Sutando ORM

Sutando's ORM maps database tables to classes that extend Model. This allows for more intuitive data manipulation, including querying, saving, and deleting records.

class User extends Model {}

// Querying via Model
const users = await User.query().where('age', '>', 35).get();

// Inserting a new record
const user = new User;
user.name = 'David Bowie';
await user.save();

// Deleting a record
await user.delete();

To use Sutando, you must install the sutando package along with your preferred database driver (e.g., mysql2 for MySQL).

$ npm install sutando mysql2 --save

Before performing database operations, you must register your connection details using sutando.addConnection(). This method accepts a configuration object specifying the client (the database driver) and a connection object containing host, port, user, password, and database name.

const { sutando, Model } = require('sutando');

sutando.addConnection({
  client: 'mysql2',
  connection: {
    host : '127.0.0.1',
    port : 3306,
    user : 'root',
    password : '',
    database : 'test'
  },
});

const db = sutando.connection();

Sutando models support advanced querying features like pagination and eager loading to handle relationships efficiently.

• Pagination: Use .paginate() on a query.
• Eager Loading: Use .with('relationName') to load related models in a single query.
• Constrained Eager Loading: Pass a callback to .with() to filter the related models being loaded.
• Lazy Eager Loading: Use .load('relationName') on an existing model instance to load its relations.

// Pagination
const users = await User.query().paginate();

// Eager Loading
const users = await User.query().with('posts').get();

// Constraining Eager Loads
const users = await User.query().with({
  posts: q => q.where('likes_count', '>', 100)
}).get();

// Lazy Eager Loading
await user.load('posts');

Sutando provides specialized classes to handle different types of database relationships. These are typically defined within a Model class.

• HasOne<M>: A one-to-one relationship where the current model holds the foreign key.
• HasMany<M>: A one-to-many relationship.
• BelongsTo<M>: A relationship where the current model holds the foreign key pointing to another model.
• BelongsToMany<M>: A many-to-many relationship using a pivot table. Supports pivot-specific filtering via wherePivot(...) and orderByPivot(...).

// Example of defining a relationship in a Model
class Post extends Model {
  posts() {
    return this.hasMany(Comment);
  }
}

class Comment extends Model {
  post() {
    return this.belongsTo(Post);
  }
}

// Accessing relationships
const post = await Post.query().find(1);
const comments = await post.posts().getResults();

Sutando supports a plugin system to extend Model functionality.

• Plugin: A function that takes a Model class and returns an extended version of it.
• MixinFunction: A utility used to compose multiple plugins onto a model class using compose(modelClass, ...plugins).

This allows you to add shared behaviors (like soft deletes or auditing) to multiple models.

import { Model, Plugin, compose } from 'sutando';

const myPlugin: Plugin = (BaseModel) => {
  return class extends BaseModel {
    customMethod() { return 'hello'; }
  };
};

class User extends compose(Model, myPlugin) {}

const user = new User();
console.log(user.customMethod());

Run the init command to create a fresh sutando.config.js file in your current working directory using the default stub. This is required before running most other CLI commands like migrations or model generation.

sutando init

The Query Builder allows you to construct SQL queries using JavaScript methods without needing to define a Model class. You can access the builder via sutando.connection().table('tableName').

const db = sutando.connection();
const users = await db.table('users').where('age', '>', 35).get();

The HasMany class is used to define a one-to-many relationship between a parent entity and multiple related entities. It extends the base Relation class and requires a foreignKey (the key on the related objects pointing back to the parent) and a localKey (the key on the parent object used for the match). When instantiated, it returns a proxy object representing the relationship.

const HasMany = require('./has-many');

// Usage pattern:
// new HasMany(related, parent, foreignKey, localKey);