Mutators & Casting

Accessors and mutators transform attribute values as you get or set them on a model, including casts to dates, JSON, and custom classes.

Accessors, mutators allow you to transform Sutando attribute values when you retrieve or set them on model instances.

Accessors & Mutators

Defining An Accessor

To define an accessor, create a camelCase named attribute{Attribute} method in the model to represent the accessible attribute. This method name corresponds to the representation of the real underlying model attribute/database field.

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

import { Model, Attribute } from 'sutando';

class User extends Model {
  attributeFirstName() {
    return Attribute.make({
      get: value => value.toUpperCase()
    })
  }
}

All accessor methods return an Attribute instance that defines how to access the attribute and how to change the attribute. In this example we only define 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 and return the value. To access the value of the accessor, you may simply access the first_name attribute on a model instance:

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

Sometimes your accessor may need to transform multiple model attributes into a single “value object”. To do so, your get closure may accept a second argument of attributes, which will be automatically supplied to the closure and will contain a object of all of the model’s current attributes:

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

Defining A Mutator

To define a mutator, you may provide the set argument 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 { Model, Attribute } from 'sutando';

class User extends Model {
  attributeFirstName() {
    return Attribute.make({
      get: value => value.toUpperCase(),
      set: value => value.toLocalLowerCase()
    })
  }
}

The mutator will receive the value that is being set on the attribute, allowing you to manipulate the value and set the manipulated value on the Sutando model’s internal attributes property. To use our mutator, we only need to set the first_name attribute on an 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. The mutator will then 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 so, you may return a object from the set closure. Each key in the object should correspond with an underlying attribute / database column associated with the model:

attributeFullName() {
  return Attribute.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 functionality similar to accessors and mutators without requiring you to define any additional methods on your model. Instead, your model’s casts property provides a convenient method of converting attributes to common data types.

The casts property should be a obejct 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 cast types 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 our database as an integer (0 or 1) to a boolean value:

import { Model } from 'sutando';

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 you access it, even if the underlying value is stored in the database as an integer:

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

if (user.is_admin) {
  // ...
}

JSON Casting

The json cast is particularly useful when working with columns that are stored as serialized JSON. For example, if your database has a JSON or TEXT field type that contains serialized JSON, adding the json cast to that attribute will automatically deserialize the attribute when you access it on your model:

import { Model } from 'sutando';

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

Once the cast is defined, you may access the options attribute and it will automatically be deserialized from JSON into a object. When you set the value of the options attribute, the given object will automatically be serialized back into JSON for storage:

import { Model } from 'sutando';

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

const options = user.options;

options.key = value;

user.options = options;

await user.save();

Date Casting

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

When defining a date or datetime cast, you may also specify the date’s format. This format will be used when the model is serialized to a object or JSON:

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

You may 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 the database:

import dayjs from '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 a 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, the 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 the date or datetime cast, such as datetime:YYYYY-MM-DD HH:mm:ss, the UTC timezone will be used during date serialization.

Custom Casts

Sutando has a variety of built-in, helpful cast types; however, you may occasionally need to define your own cast types. All custom cast classes extend the CastsAttributes. Classes that implement this interface must define a get and set method. The get method is responsible for transforming a raw value from the database into a cast value, while the set method should transform a cast value into a raw value that can be stored in the database. As an example, we will re-implement the built-in json cast type as a custom cast type:

// casts/json.js
import { Model, CastsAttributes } from 'sutando';

class Json extends CastsAttributes {
  // Cast 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 you have defined a custom cast type, you may attach it to a model attribute using its class:

import Json from './casts/json';

class User extends Model {
  // The attributes that should be cast.
  casts = {
    options: Json,
  };
}