Models

KawkabJS models are built on the active record pattern.

Kawkab’s data model layer makes it very easy to implement CRUD operations and manage relationships between models.

We recommend using models extensively and resorting to the standard query builder for special use cases.

Creating Your First Model

Let’s take a look at a basic model class and discuss some of the main conventions in Kawkab:

const { Model } = "kawkab";
 
class Flight extends Model {
  //
}

Table Names

After looking at the example above, you might have noticed that we did not tell Kawkab which database table matches our Flight model. By convention, the plural name of the class in snake case will be used as the table name unless another name is explicitly specified. Therefore, in this case, Kawkab will assume that the Flight model stores records in a flights table, while an AirTrafficController model would store records in an air_traffic_controllers table.

If the database table for your model does not follow this convention, you may explicitly specify the model’s table name by defining a table property on the model:

import { BaseModel } from "kawkab";
 
class Flight extends Model {
  // The table associated with the model.
  table = 'my_flights';
}

Primary Keys

Kawkab will also assume that each database table has a primary key column named id. If necessary, you may define a protected primaryKey property on your model to specify a different column that should serve as the model’s primary key:

import { BaseModel } from "kawkab";
 
class Flight extends Model {
  // The primary key associated with the table.
  primaryKey = 'flight_id';
}

If you wish to use a non-incrementing or non-numeric primary key, you should define an incrementing property on your model which is set to false:

class Flight extends Model {
  // Indicates if the model's ID is auto-incrementing.
  incrementing = false;
}

If your model’s primary key is not an integer, you should define a keyType property on your model. This property should contain a string value:

class Flight extends Model {
  // The data type of the auto-incrementing ID.
  keyType = 'string';
}

Timestamps

By default, Sutando expects created_at and updated_at columns to exist on your model’s corresponding database table. Sutando will automatically set the values of these columns when models are created or updated. If you do not want these columns to be managed automatically by Sutando, you should define a timestamps property on your model with a value of false:

import { BaseModel } from "kawkab";
 
class Flight extends Model {
  // Indicates if the model should be timestamped.
  timestamps = false;
}

If you need to customize the names of the columns used to store the timestamps, you can set CREATED_AT and UPDATED_AT properties on your model:

import { BaseModel } from "kawkab";
 
class Flight extends Model {
  static CREATED_AT = 'creation_date';
  static UPDATED_AT = 'updated_date';
}

Database Connections

By default, all Sutando models will use the default database connection configured for your application. If you would like to specify a different connection to be used when interacting with a given model, you should define a connection property on the model:

import { BaseModel } from "kawkab";
 
class Flight extends Model {
  connection = 'sqlite';
}

Default Attribute Values

By default, a newly created model instance will not have any attribute values. If you would like to specify default values for some of your model’s attributes, you may define an attributes property on the model. The attribute values placed in attributes should be in their raw, “storage-ready” form as if they were just read from the database:

import { BaseModel } from "kawkab";
 
class Flight extends Model {
  attributes = {
    options: '[]',
    delayed: false,
  };
}

Retrieving Models

Once you have created a model and its associated database table, you are ready to start retrieving data from your database. You may think of each Sutando model as a powerful query builder allowing you to fluently query the database table associated with the model. The all method of the model will retrieve all records from the model’s associated database table:

const { Flight } = require('./models');
 
const flights = await Flight.query().all();
 
flights.map(flight => {
  console.log(flight.name)
})

Building Queries

The Sutando all method will retrieve all of the results in the model’s table. However, since every Sutando model serves as a query builder, you may add additional constraints to the queries, and then use the get/first/find method to retrieve the results:

const flights = await Flight.query().where('active', 1)
  .orderBy('name')
  .take(10)
  .get();
 
const flight = await Flight.query().where('active', 1).first();
 
const flight = await Flight.query().find(5);

Updating Models

