Mutators

Table of Contents

Getters and setters provide many benefits, including the ability to transform your data before saving and retrieving from a database.

In this guide, we learn when and where to use getters, setters and computed properties (also known as accessors and mutators).

Getters

Getters are called when retrieving a value from a model instance.

They are often used to transform model data for display.

For example, converting a Post title to title case:

app/Models/Post.js
'use strict'

const Model = use('Model')

class Post extends Model {
  getTitle (title) {
    return title.replace(/^(.)|\s(.)/g, ($1) => {
      return $1.toUpperCase()
    })
  }
}
const post = await Post.find(postId)

// getters are called automatically
return post.toJSON()

In the example above, assuming the Post title is saved as a title field in the database, AdonisJs executes the getTitle method and uses the returned value when post.title is referenced.

  • Getters always start with the get keyword followed by the camel case version of the field name (e.g. field_namegetFieldName).

  • A getter’s return value is used instead of the actual database field name value when that field is referenced on a model instance.

  • Getters are automatically evaluated when you call toJSON on a model instance or serializer instance.

  • As getters are synchronous, you cannot run asynchronous code inside them (for asynchronous functionality, use hooks).

Setters

Setters are called when assigning a value to a model instance.

They are often used to normalize data before saving to a database:

app/Models/User.js
'use strict'

const Model = use('Model')

class User extends Model {
  setAccess (access) {
    return access === 'admin' ? 1 : 0
  }
}

const user = new User()
user.access = 'admin'

console.log(user.access) // will return 1
await user.save()
  • Setters always starts with the set keyword followed by the camel case version of the field name.

  • A setter executes when you set/update the value of the given field on the model instance.

  • Setters receive the current value of a given field to parse before assignment.

  • As setters are synchronous, you cannot run asynchronous code inside them (for asynchronous functionality, use hooks).

Computed Properties

Computed properties are virtual values which only exist in a model instance’s JSON representation.

To create a computed fullname property from a User first/last name:

app/Models/User.js
'use strict'

const Model = use('Model')

class User extends Model {
  static get computed () {
    return ['fullname']
  }

  getFullname ({ firstname, lastname }) {
    return `${firstname} ${lastname}`
  }
}

In the example above, when toJSON is called on the User instance, a fullname property gets added to the return value:

const user = await User.find(1)

const json = user.toJSON()
console.log(json.fullname) // firstname + lastname
  • All computed property names (e.g. fullname) must be returned in an array from the model class static computed getter.

  • Computed property method definitions are prefixed with get, the same as getter method definitions (e.g. getFullname).

  • Computed properties receive an object of existing model attributes for use in their method definitions.