@yadah/objection-scope

Objection scope mixin

A mixin for Objection.js which extends the QueryBuilder to have a scope() method. It allows a model to define common query building functions based on a criteria object with a well-defined shape.

Usage

The Model.scopes object maps criteria keys to functions that work in a similar way to Model.modifiers. Scope modifiers accept the query object and the criteria object that was passed to the QueryBuilder.scope() function (this object will have a property with key that matches the Model.scopes key).

import ScopeMixin from "@yadah/objection-scope"
import { mixin, Model } from "objection"

class MyModel extends mixin(Model, [ScopeMixin]) {
  static get scopes() {
    return {
      ...super.scopes,
      keyword: (query, { keyword }) {
        return query.where("title", "like", `%${keyword}`)
      }
    }
  }
}

MyModel.query().scope({ keyword: "abc" })
// select * from "tableName" where "tableName"."title" like ?
// bindings: ["%abc"]

Matcher

The ScopeBuilder class can be used to help write common modifier patterns.

class MyModel extends mixin(Model, [ScopeMixin]) {
  static get scopes() {
    const matcher = new this.ScopeBuilder();
    return {
      ...super.scopes,
      field1: matcher,
      field2: matcher,
    };
  }
}
MyModel.query().scope({ field1: "foo", field2: "bar" });
// select * from "tableName" where "tableName"."field1" = ? and "tableName"."field2" = ?
// bindings: ["foo", "bar"]

The matcher object can be chained to produce various common types of query modifier.

const matcher = new this.ScopeBuilder();
const scopes = {
  field1: matcher,
  minField2: matcher.min,
  maxField3: matcher.max,
  field4: matcher.related("related"),
  field5: matcher.notNull,
};

Expression	Result	Notes
matcher	.where(fieldName, value)	if value is not an array
matcher	.whereIn(fieldName, value)	if value is an array
matcher.min	.where(fieldName, ">=", value)
matcher.max	.where(fieldname, "<=", value)
matcher.related(relationName)	.joinRelated(relationName).where(`${relationName}.${fieldName}`, value)	if value is not an array
matcher.related(relationName)	.joinRelated(relationName).whereIn(`${relationName}.${fieldName}`, value)	if value is an array
matcher.exists	.whereExists(Model.relatedQuery(fieldName).scope(value))
matcher.notNull	.whereNotNull(fieldname)	if value is true
matcher.notNull	.whereNull(fieldName)	if value is false
matcher.name(name)		changes fieldName to name