knex-supermodel

knex-supermodel

Description

knex-supermodel is meant to be a very lite but not quite an ORM for knex. This is accomplished by providing a base model that is simply an ES6 class that you extend in your own models. You can override the provided methods or even add to them to make your own. Each method will always return your model back to you, except in the obvious case of collection!

This package requires ES6 features only available in node 6.

Static Examples

Each subclass will have automatic access to static methods to create, fetch, collection, forge, update and destroy.

Create

When creating, the provided object becomes the properties. After inserting into the database, an instantation of your class is returned.

let user;
 
User.create({ foo: 'bar' })
  .then((u) => {
    user = u;
  });

Fetching

When fetching, the provided object becomes the where clause with a limit of 1. This results in an instantaion of your class whose properties are loaded from the database.

let user;
 
User.fetch({ id: '123' })
  .then((u) => {
    user = u;
  });

Forging

For convenience each model has access to a static forge method. Under the hood it is only calling the constructor and returing an instantiation of your class.

const user = User.forge({ foo: 'bar', bar: 'baz' });
 
console.log(user.foo); // bar
console.log(user.bar); // baz

Update

The static method update accepts new properties and a knex where clause object and returns to you instantiations of your class. It will return an array if there is more than one, otherwise it just give you the model updated. This is usefull if you are updating by ID.

User.update({ foo: 'baz' }, { foo: 'bar' })
  .then((users) => {
    console.log(user[0].foo); // baz
    console.log(user[1].foo); // baz
    console.log(user[2].foo); // baz
  });

Destroy

The static method destroy accepts a knex where clause object to delete records.

User.destroy({ foo: 'bar' }) // Deletes all users where foo is bar
  .then((res) => {
    console.log(res); // 1
  });

Collection

When getting a collection, the provided object becomes the where clause. Each member in the collection is an instantation of your class.

let users;
 
User.collection({ foo: 'bar' })
  .then((u) => {
    users = u;
  });

Instance Examples

Saving

Any added properties will become part of the resultant query. By default, the method of saving is insert but you may provide update as well.

class User extends require('knex-supermodel') {
  constructor(opts) {
    super(opts);
  }
}
 
User.knex = knex;
const user = new User({ foo: 'bar', bar: 'baz' });
 
console.log(user.foo); // bar
console.log(user.bar); // baz
 
user.save(); // performs insert
user.save({ method: 'insert' }); // performs insert
user.save({ method: 'update' }); // performs update

Destroy

When deleting, it assumes you want to delete by id unless you previously have set keys on the static model. These keys, if present, will be used to uniquely identify the model for deletion.

User.fetch({ id: '123' })
  .then((user) => user.destroy())
  .then((res) => {
    console.log(res); // 1
  });
 
User.fetch({ id: '123' })
  .then((user) => user.destroy())
  .then((res) => {
    console.log(res); // 1
  });
 
User.keys = [ 'foo' ];
User.fetch({ foo: 'bar' })
  .then((user) => user.destroy())
  .then((res) => {
    console.log(res); // 1
  });

Transacting

You may either provide a transacting knex to each method or chain it.

let user;
 
knex.transaction((trx) => {
  User.fetch({ id: '123' }, { trx })
    .then((u) => {
      user = u;
 
      return user.update({ foo: 'baz' });
    });
});
 
knex.transaction((trx) => {
  user.transaction(trx)
    .update({ trx })
    .then((user) => {
      return user.update({ foo: 'baz' });
    });
});

License

This software is licensed under the MIT license.