Lux

Model

Source:src/packages/database/model/index.js:31

Properties

.tableName:String
Source:src/packages/database/model/index.js:553
The name of the corresponding database table for the model.

.hasOne:Object

Source:src/packages/database/model/index.js:117

An object where you declare hasOne relationships.

When declaring a relationship you must specify the inverse of the relationship.

class User extends Model {
  static hasOne = {
    profile: {
      inverse: 'user'
      // The line above lets Lux know that this relationship is accessible
      // on profile instances via `profile.user`.
    }
  };
}

class Profile extends Model {
  static belongsTo = {
    user: {
      inverse: 'profile'
      // The line above lets Lux know that this relationship is accessible
      // on user instances via `user.profile`.
    }
  };
}

If the name of the model is different than the key of the relationship, you must specify it in the relationship object.

class Profile extends Model {
  static belongsTo = {
    owner: {
      inverse: 'profile',
      model: 'user'
      // The line above lets Lux know that this is a relationship with the
      // `User` model and not a non-existent `Owner` model.
    }
  };
}

.hasMany:Object

Source:src/packages/database/model/index.js:169

An object where you declare hasMany relationships.

When declaring a relationship you must specify the inverse of the relationship.

class Author extends Model {
  static hasMany = {
    books: {
      inverse: 'author'
      // The line above lets Lux know that this relationship is accessible
      // on book instances via `book.author`.
    }
  };
}

class Book extends Model {
  static belongsTo = {
    author: {
      inverse: 'books'
      // The line above lets Lux know that this relationship is accessible
      // on author instances via `author.books`.
    }
  };
}

If the name of the model is different than the key of the relationship, you must specify it in the relationship object.

class Author extends Model {
  static hasMany = {
    publications: {
      inverse: 'author',
      model: 'book'
      // The line above lets Lux know that this is a relationship with the
      // `Book` model and not a non-existent `Publication` model.
    }
  };
}

In the examples above there is only one owner of relationship. Sometimes we need to express a many to many relationship. Typically in relational databases, this is done with a join table. When declaring a many to many relationship that uses a join table, you must specify the join model.

class Categorization extends Model {
  static belongsTo = {
    tag: {
      inverse: 'categorization'
    },
    post: {
      inverse: 'categorization'
    }
  }
}

class Tag extends Model {
  static hasMany = {
    posts: {
      inverse: 'tags',
      through: 'categorizations'
    }
  };
}

class Post extends Model {
  static hasMany = {
    tags: {
      inverse: 'posts',
      through: 'categorizations'
    }
  };
}

.validates:Object
Source:src/packages/database/model/index.js:326
An object where you declare validations for an instance's attributes.
Before a model instance is saved, validations declared in this block are executed. To declare a validation for a model attribute, simply add the attribute name as a key to the validates object. The value for the attribute key should be a function that takes a single argument (the value to validate against) and return a boolean value represent whether or not the attribute is valid.
```
class User extends Model {
  static validates {
    username: value => /^\w{2,30}$/.test(value),
    password: value => String(value).length >= 8
  };
}
```
In the spirit of have a small api surface area, Lux provides no validation helper functions. You can roll your own helpers with or use one of the many excellent validation libraries like validator.
```
import { isEmail } from 'validator';

class User extends Model {
  static validates {
    email: isEmail
  };
}
```
.logger:Logger
Source:src/packages/database/model/index.js:543
A reference to the application's logger.
#createdAt:Date
Source:src/packages/database/model/index.js:64
A timestamp representing when the Model instance was created.
.resourceName:String
Source:src/packages/database/model/index.js:573
The name of the resource the model represents.
.primaryKey:String
Source:src/packages/database/model/index.js:583
The column name to use for a model's primary key.

.belongsTo:Object

Source:src/packages/database/model/index.js:259

An object where you declare belongsTo relationships.

When declaring a relationship you must specify the inverse of the relationship.

class Book extends Model {
  static belongsTo = {
    author: {
      inverse: 'books'
      // The line above lets Lux know that this relationship is accessible
      // on author instances via `author.books`.
    }
  };
}

class Author extends Model {
  static hasMany = {
    books: {
      inverse: 'book'
      // The line above lets Lux know that this relationship is accessible
      // on book instances via `book.author`.
    }
  };
}

If the name of the model is different than the key of the relationship, you must specify it in the relationship object.

class Book extends Model {
  static belongsTo = {
    writer: {
      inverse: 'books',
      model: 'author'
      // The line above lets Lux know that this is a relationship with the
      // `Author` model and not a non-existent `Writer` model.
    }
  };
}

Sometimes our foreign keys in the database do not follow conventions (i.e author_id). You have the option to manually specify foreign keys when a situation like this occurs.

class Book extends Model {
  static belongsTo = {
    author: {
      inverse: 'books',
      foreignKey: 'SoMe_UnCoNvEnTiOnAl_FoReIgN_KeY'
    }
  };
}

#dirtyAttributes:Map
Source:src/packages/database/model/index.js:796
#dirtyRelationships:Map
Source:src/packages/database/model/index.js:820

.scopes:Object

