Types

This page contains the documentation of all other types and classes than Model and QueryBuilder. There are two types of items on this page:

1. type: A type is just a POJO (Plain Old Javascript Object) with a set of properties.
2. class: A class is a JavaScript class with properties and methods.

type RelationMapping

type RelationJoin

type RelationThrough

type ModelOptions

type CloneOptions

type ToJsonOptions

type GraphOptions

type UpsertGraphOptions

type InsertGraphOptions

type FetchGraphOptions

type TableMetadataFetchOptions

type TableMetadataOptions

type TableMetadata

type StaticHookArguments

type FieldExpression

Field expressions are strings that allow you to refer to JSONB fields inside columns.

Syntax: <column reference>[:<json field reference>]

e.g. persons.jsonColumnName:details.names[1] would refer to value 'Second' in column persons.jsonColumnName which has { details: { names: ['First', 'Second', 'Last'] } } object stored in it.

First part <column reference> is compatible with column references used in knex e.g. MyFancyTable.tributeToThBestColumnNameEver.

Second part describes a path to an attribute inside the referred column. It is optional and it always starts with colon which follows directly with first path element. e.g. Table.jsonObjectColumnName:jsonFieldName or Table.jsonArrayColumn:[321].

Syntax supports [<key or index>] and .<key or index> flavors of reference to json keys / array indexes:

e.g. both Table.myColumn:[1][3] and Table.myColumn:1.3 would access correctly both of the following objects [null, [null,null,null, "I was accessed"]] and { "1": { "3" : "I was accessed" } }

Caveats when using special characters in keys:

1. objectColumn.key This is the most common syntax, good if you are not using dots or square brackets [] in your json object key name.
2. Keys containing dots objectColumn:[keywith.dots] Column { "keywith.dots" : "I was referred" }
3. Keys containing square brackets column['[]'] { "[]" : "This is getting ridiculous..." }
4. Keys containing square brackets and quotes objectColumn:['Double."Quote".[]'] and objectColumn:["Sinlge.'Quote'.[]"] Column { "Double.\"Quote\".[]" : "I was referred", "Sinlge.'Quote'.[]" : "Mee too!" }
5. Keys containing dots, square brackets, single quotes and double quotes in one json key is not currently supported

There are some special methods that accept FieldExpression strings directly, like whereJsonSupersetOf but you can use FieldExpressions anywhere with ref. Here's an example:

const { ref } = require('objection');

await Person.query()
  .select([
    'id',
    ref('persons.jsonColumn:details.name').castText().as('name'),
    ref('persons.jsonColumn:details.age').castInt().as('age'),
  ])
  .join(
    'someTable',
    ref('persons.jsonColumn:details.name').castText(),
    '=',
    ref('someTable.name')
  )
  .where('age', '>', ref('someTable.ageLimit'));

In the above example, we assume persons table has a column named jsonColumn of type jsonb (only works on postgres).

type RelationExpression

Relation expression is a simple DSL for expressing relation trees.

These strings are all valid relation expressions:

• children
• children.movies
• [children, pets]
• [children.movies, pets]
• [children.[movies, pets], pets]
• [children.[movies.actors.[children, pets], pets], pets]
• [children as kids, pets(filterDogs) as dogs]

There are two tokens that have special meaning: * and ^. * means "all relations recursively" and ^ means "this relation recursively".

For example children.* means "relation children and all its relations, and all their relations and ...".

::: warning The * token must be used with caution or you will end up fetching your entire database. :::

Expression parent.^ is equivalent to parent.parent.parent.parent... up to the point a relation no longer has results for the parent relation. The recursion can be limited to certain depth by giving the depth after the ^ character. For example parent.^3 is equal to parent.parent.parent.

Relations can be aliased using the as keyword.

For example the expression children.[movies.actors.[pets, children], pets] represents a tree:

              children
              (Person)
                 |
         -----------------
         |               |
       movies           pets
      (Movie)         (Animal)
         |
       actors
      (Person)
         |
    -----------
    |         |
   pets    children
 (Animal)  (Person)

The model classes are shown in parenthesis. When given to withGraphFetched method, this expression would fetch all relations as shown in the tree above:

const people = await Person.query().withGraphFetched(
  'children.[movies.actors.[pets, children], pets]'
);

// All persons have the given relation tree fetched.
console.log(people[0].children[0].movies[0].actors[0].pets[0].name);

