Attribute Casting & Mutators

Attribute casting and mutators allow you to transform Sutando attribute values when retrieving or setting them on model instances.

Accessors & Mutators

Defining An Accessor

To define an accessor, create a method named using camelCase attribute{Attribute} on the model to represent the attribute being accessed. The name of this method matches the actual attribute representation for the model/database field.

In this example, we will define an accessor for the first_name attribute. The accessor will be automatically called by Sutando when attempting to retrieve the value of the first_name attribute:

import { BaseModel, AttributeModel } from "kawkab";
 
class User extends Model {
  attributeFirstName() {
    return AttributeModel.make({
      get: value => value.toUpperCase()
    })
  }
}

All accessor methods return an Attribute instance that defines how to access the attribute and how to mutate the attribute. In this example, we are only defining how to access the property. To do this, we provide the get parameter to the Attribute class constructor.

As you can see, the original value of the column is passed to the accessor, allowing you to manipulate the value and return it. To access the value of the accessor, you can simply access the first_name attribute on the model instance:

const user = await User.query().find(1);
 
const firstName = user.first_name;

:::tip If you want to add these computed values to the object/JSON representations of your model, you will need to append them. :::

Sometimes your accessor may need to transform multiple model attributes into a single “value object”. To do this, your accessor can accept a second attributes parameter, which will be automatically provided to the accessor and will contain an object with all of the current model’s attributes:

attributeFullName() {
  return AttributeModel.make({
    get: (value, attributes) => `${attributes.first_name} ${attributes.last_name}`
  })
}

Defining A Mutator

To define a mutator, you can provide the set parameter when defining your attribute. Let’s define a mutator for the first_name attribute. This mutator will be automatically called when we attempt to set the value of the first_name attribute on the model:

import { BaseModel, AttributeModel } from "kawkab";
 
class User extends Model {
  attributeFirstName() {
    return AttributeModel.make({
      get: value => value.toUpperCase(),
      set: value => value.toLocalLowerCase()
    })
  }
}

The mutator will receive the value being set on the attribute, allowing you to manipulate the value and set the modified value on the internal attributes property of the Sutando model. To use our mutator, we simply need to set the first_name attribute on the Sutando model:

const user = User.query().find(1);
 
user.first_name = 'Sally';

In this example, the set callback will be called with the value Sally. Then, the mutator will apply the toLocalLowerCase function to the name and set its resulting value in the model’s internal attributes.

Mutating Multiple Attributes

Sometimes your mutator may need to set multiple attributes on the underlying model. To do this, you can return an object from the set callback. Each key in the object should correspond to a base attribute/database column associated with the model:

attributeFullName() {
  return AttributeModel.make({
    get: (value, attributes) => `${attributes.first_name} ${attributes.last_name}`,
    set: (value) => ({
      first_name: value.split(' ')[0],
      last_name: value.split(' ')[1],
    }),
  });
}

Attribute Casting

Attribute casting provides similar functionality to accessors and mutators without the need to define any additional methods on your model. Instead, the casts property of the model provides a convenient way to transform attributes to common data types.

The casts property should be an object where the key is the name of the attribute being cast and the value is the type you wish to cast the column to. The supported types for casting are:

• integer int
• float double
• string
• boolean bool
• collection
• date
• datetime
• json object

To demonstrate attribute casting, let’s cast the is_admin attribute, which is stored in the database as an integer (0 or 1), to a boolean value:

import { BaseModel } from "kawkab";
 
class User extends Model {
  // The attributes that should be cast.
  casts = {
    is_admin: 'boolean',
  };
}

After defining the cast, the is_admin attribute will always be cast to a boolean when accessed, even though the underlying value is stored in the database as an integer:

const user = await User.query().find(1);
 
if (user.is_admin) {
  // ...
}

:::tip You should never define a cast (or attribute) that has the same name as a relationship or set a cast for the model’s primary key. :::

JSON Casting

JSON casting is particularly useful when working with columns that are stored as JSON strings. For example, if your database has a JSON or TEXT field type containing serialized JSON, adding a JSON cast to that attribute will automatically unserialize the attribute when accessing it on your model:

import { BaseModel } from "kawkab";
 
class User extends Model {
    // The attributes that should be cast.
    casts = {
      options: 'json',
    };
}

Once the cast is defined, you can access the options attribute and it will automatically be unserialized from JSON to an object. When setting the value of the options attribute, the given object will automatically be serialized back to JSON for storage:

import { BaseModel } from "kawkab";
 
const user = await User.query().find(1);
 
const options = user.options;
 
options.key = value;
 
user.options = options;
 
await user.save();

:::tip Direct modifications to the attributes themselves will not update the model’s data, so the following usage is incorrect:

const user = await User.query().find(1);
 
user.options.key = value;

:::

Date Casting

By default, Sutando will cast the created_at and updated_at columns to Date instances. You can cast additional date attributes by defining additional date casts within your model’s casts property. Typically, dates should be cast using the datetime cast type.

When defining a date or datetime cast, you can also specify the date format. This format will be used when serializing the model to an object or JSON:

casts = {
  created_at: 'datetime:YYYY-MM-DD',
};

You can customize the default serialization format for all of your model’s dates by defining a serializeDate method on your model. This method does not affect how your dates are formatted for storage in your database:

const dayjs = require('dayjs');
 
class User extends Model {
  serializeDate(date) {
    return dayjs(date).format('YYYY-MM-DD');
  }
}

To specify the format that should be used when actually storing your model’s dates within your database, you should define a dateFormat property on your model:

class User extends Model {
  dateFormat = 'X'
}

List of all available formats

Date Casting, Serialization, & Timezones

By default, date and datetime casts will serialize dates to a UTC ISO-8601 date string (2012-12-12T12:25:36.000000Z), regardless of the timezone specified in your application’s timezone configuration option.

If a custom format is applied to a date or datetime cast, such as datetime:YYYYY-MM-DD HH:mm:ss, the UTC timezone will be used while serializing the date.

Custom Casts

Sutando includes a variety of built-in, useful cast types; however, you may sometimes need to define your own cast types. All custom cast classes extend CastsAttributes. Classes implementing this interface should define get and set methods. The get method is responsible for transforming a raw value from the database to a cast value, while the set method should transform the cast value to a raw value that can be stored in the database. As an example, let’s recreate the built-in json cast type as a custom cast type:

// casts/json.js
const { Model, CastsAttributes } from "kawkab";
 
class Json extends CastsModel {
  // Transform the given value.
  static get(model, key, value, attributes) {
    try {
      return JSON.parse(value);
    } catch (e) {
      return null;
    }
  }
 
  // Prepare the given value for storage.
  static set(model, key, value, attributes) {
    return JSON.stringify(value);
  }
}

Once a custom cast type is defined, you may attach it to a model attribute using its class:

const Json = require('./casts/json');
 
class User extends Model {
  // The attributes that should be cast.
  casts = {
    options: Json,
  };
}