If you already have a Sutando model instance retrieved from the database, you can “refresh” the model using the fresh and refresh methods. The fresh method will retrieve a fresh model instance from the database. The current model instance will be unaffected:

const flight = await Flight.query().where('number', 'FR 900').first();
 
const freshFlight = await flight.fresh();

The refresh method will re-populate the current model using fresh data from the database. Additionally, all loaded relationships will be refreshed as well:

const flight = await Flight.query().where('number', 'FR 900').first();
 
flight.number = 'FR 456';
 
await flight.refresh();
 
flight.number; // "FR 900"

Collections

As we saw, Sutando methods like all and get retrieve multiple records from the database. However, these methods do not return a plain array. Instead, an instance of Collection is returned.

The Sutando Collection class extends the collect.js class, which provides a variety of useful methods for interacting with collections of data. For example, the reject method may be used to remove models from the collection based on the result of a closure:

const flights = await Flight.query().where('destination', 'Paris').get();
 
const newFlights = flights.reject(flight => {
  return flight.cancelled;
});

In addition to the methods provided by the base collect.js collection class, the Sutando collection class provides a few additional methods that are specifically tailored for interacting with collections of Sutando models.

Since all Sutando collections implement JavaScript’s iterable interfaces, you may loop over the collections as if they were an array:

for (let flight of flights) {
  console.log(flight.name);
}

Chunking Results

If you need to process thousands of Sutando records, you may run into memory issues if you attempt to load them all at once via the all or get methods. Instead of using these methods, you may use the chunk method.

The chunk method will retrieve a subset of Sutando models, passing them to a closure for processing. Since only the current chunk of Sutando models is retrieved at any one time, the chunk method will provide significantly lower memory usage when working with a large number of models:

const { Flight } = require('./models');
 
await Flight.query().chunk(200, flights => {
  flights.map(flight => {
    //
  });
});

Retrieving Single Models / Aggregates

In addition to retrieving all records that match a given query, you may also retrieve single records using the find or first methods. Instead of returning a collection of models, these methods return a single model instance:

const { Flight } = require('./modles');
 
// Retrieve a model by its primary key...
const flight = await Flight.query().find(1);
 
// Retrieve the first model matching the query constraints...
const flight = await Flight.query().where('active', 1).first();

Retrieving Or Creating Models

The firstOrCreate method will attempt to locate a database record using the given column / value pairs. If the model cannot be found in the database, a record will be inserted with the attributes resulting from merging the first argument with the optional second argument:

The firstOrNew method, like firstOrCreate, will attempt to locate a record in the database matching the given attributes. However, if a model is not found, a new model instance will be returned. Note that the model returned by firstOrNew has not yet been saved to the database. You will need to manually call the save method to save it:

const { Flight } = require('./modles');
 
// Retrieve the flight by name or create it if it doesn't exist...
const flight = await Flight.query().firstOrCreate({
  name: 'London to Paris'
});
 
// Retrieve the flight by name or create it with the name, delayed, and arrival time...
const flight = await Flight.query().firstOrCreate(
  { name: 'London to Paris' },
  { delayed: 1, arrival_time: '11:30' }
);
 
// Retrieve the flight by name or create a new flight instance...
const flight = await Flight.query().firstOrNew({
  name: 'London to Paris'
});
 
// Retrieve the flight by name or create it with the name, delayed, and arrival time...
const flight = await Flight.query().firstOrNew(
  { name: 'Tokyo to Sydney' },
  { delayed: 1, arrival_time: '11:30' }
);

Retrieving Aggregates

When interacting with Sutando models, you may also use the count, sum, max, and other aggregate methods provided by the query builder. As you might expect, these methods return a single aggregate value instead of a Sutando model instance:

const count = await Flight.query().where('active', 1).count(); // 100
 
const max = await Flight.query().where('active', 1).max('price'); // 104
 
const flight = await Flight.query().find(1); // flight instanceof Flight

Inserting & Updating Models