Relation expressions can have arguments. Arguments are used to refer to modifier functions (either global or local. Arguments are listed in parenthesis after the relation names like this:

Person.query().withGraphFetched(
  `children(arg1, arg2).[movies.actors(arg3), pets]`
);

You can spread relation expressions to multiple lines and add whitespace:

Person.query().withGraphFetched(`[
    children.[
      pets,
      movies.actors.[
        pets,
        children
      ]
    ]
  ]`);

Relation expressions can be aliased using as keyword:

Person.query().withGraphFetched(`[
    children as kids.[
      pets(filterDogs) as dogs,
      pets(filterCats) as cats,

      movies.actors.[
        pets,
        children as kids
      ]
    ]
  ]`);

RelationExpression object notation

In addition to the string expressions, a more verbose object notation can also be used.

The string expression in the comment is equivalent to the object expression below it:

// `children`
{
  children: true;
}

// `children.movies`
{
  children: {
    movies: true;
  }
}

// `[children, pets]`
{
  children: true;
  pets: true;
}

// `[children.[movies, pets], pets]`
{
  children: {
    movies: true,
    pets: true
  }
  pets: true
}

// `parent.^`
{
  parent: {
    $recursive: true;
  }
}

// `parent.^5`
{
  parent: {
    $recursive: 5;
  }
}

// `parent.*`
{
  parent: {
    $allRecursive: true;
  }
}

// `[children as kids, pets(filterDogs) as dogs]`
{
  kids: {
    $relation: 'children'
  },

  dogs: {
    $relation: 'pets',
    $modify: ['filterDogs']
  }
}

type TransactionObject

This is nothing more than a knex transaction object. It can be used as a knex query builder, it can be passed to objection queries and models can be bound to it

See the section about transactions for more info and examples.

Instance Methods

commit()

const promise = trx.commit();

Call this method to commit the transaction. This only needs to be called if you use transaction.start() method.

rollback()

const promise = trx.rollback(error);

Call this method to rollback the transaction. This only needs to be called if you use transaction.start() method. You need to pass the error to the method as the only argument.

class ValidationError

const { ValidationError } = require('objection');

throw new ValidationError({ type, message, data });

For each key, a list of errors is given. Each error contains the default message (as returned by the validator), an optional keyword string to identify the validation rule which didn't pass and a param object which optionally contains more details about the context of the validation error.

If type is anything else but "ModelValidation", data can be any object that describes the error.

Error of this class is thrown by default if validation of any input fails. By input we mean any data that can come from the outside world, like model instances (or POJOs), relation expressions object graphs etc.

You can replace this error by overriding Model.createValidationError() method.

See the error handling recipe for more info.

If type is "ModelValidation" then data object should follow this pattern:

{
  key1: [{
    message: '...',
    keyword: 'required',
    params: null
  }, {
    message: '...',
    keyword: '...',
    params: {
      ...
    }
  }, ...],

  key2: [{
    message: '...',
    keyword: 'minLength',
    params: {
      limit: 1,
      ...
    }
  }, ...],

  ...
}

class NotFoundError

const { NotFoundError } = require('objection');

throw new NotFoundError(data);

Error of this class is thrown by default by throwIfNotFound()

You can replace this error by overriding Model.createNotFoundError() method.

See the error handling recipe for more info.

class Relation

Relation is a parsed and normalized instance of a RelationMapping. Relations can be accessed using the getRelations method.

Relation holds a RelationProperty instance for each property that is used to create the relationship between two tables.

Relation is actually a base class for all relation types BelongsToOneRelation, HasManyRelation etc. You can use instanceof to determine the type of the relations (see the example on the right). Note that HasOneRelation is a subclass of HasManyRelation and HasOneThroughRelation is a subclass of ManyToManyRelation. Arrange your instanceof checks accordingly.

Note that Relation instances are actually instances of the relation classes used in relationMappings. For example:

class Person extends Model {
  static get relationMappings() {
    return {
      pets: {
        relation: Model.HasManyRelation,
        modelClass: Animal,
        join: {
          from: 'persons.id',
          to: 'animals.ownerId',
        },
      },
    };
  }
}

const relations = Person.getRelations();

console.log(relations.pets instanceof Model.HasManyRelation); // --> true
console.log(relations.pets.name); // --> pets
console.log(relations.pets.ownerProp.cols); // --> ['id']
console.log(relations.pets.relatedProp.cols); // --> ['ownerId']

class RelationProperty

Represents a property that is used to create relationship between two tables. A single RelationProperty instance can represent composite key. In addition to a table column, A RelationProperty can represent a nested field inside a column (for example a jsonb column).

Properties

Methods

getProp()

const value = property.getProp(obj, index);

Gets this property's index:th value from an object. For example if the property represents a composite key [a, b.d.e, c] and obj is {a: 1, b: {d: {e: 2}}, c: 3} then getProp(obj, 1) would return 2.

setProp()

property.setProp(obj, index, value);

Sets this property's index:th value in an object. For example if the property represents a composite key [a, b.d.e, c] and obj is {a: 1, b: {d: {e: 2}}, c: 3} then setProp(obj, 1, 'foo') would mutate obj into {a: 1, b: {d: {e: 'foo'}}, c: 3}.

fullCol()

const col = property.fullCol(builder, index);

Returns the property's index:th column name with the correct table reference. Something like "Table.column". The first argument must be an objection QueryBuilder instance.

ref()

const ref = property.ref(builder, index);

Allows you to do things like this:

const builder = Person.query();
const ref = property.ref(builder, 0);
builder.where(ref, '>', 10);

Returns a ReferenceBuilder instance that points to the index:th column.

patch()

property.patch(patchObj, index, value);

Allows you to do things like this:

const builder = Person.query();
const patch = {};
property.patch(patch, 0, 'foo');
builder.patch(patch);

Appends an update operation for the index:th column into patchObj object.

class ReferenceBuilder

An instance of this is returned from the ref helper function.

Instance Methods

castText()

Cast reference to sql type text.

castInt()

Cast reference to sql type integer.

castBigInt()

Cast reference to sql type bigint.

castFloat()

Cast reference to sql type float.

castDecimal()

Cast reference to sql type decimal.

castReal()

Cast reference to sql type real.

castBool()

Cast reference to sql type boolean.

castTo()

Give custom type to which referenced value is cast to.

.castTo('mytype') --> CAST(?? as mytype)

castJson()

In addition to other casts wrap reference to_jsonb() function so that final value reference will be json type.

as()

Gives an alias for the reference .select(ref('age').as('yougness'))

from()

Specifies that table of the reference.

See this for some examples.

class ValueBuilder

An instance of this is returned from the val helper function. If an object is given as a value, it is cast to json by default.

Instance Methods

castText()

Cast to sql type text.

castInt()

Cast to sql type integer.

castBigInt()

Cast to sql type bigint.

castFloat()

Cast to sql type float.

castDecimal()

Cast to sql type decimal.

castReal()

Cast to sql type real.

castBool()

Cast to sql type boolean.

castTo()

Give custom type to which referenced value is cast to.

.castTo('mytype') --> CAST(?? as mytype)

castJson()

Converts the value to json (jsonb in case of postgresql). The default cast type for object values.

asArray()

Converts the value to an array.

val([1, 2, 3]).asArray() --> ARRAY[?, ?, ?]

Can be used in conjuction with castTo.

val([1, 2, 3]).asArray().castTo('real[]') -> CAST(ARRAY[?, ?, ?] AS real[])

as()

Gives an alias for the reference .select(ref('age').as('yougness'))

class RawBuilder

An instance of this is returned from the raw helper function.

Instance Methods

as()

Gives an alias for the raw expression .select(raw('concat(foo, bar)').as('fooBar')).

You should use this instead of inserting the alias to the SQL to give objection more information about the query. Some edge cases, like using raw in select inside a withGraphJoined modifier won't work unless you use this method.

class FunctionBuilder

An instance of this is returned from the fn helper function.

Instance Methods

as()

Gives an alias for the raw expression .select(fn('concat', 'foo', 'bar').as('fooBar')).

You should use this instead of inserting the alias to the SQL to give objection more information about the query. Some edge cases, like using fn in select inside a withGraphJoined modifier won't work unless you use this method.

class Validator

const { Validator } = require('objection');

Abstract class from which model validators must be inherited. See the example for explanation. Also check out the createValidator method.

Examples

const { Validator } = require('objection');

class MyCustomValidator extends Validator {
  validate(args) {
    // The model instance. May be empty at this point.
    const model = args.model;

    // The properties to validate. After validation these values will
    // be merged into `model` by objection.
    const json = args.json;

    // `ModelOptions` object. If your custom validator sets default
    // values, you need to check the `opt.patch` boolean. If it is true
    // we are validating a patch object and the defaults should not be set.
    const opt = args.options;

    // A context object shared between the validation methods. A new
    // object is created for each validation operation. You can store
    // any data here.
    const ctx = args.ctx;

    // Do your validation here and throw any exception if the
    // validation fails.
    doSomeValidationAndThrowIfFails(json);

    // You need to return the (possibly modified) json.
    return json;
  }

  beforeValidate(args) {
    // Takes the same arguments as `validate`. Usually there is no need
    // to override this.
    return super.beforeValidate(args);
  }

  afterValidate(args) {
    // Takes the same arguments as `validate`. Usually there is no need
    // to override this.
    return super.afterValidate(args);
  }
}

const { Model } = require('objection');

// Override the `createValidator` method of a `Model` to use the
// custom validator.
class BaseModel extends Model {
  static createValidator() {
    return new MyCustomValidator();
  }
}

class AjvValidator

const { AjvValidator } = require('objection');

The default Ajv based json schema validator. You can override the createValidator method of Model like in the example to modify the validator.

Examples

const { Model, AjvValidator } = require('objection');

class BaseModel extends Model {
  static createValidator() {
    return new AjvValidator({
      onCreateAjv: (ajv) => {
        // Here you can modify the `Ajv` instance.
      },
      options: {
        allErrors: true,
        validateSchema: false,
        ownProperties: true,
        v5: true,
      },
    });
  }
}