Skip to content

Mutators & Casting

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:

js
const { Model, Attribute } = require('sutando');

class User extends Model {
  attributeFirstName() {
    return Attribute.make({
      get: value => value.toUpperCase()
    })
  }
}
const { Model, Attribute } = require('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:

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

TIP

If you would like these computed values to be added 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 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:

js
attributeFullName() {
  return Attribute.make({
    get: (value, attributes) => `${attributes.first_name} ${attributes.last_name}`
  })
}
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:

js
const { Model, Attribute } = require('sutando');

class User extends Model {
  attributeFirstName() {
    return Attribute.make({
      get: value => value.toUpperCase(),
      set: value => value.toLocalLowerCase()
    })
  }
}
const { Model, Attribute } = require('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:

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

user.first_name = 'Sally';
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:

js
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],
    }),
  });
}
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:

js
const { Model } = require('sutando');

class User extends Model {
  // The attributes that should be cast.
  casts = {
    is_admin: 'boolean',
  };
}
const { Model } = require('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:

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

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

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

TIP

You should never define a cast (or an attribute) that has the same name as a relationship or assign a cast to the model's primary key.

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:

js
const { Model } = require('sutando');

class User extends Model {
    // The attributes that should be cast.
    casts = {
      options: 'json',
    };
}
const { Model } = require('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:

js
const { Model } = require('sutando');

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

const options = user.options;

options.key = value;

user.options = options;

await user.save();
const { Model } = require('sutando');

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

const options = user.options;

options.key = value;

user.options = options;

await user.save();

TIP

Directly modifying the attributes itself cannot update the model data, so the following usage is incorrect:

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

user.options.key = value;
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 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:

js
casts = {
  created_at: 'datetime:YYYY-MM-DD',
};
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:

js
const dayjs = require('dayjs');

class User extends Model {
  serializeDate(date) {
    return dayjs(date).format('YYYY-MM-DD');
  }
}
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 a model's dates within your database, you should define a dateFormat property on your model:

js
class User extends Model {
  dateFormat = 'X'
}
class User extends Model {
  dateFormat = 'X'
}

List of all available formats

FormatOutputDescription
YY18Two-digit year
YYYY2018Four-digit year
M1-12The month, beginning at 1
MM01-12The month, 2-digits
MMMJan-DecThe abbreviated month name
MMMMJanuary-DecemberThe full month name
D1-31The day of the month
DD01-31The day of the month, 2-digits
d0-6The day of the week, with Sunday as 0
ddSu-SaThe min name of the day of the week
dddSun-SatThe short name of the day of the week
ddddSunday-SaturdayThe name of the day of the week
H0-23The hour
HH00-23The hour, 2-digits
h1-12The hour, 12-hour clock
hh01-12The hour, 12-hour clock, 2-digits
m0-59The minute
mm00-59The minute, 2-digits
s0-59The second
ss00-59The second, 2-digits
SSS000-999The millisecond, 3-digits
Z+05:00The offset from UTC, ±HH:mm
ZZ+0500The offset from UTC, ±HHmm
AAM PM
aam pm
Q1-4Quarter
Do1st 2nd ... 31stDay of Month with ordinal
k1-24The hour, beginning at 1
kk01-24The hour, 2-digits, beginning at 1
X1360013296Unix Timestamp in second
x1360013296123Unix Timestamp in millisecond

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:

js
// casts/json.js
const { Model, CastsAttributes } = require('sutando');

class Json extends CastsAttributes {
  // Cast the given value.
  get(model, key, value, attributes) {
    try {
      return JSON.parse(value);
    } catch (e) {
      return null;
    }
  }

  // Prepare the given value for storage.
  set(model, key, value, attributes) {
    return JSON.stringify(value);
  }
}
// casts/json.js
const { Model, CastsAttributes } = require('sutando');

class Json extends CastsAttributes {
  // Cast the given value.
  get(model, key, value, attributes) {
    try {
      return JSON.parse(value);
    } catch (e) {
      return null;
    }
  }

  // Prepare the given value for storage.
  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:

js
const Json = require('./casts/json');

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

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

Released under the MIT License. (dev)