Source:src/packages/database/model/index.js:367

An object where you declare custom query scopes for the model.

Scopes allow you to DRY up query logic by chaining custom set's of queries with built-in query method such as where, not, page, etc. To declare a scope, add it as a method on the scopes object.

class Post extends Model {
  static hasMany = {
    tags: {
      inverse: 'posts'
    },
    comments: {
      inverse: 'post'
    }
  };

  static belongsTo = {
    user: {
      inverse: 'posts'
    }
  };

  static scopes = {
    isPublic() {
      return this.where({
        isPublic: true
      });
    },

    byUser(user) {
      return this.where({
        userId: user.id
      });
    },

    withEverything() {
      return this.includes('tags', 'user', 'comments');
    }
  };
}

Given the scopes declared in the example above, here is how we could return all the public posts with relationships eager loaded for the user with the id of 1.

const user = await User.find(1);

return Post
  .byUser(user)
  .isPublic()
  .withEverything();

Since scopes can be chained with built-in query methods, we can easily paginate this collection.

const user = await User.find(1);

return Post
  .byUser(user)
  .isPublic()
  .withEverything()
  .page(1);

.hooks:Object
Source:src/packages/database/model/index.js:445
An object where you declare hooks to execute at certain times in a model instance's lifecycle.
There are many lifecycle hooks that are executed through out a model instance's lifetime. The have many use cases such as sanitization of attributes, creating dependent relationships, hashing passwords, and much more.
Execution Order
When creating a record.
1. beforeValidation
2. afterValidation
3. beforeCreate
4. beforeSave
5. afterCreate
6. afterSave
When updating a record.
1. beforeValidation
2. afterValidation
3. beforeUpdate
4. beforeSave
5. afterUpdate
6. afterSave
When deleting a record.
1. beforeDestroy
2. afterDestroy
Anatomy
Hooks are async functions that are called with two arguments. The first argument is the record that the hook applies to and the second argument is the transaction object relevant to the method from which the hook was called.
The only time you will need to use the transaction object is if you are creating, updating, or deleting different record(s) within the hook. Using the transaction object when modifying the database in a hook ensures that any modifications made within the hook will be rolled back if the function that initiated the transaction fails.
```
import Notification from 'app/models/notification';

class Comment extends Model {
  static belongsTo = {
    post: {
      inverse: 'comments'
    },
    user: {
      inverse: 'comments'
    }
  };

  static hooks = {
    async afterCreate(comment, trx) {
      let [post, commenter] = await Promise.all([
        comment.post,
        comment.user
      ]);

      const commentee = await post.user;

      post = post.title;
      commenter = commenter.name;

      // Calling .transacting(trx) prevents the commentee from getting a
      // notification if the comment fails to be persisted in the database.
      await Notification
        .transacting(trx)
        .create({
          user: commentee,
          message: `${commenter} commented on your post "${post}"`
        });
    },

    async afterSave() {
      // Good thing you called transacting in afterCreate.
      throw new Error('Fatal Error');
    }
  };
}
```

#isDirty:Boolean

Source:src/packages/database/model/index.js:730

Indicates if the model is dirty.

import Post from 'app/models/post';

Post
 .find(1)
 .then(post => {
    post.isDirty;
    // => false

    post.isPublic = true;

    post.isDirty;
    // => true

    return post.save();
  })
  .then(post => {
    post.isDirty;
    // => false
  });

#isNew:Boolean

Source:src/packages/database/model/index.js:697

Indicates if the model is new.

import Post from 'app/models/post';

let post = new Post({
  body: '',
  title: 'New Post',
  isPublic: false
});

post.isNew;
// => true

Post.create({
  body: '',
  title: 'New Post',
  isPublic: false
}).then(post => {
  post.isNew;
  // => false;
});

.modelName:String
Source:src/packages/database/model/index.js:563
The canonical name of the model.
#modelName:String
Source:src/packages/database/model/index.js:46
The canonical name of a Model's constructor.

#persisted:Boolean

Source:src/packages/database/model/index.js:763

Indicates if the model is persisted.

import Post from 'app/models/post';

Post
 .find(1)
 .then(post => {
    post.persisted;
    // => true

    post.isPublic = true;

    post.persisted;
    // => false

    return post.save();
  })
  .then(post => {
    post.persisted;
    // => true
  });

#resourceName:String
Source:src/packages/database/model/index.js:55
The name of the API resource a Model instance's constructor represents.
#tableName:String
Source:src/packages/database/model/index.js:36
The name of the corresponding database table for a Model instance's constructor.
#updatedAt:Date
Source:src/packages/database/model/index.js:73
A timestamp representing the last time the Model instance was updated.

Methods

.isInstance(value):Boolean
Source:src/packages/database/model/index.js:1396
Check if a value is an instance of a model.
Parameters
- value: Any
  The value in question.
Return Value
Boolean
.hasScope(name):Boolean
Source:src/packages/database/model/index.js:1383
Check if a model has a scope.
Parameters
- name: String
  The name of the scope to look for.
