Leoric ORM

Leoric is a thin Object Relational Mapping (ORM) layer for Node.js. It is heavily influenced by Ruby on Rails' Active Record and is designed to represent business data and logic by connecting rich application objects to relational database tables.

Key features include:

• Representing models and their data.
• Representing associations between models.
• Mapping existing tables without repeating column definitions.
• Asynchronous CRUD (Create, Read, Update, Delete) operations.
• Support for modern JavaScript.

SQLite supports connection pooling, which is enabled by default with a connectionLimit of 10. However, multiple connections can lead to SQLITE_BUSY errors because SQLite lacks a server to manage locks.

To mitigate this, you can:

1. Set connectionLimit: 1 to ensure only one connection is used.
2. Increase the busyTimeout to allow the client to wait longer for locks to clear.

const realm = new Realm({
  dialect: 'sqlite',
  database: 'database/development.sqlite3',
  models: 'app/models',
  connectionLimit: 1,
});

Leoric uses method chaining to build queries. Calling a query method like .find() or .order() returns a Spell instance. A Spell is a builder object that allows you to append further query details (like .where(), .group(), .limit(), etc.) before execution.

Execution:

• A Spell can be treated as a Promise (using async/await, .then(), or co).
• To inspect the generated SQL without executing it, call .toSqlString() on the Spell instance.

// Building and executing a chain
const query = Post.where('title LIKE ?', '%Post%')
const posts = await query.order('updatedAt desc').limit(10)

// Inspecting SQL
const sql = Post.find().where('id = 1').toSqlString()

The VIRTUAL type allows you to define columns that exist on your model instance but are not stored in the database. These are ideal for computed properties that depend on other attributes.

class User extends Bone {
  static attributes = {
    firstName: STRING,
    lastName: STRING,
    fullName: {
      type: VIRTUAL,
      get() {
        return `${this.firstName} ${this.lastName}`;
      },
    },
  }
}

Leoric supports logical operators in object conditions using a syntax similar to MongoDB's BOSN grammar. You can use two different patterns for logical queries, and they are both nestable:

1. Top-level logical operators: Using $or or $and at the root of the condition object.
2. Field-level logical operators: Nesting $or or $and directly under a specific field name.

Both methods are supported and can be nested within each other.

// Pattern 1: Top-level $or
await Post.where({
  $or: [
    { title: 'Nephalem' },
    { title: { $like: 'Angel%' },
  ],
});

// Pattern 2: Field-level $or
await Post.where({
  title: {
    $or: [
      'Nephalem',
      { $like: 'Angel%' },
    ],
  },
});

Associations

When soft delete is enabled on a model, its associations respect the deletedAt scope. When using .include() or .with(), any associated records that have been soft-deleted will be automatically filtered out of the result set.

Timestamps

• Soft-deletion: Sets deletedAt to the current timestamp. It does not automatically update the updatedAt column.
• Restoration: Sets deletedAt to null.

Leoric uses a 'Convention over Configuration' approach to map models to database tables and attributes. If you follow these rules, you write less configuration code.

Model and Table Mapping

• Model names: Use CamelCase (e.g., Shop, TagMap).
• Table names: Use the pluralized model name in snake_case (e.g., shops, tag_maps). Leoric uses the pluralize library for this transformation.

Attribute Mapping

• Model attributes: Use camelCase (e.g., createdAt).
• Database columns: Typically snake_case (e.g., created_at). Leoric automatically transforms column names to camelCase for model attributes.

Relationship Keys

• Foreign keys: Should follow the pattern modelNameId (e.g., shopId), which maps to the database column model_name_id (e.g., shop_id).
• Primary keys: Should be an unsigned integer named id.