Inserts

Of course, when using Sutando, we don’t just need to retrieve models from the database. We also need to insert new records. Luckily, Sutando makes it simple. To insert a new record into the database, you should create a new model instance and set the attributes on the model. Then, call the save method on the model instance:

const { Flight } = require('./model');
 
  const flight = new Flight;
  flight.name = req.name;
  await flight.save();
 
  res.send(flight);

In this example, we are setting the name field from the incoming HTTP request to the name attribute of the Flight model instance. When we call the save method, a record will be inserted into the database. The created_at and updated_at timestamps will be automatically set when the save method is called, so there is no need to set them manually.

Alternatively, you may use the create method to “save” a new model using a single PHP statement. The inserted model instance will be returned by the create method:

const { Flight } = require('./model');
 
const flight = await Flight.query().create({
  name: 'London to Paris',
});

Updates

The save method may also be used to update models that already exist in the database. To update a model, you should retrieve it and set any attributes you wish to update. Then, you should call the model’s save method. Again, the updated_at timestamp will be automatically updated, so there is no need to set its value manually:

const { Flight } = require('./model');
 
const flight = await Flight.query().find(1);
flight.name = 'Paris to London';
await flight.save();

Mass Updates

Updates can also be performed against any model matching a given query. In this example, all flights that are active and have a destination of San Diego will be marked as delayed:

await Flight.query().where('active', 1)
  .where('destination', 'San Diego')
  .update({
    delayed: 1,
  });

The update method expects an array of column and value pairs representing the columns that should be updated. The update method returns the number of affected rows.

:::tip When issuing a mass update, the saving, saved, updating, and updated model events will not be fired for the updated models. This is because the models are not actually retrieved when issuing a mass update. :::

Checking Attribute Changes

Sutando provides isDirty methods to inspect the internal state of your model and determine how its attributes have changed from when the model was originally retrieved.

The isDirty method determines if any attributes have been changed since the model was retrieved. You may pass a specific attribute name or an array of attributes to the isDirty method to determine if any of the attributes are “dirty”. This method also accepts an optional attribute parameter:

const { Flight } = require('./model');
 
const user = await User.query().create({
  first_name: 'Taylor',
  last_name: 'Otwell',
  title: 'Developer',
});
 
user.title = 'Painter';
 
user.isDirty(); // true
user.isDirty('title'); // true
user.isDirty('first_name'); // false
user.isDirty(['first_name', 'title']); // true
 
await user.save();
 
user.isDirty(); // false

Upserts

Sometimes you may need to update an existing model or create a new model if none exists. Like the firstOrCreate method, the updateOrCreate method will save the model, so there is no need to call the save method manually.

In the example below, if there is already a flight with a departure of Oakland and a destination of San Diego, the price and discounted columns will be updated. If no such flight exists, a new flight will be created with the attributes resulting from merging the first argument’s object with the second argument’s object:

const flight = await Flight.query().updateOrCreate(
  {
    departure: 'Oakland',
    destination: 'San Diego'
  },
  {
    price: 99,
    discounted: 1
  }
);

Deleting Models

To delete a model, you may call the delete method on a model instance:

const { Flight } = require('./models');
 
const flight = await Flight.query().find(1);
await flight.delete();

Deleting An Existing Model By Its Primary Key

In the example above, we are retrieving the model from the database before calling the delete method. However, if you know the primary key of the model, you may delete the model without explicitly retrieving it by calling the destroy method. In addition to accepting a single primary key, the destroy method will accept multiple primary keys, an array of primary keys, or a Collection of primary keys:

await Flight.query().destroy(1);
 
await Flight.query().destroy(1, 2, 3);
 
await Flight.query().destroy([1, 2, 3]);

Deleting Models By Query

Of course, you may build a Sutando query to delete all models matching your query’s criteria. In this example, we will delete all flights that are marked as inactive. Like mass updates, mass deletes will not fire model events for the deleted models:

