API.md

API Reference

require('objection-find')

var findQuery = require('objection-find');

findQuery(ObjectionModelConstructor) -> FindQueryBuilder

The function returned by require('objection-find') can be used to create a FindQueryBuilder instance. Just pass an objection.js model constructor to the function and start building the query.

const findQuery = require('objection-find');
const Person = require('./models/Person');
const builder = findQuery(Person);

findQuery(Person) is just a shortcut for new findQuery.FindQueryBuilder(Person)

findQuery.FindQueryBuilder

The FindQueryBuilder class constructor function. You can use this to create subclasses and whatnot.

FindQueryBuilder

Methods

• new FindQueryBuilder(ObjectionModelConstructor)
• FindQueryBuilder.extend(SubClassConstructor)
• .allowAll(boolean)
• .allow(string|Array., ...)
• .allowEager(string)
• .registerFilter(boolean)
• .specialParameter(string, string)
• .build(object, [QueryBuilder])

new FindQueryBuilder(ObjectionModelConstructor) -> FindQueryBuilder

The constructor function.

const FindQueryBuilder = require('objection-find').FindQueryBuilder;
const Person = require('./models/Person');
const findQueryBuilder = new FindQueryBuilder(Person);

FindQueryBuilder.extend(SubClassConstructor) -> SubClassConstructor

Creates a subclass of the FindQueryBuilder.

const FindQueryBuilder = require('objection-find').FindQueryBuilder;

function MyFindQueryBuilder() {
  FindQueryBuilder.apply(this, arguments);
}

FindQueryBuilder.extend(MyFindQueryBuilder);

MyFindQueryBuilder.prototype.someCustomMethod = function () {

};

.allowAll(boolean) -> FindQueryBuilder

Allows all property references. See .allow(string|Array., ...) for allowing only a subset. This is true by default.

findQueryBuilder.allowAll(false);

.allow(string|Array.<string>, ...) -> FindQueryBuilder

Use this method to whitelist property references. For security reasons it is sometimes important that the user cannot access some properties or relations of a model. By default all property references are allowed (see .allowAll(boolean)).

findQueryBuilder.allow('firstName', 'parent.firstName', 'pets.name');
// or
findQueryBuilder.allow(['firstName', 'parent.firstName', 'pets.name']);

allowEager(string) -> FindQueryBuilder

Sets the eager expression allowed by the eager query parameter. Any subset of the allowed expression is accepted in the eager query parameters. For example setting the allowed expression to a.b.c expressions a, a.b and a.b.c are accepted int the eager query parameter.

The eager expression is an objection.js relation expression. This method basically calls the QueryBuilder.allowEager(string) method of the underlying objection.js QueryBuilder.

By default, any eager expression is allowed.

findQueryBuilder.allowEager('[movies, children.[movies, children]]');

registerFilter(string, function) -> FindQueryBuilder

Registers a filter function that can be used in filter query parameters.

Given a filter query parameter someProp:eq=10 the eq part is the filter. The filter name (in this case 'eq') is mapped to a function that performs the filtering.

Filter functions take in three arguments:

1. PropertyRef instance of the property to be filtered
2. the filter value
3. and the objection.js model class constructor

The filter function must return an object {method: string, args: *}. For example:

function lowercaseEq(propertyRef, value, modelClass) {
  return {
    // Name of the filter method to be called on the objection.js query builder.
    method: 'where',
    // The arguments to pass for the filter method. You can access the name of the
    // column we are filtering through `propertyRef.fullColumnName()`.
    args: [propertyRef.fullColumnName(), '=', value.toLowerCase()]
  };
}

A better lowercaseEq would lowercase both sides of the comparison:

function lowercaseEq(propertyRef, value, modelClass) {
  // Always use use knex columnization for column references when building raw queries to make sure column names are escaped.

  return {
    method: 'whereRaw',
    // Always escape the user input when building raw queries.
    args: ['lower(??) like ?', [propertyRef.fullColumnName(), value.toLowerCase()]]
  };
}

The method must be the name of one of the objection.js where methods. args is the array of arguments for the method. The filter is invoked somewhat like this:

const filter = lowercaseEq(propertyRef, value, modelClass);
objectionQueryBuilder[filter.method].apply(objectionQueryBuilder, filter.args);

The args array can be anything the given where method accepts as an argument list. Check out the knex.js and objection.js documentation.

To register lowercaseEq with name leq, do this:

builder.registerFilter('leq', lowercaseEq);

Now you could use your filter in the query parameters like this someProperty:leq=Hello.

specialParameter(string, string) -> FindQueryBuilder

This can be used to rename a special parameter for example if it collides with a property name. With the following example you can fetch relations eagerly by giving a withRelated=[pets, movies] query parameter instead of eager=[pets, movies].

findQueryBuilder.specialParameter('eager', 'withRelated');

build(object, [QueryBuilder]) -> QueryBuilder

Given the query parameters, builds the query and returns an objetion.js QueryBuilder.

expressApp.get('/persons', function (req, res, next) {
  findQuery(Person)
    .allow('firstName', 'movies.name', 'children.firstName')
    .allowEager('[movies, children]')
    .build(req.query)
    .then(function (results) { res.send(results); })
    .catch(next);
});