Objection.js

Objection.js is a relational query builder for Node.js built on top of knex. It provides a powerful set of tools for working with SQL relations while allowing you to use the full power of your underlying database engine. It is not a traditional, fully object-oriented ORM; instead, it focuses on query-based interaction.

Key Features:

• Declarative model and relationship definitions.
• Support for fetching, inserting, updating, and deleting objects.
• Mechanisms for eager loading, graph inserts, and graph upserts.
• Transaction support.
• Official TypeScript support.
• Optional JSON schema validation.
• Ability to store complex documents as single rows.

The QueryBuilder is the primary component in Objection.js used to fetch or modify database items. It acts as a wrapper around the knex QueryBuilder.

Key characteristics:

• Inheritance: It possesses all methods available in a knex QueryBuilder.
• Model Instances: Unlike knex, which returns plain JavaScript objects, Objection's QueryBuilder returns instances of your Model subclasses.
• Thenable: It is a 'thenable' object, meaning it can be used directly with await or returned from a promise to be chained like a standard Promise.

Objection.js throws four primary categories of errors:

1. ValidationError: Thrown when input from the outside world is invalid (e.g., model instances, POJOs, relation expressions, or object graphs). Use the type property to distinguish between specific validation failures.
2. NotFoundError: Thrown when the throwIfNotFound() method is called on a query but no results are returned.
3. Database Errors: Errors defined by the db-errors library. These can be accessed directly via the objection package.
4. Basic JavaScript Error: Indicates a programming or logic error. These should typically be treated as internal server errors (500) and fixed in the code.

You can write subqueries in Objection.js by passing a function to query building methods (similar to Knex.js). The function receives a query builder instance which you use to construct the subquery.

const peopleOlderThanAverage = await Person.query().where(
  'age',
  '>',
  builder => {
    builder.avg('age').from('persons');
  }
);

console.log(peopleOlderThanAverage);

You can define default values for model properties by using the default key within the jsonSchema static property. This is useful for ensuring that new model instances have predefined values for specific fields.

class Person extends Model {
  static get jsonSchema() {
    return {
      type: 'object',
      properties: {
        gender: {
          type: 'string',
          enum: ['Male', 'Female', 'Other'],
          default: 'Female'
        }
      }
    };
  }
}

You can use modifiers() to apply named, reusable query logic to your relations. Modifiers can be defined as static getters on your Models.

1. Define modifiers in the Model class using static get modifiers().
2. Apply modifiers in the query string using the relationName(modifierName) syntax.
3. Pass arguments to modifiers by using the .modifiers() method on the QueryBuilder.

Create new records by chaining the .insert(data) method to a query. The returned value is the newly created Model instance. You can include subqueries or knex.raw expressions within the data object.

// Basic insert
const jennifer = await Person.query().insert({
  firstName: 'Jennifer',
  lastName: 'Lawrence'
});

// Insert with a subquery for a field
const jenniferWithAvg = await Person.query().insert({
  firstName: 'Average',
  lastName: 'Person',
  age: Person.query().avg('age')
});