const deleted = await Flight.query().where('active', 0).delete();

Soft Deleting

In addition to actually removing records from your database, Sutando can also “soft delete” models. When models are soft deleted, they are not actually removed from your database. Instead, a deleted_at attribute will be set on the model indicating the date and time at which the model was “deleted”. To enable soft deletes for a model, use the SoftDeletes mixin and add a deleted_at field to your corresponding database table:

const { Model, compose, SoftDeletes } = "kawkab";
 
class Flight extends compose(Model, SoftDeletes) {
  // ...
}

Now, when the delete method is called on the model, the deleted_at column will be set to the current date and time. However, the model’s database record will remain in the table. When querying a model that uses soft deletes, the soft deleted models will automatically be excluded from all query results.

To determine if a given model instance has been soft deleted, you may use the trashed method:

if (flight.trashed()) {
  //
}

Restoring Soft Deleted Models

Sometimes you may wish to “un-delete” a soft deleted model. To restore a soft deleted model into an active state, you may call the restore method on a model instance. The restore method will set the model’s deleted_at column to null:

await flight.restore();

You may also use the restore method in a query to restore multiple models. Again, like other “mass” operations, this operation will not fire any model events for the restored models:

await Flight.query().withTrashed()
  .where('airline_id', 1)
  .restore();

The restore method may also be used when building relationship queries:

await flight.related('history').restore();

Permanently Deleting Models

Sometimes you may need to truly remove a model from your database. You may use the forceDelete method to permanently remove a model from the database:

await flight.forceDelete();

You may also use the forceDelete method when building Sutando relationship queries:

await flight.related('history').forceDelete();

Querying Soft Deleted Models

Including Soft Deleted Models

As noted above, soft deleted models will automatically be excluded from query results. However, you may force soft deleted models to be included in a query’s results by calling the withTrashed method on the query:

const { Flight } = require('./models');
 
const flights = await Flight.query().withTrashed()
  .where('account_id', 1)
  .get();

The withTrashed method may also be called when building a relationship query:

await flight.related('history').withTrashed().get();

Retrieving Only Soft Deleted Models

The onlyTrashed method will retrieve only soft deleted models:

const flights = await Flight.query().onlyTrashed()
  .where('airline_id', 1)
  .get();

Query Scopes

Scopes allow you to define common sets of query constraints that you may easily re-use throughout your application. For example, you may need to frequently retrieve all users that are considered “popular”. To define a scope, prefix a model method with scope:

Scopes should always return a query builder instance or void:

const { Model } = require('./models');
 
class User extends Model {
  scopePopular(query){
    return query.where('votes', '>', 100);
  }
 
  scopeActive(query){
    query.where('active', 1);
  }
}

Using A Scope

Once the scope has been defined, you may call the scope methods when querying the model. However, you should not include the scope prefix when calling the method. You may even chain calls to different scopes:

const { User } = require('./models');
 
const users = await User.query().popular().active().orderBy('created_at').get();

Combining multiple Sutando model scopes via an or query builder operator requires the use of a closure to achieve the proper logical grouping:

const users = await User.query().popular().orWhere(query => {
  query.active();
}).get();

Dynamic Scopes

Sometimes you may wish to define a scope that accepts parameters. To get started, simply add the additional parameters you need to your scope method’s signature. Scope parameters should be defined after the query parameter:

const { Model } = require('./models');
 
class User extends Model {
  scopeOfType(query, type){
    return query.where('type', type);
  }
}

Once you have added the expected parameters to your scope method’s signature, you may pass the arguments when calling the scope:

const users = await User.query().ofType('admin').get();

Comparing Models

Sometimes you may need to determine if two models are “the same”. The is and isNot methods can be used to quickly verify if two models have the same primary key, table, and database connection:

if (post.is(anotherPost)) {
  //
}
 
if (post.isNot(anotherPost)) {
  //
}