Return Value
Boolean
.transaction(fn):Promise
Source:src/packages/database/model/index.js:1262
Manually begin a new transaction.
Most of the time, you don't need to start transactions yourself. However, the transaction method can be useful if you need to do something like bulk creating records.
```
await Post.transaction(trx => {
  return Promise.all([
    Post.transacting(trx).create({
      // ...props
    }),
    Post.transacting(trx).create({
      // ...props
    })
  ]);
});
```
Parameters
- fn: Function
  The function used for executing the tranasction. This function is called with a new transaction object as it's only argument and is expected to return a promise.
Return Value
Promise
Resolves with the resolved value of the fn param.
.transacting(transaction):Model
Source:src/packages/database/model/index.js:1224
Specify the transaction object to use for following save, update, or destroy method calls.
When you call a method like update or destroy, lux will create a transaction and wrap the internals of the method and other downstream method calls like model hooks within. In some edge cases it can be more useful to manually initiate the transaction. Bulk updating or destroying are good examples of this. When you manually begin a transaction, you can call this method to specify the transaction object that you would like to use for calls to the static create method so lux knows not to automatically begin a new transaction if/when the static create method is called.
```
// This call to create uses the transaction that lux will initiate.
await Post.create();

await Post.transaction(trx => {
  // This call to create uses the transaction that we created with the
  // call to the transaction method.
  return Post
    .transacting(trx)
    .create();
});
```
Parameters
- transaction: Transaction
  A transaction object to forward to create method calls.
Return Value
Model
Returns a proxied version of this that delagates the transaction param to subsquent create method calls.
.create(properties):Promise
Source:src/packages/database/model/index.js:1152
Create and persist a new instance of the model.
Parameters
- properties: Object
  An object containing key, value pairs of the attributes and/or relationships you would like to assign to the instance.
Return Value
Promise
Resolves with the newly created model.
#destroy():Promise
Source:src/packages/database/model/index.js:1072
Permanently delete the instance from the database.
Parameters
Return Value
Promise
Resolves with this.
#reload():Promise
Source:src/packages/database/model/index.js:1097
Reload the record from the database.
Parameters
Return Value
Promise
Resolves with this.
#rollback():Model
Source:src/packages/database/model/index.js:1112
Rollback attributes and relationships to the last known persisted set of values.
Parameters
Return Value
Model
Returns this.

#save():Promise

Source:src/packages/database/model/index.js:955

Persist any unsaved changes to the database.

const post = await Post.first();

console.log(post.title, post.isDirty);
// => 'New Post' false

post.title = 'How to Save a Lux Model';

console.log(post.title, post.isDirty);
// => 'How to Update a Lux Model' true

await post.save();

console.log(post.title, post.isDirty);
// => 'How to Save a Lux Model' false

Parameters

Return Value

Promise

Resolves with this.

#transacting(transaction):Model
Source:src/packages/database/model/index.js:877
Specify the transaction object to use for following save, update, or destroy method calls.
When you call a method like update or destroy, lux will create a transaction and wrap the internals of the method and other downstream method calls like model hooks within. In some edge cases it can be more useful to manually initiate the transaction. Bulk updating or destroying are good examples of this. When you manually begin a transaction, you can call this method to specify the transaction object that you would like to use for subsequent mutation methods (save, update, destroy, etc.) so lux knows not to automatically begin a new transaction if/when a mutation method is called.
```
const post = await Post.first();

// This call to update uses the transaction that lux will initiate.
await post.update({
  // updates to post...
});

await post.transaction(trx => {
  // This call to update uses the transaction that we created with the
  // call to the transaction method.
  return post
    .transacting(trx)
    .update({
      // updates to post...
    });
});
```
Parameters
- transaction: Transaction
  A transaction object to forward to save, update, or destroy method calls.
Return Value
Model
Returns a proxied version of this that delagates the transaction param to subsquent save, update, or destroy method calls.
#transaction(fn):Promise
Source:src/packages/database/model/index.js:921
Manually begin a new transaction.
Most of the time, you don't need to start transactions yourself. However, if you need to do something like implement bulk updating of related records the transaction method can be useful.
```
const post = await Post.first().include('user');
const user = await post.user;

await post.transaction(trx => {
  return Promise.all([
    post.transacting(trx).update({
      // updates to post...
    }),
    user.transacting(trx).update({
      // updates to user...
    })
  ]);
});
```
Parameters
- fn: Function
  The function used for executing the tranasction. This function is called with a new transaction object as it's only argument and is expected to return a promise.
Return Value
Promise
Resolves with the resolved value of the fn param.
#update(properties):Promise
Source:src/packages/database/model/index.js:983
Assign values to the instance and persist any changes to the database.
```
const post = await Post.first();

console.log(post.title, post.isPublic, post.isDirty);
// => 'New Post' false false

await post.update({
  title: 'How to Update a Lux Model',
  isPublic: true
});

console.log(post.title, post.isPublic, post.isDirty);
// => 'How to Update a Lux Model' true false
```
Parameters
- properties: Object
  An object containing key, value pairs of the attributes and/or relationships you would like to assign to the instance.
Return Value
Promise
Resolves with this.