@tylix/orm 0.5.1 → 0.7.0

package/src/model/Model.d.ts

@@ -1,5 +1,6 @@
 // orm/src/model/Model.d.ts
 import { QueryBuilder } from '../query/QueryBuilder.js';
+import type { WhereClause } from '../query/types.js';
 
 interface PaginateOptions {
     page?: number;
@@ -17,33 +18,73 @@ interface PaginateResult<T> {
     };
 }
 
+type Row = Record<string, unknown>;
+
+/** Hooks an observer may define; see observers.js. All optional. */
+export interface Observer {
+    creating?(data: Row, model: typeof Model): Row | void | Promise<Row | void>;
+    created?(row: Row, model: typeof Model): unknown;
+    updating?(data: Row, before: Row | null, model: typeof Model): Row | void | Promise<Row | void>;
+    updated?(row: Row, before: Row | null, model: typeof Model): unknown;
+    deleting?(row: Row, model: typeof Model): unknown;
+    deleted?(row: Row, model: typeof Model): unknown;
+}
+
+/** An observer object, or a class whose instances are observers. */
+export type ObserverLike = Observer | (new () => Observer);
+
 export declare class Model {
+    /** Lets traits extend models as TypeScript mixins (see traits.d.ts). */
+    constructor(...args: any[]);
     static table: string | null;
     static fillable: string[];
     static timestamps: boolean;
+    /** Observers whose hooks run on create/update/delete. */
+    static observers?: ObserverLike[];
+    /** Adds observers at runtime. */
+    static observe<T extends typeof Model>(this: T, ...observers: ObserverLike[]): T;
 
     static getTable(): string;
     static getAdapter(): unknown;
 
-    static all(): Promise<Record<string, unknown>[]>;
-    static query(): QueryBuilder<Record<string, unknown>>;
-    static paginate(options?: PaginateOptions): Promise<PaginateResult<Record<string, unknown>>>;
-    static find(id: number | string): Promise<Record<string, unknown> | null>;
-    static create(data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
-    static update(id: number | string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    static all(): Promise<Row[]>;
+    static query(): QueryBuilder<Row>;
+    static where(field: string, value: unknown): QueryBuilder<Row>;
+    static where(field: string, operator: WhereClause['operator'], value: unknown): QueryBuilder<Row>;
+    static whereNull(field: string): QueryBuilder<Row>;
+    static whereNotNull(field: string): QueryBuilder<Row>;
+    static whereIn(field: string, values: readonly unknown[]): QueryBuilder<Row>;
+    static whereNotIn(field: string, values: readonly unknown[]): QueryBuilder<Row>;
+    static latest(column?: string): QueryBuilder<Row>;
+    static oldest(column?: string): QueryBuilder<Row>;
+    static paginate(options?: PaginateOptions): Promise<PaginateResult<Row>>;
+    static find(id: number | string): Promise<Row | null>;
+    static findOrFail(id: number | string): Promise<Row>;
+    static create(data: Row): Promise<Row | null>;
+    static update(id: number | string, data: Row): Promise<Row | null>;
+    /** Updates every row matching `where` in one statement; returns how many changed. Observers don't run. */
+    static updateWhere(where: Record<string, unknown>, values: Record<string, unknown>): Promise<number>;
     static delete(id: number | string): Promise<boolean>;
+    static destroy(...ids: Array<number | string | Array<number | string>>): Promise<number>;
+
+    static firstOrCreate(attributes: Row, values?: Row): Promise<Row | null>;
+    static updateOrCreate(attributes: Row, values?: Row): Promise<Row | null>;
+
+    static pluck(column: string): Promise<unknown[]>;
+    static pluck(column: string, keyColumn: string): Promise<Record<string, unknown>>;
+    static exists(): Promise<boolean>;
 
     static belongsTo(
-        row: Record<string, unknown> | null,
+        row: Row | null,
         foreignKey: string,
         RelatedModel: typeof Model,
-    ): Promise<Record<string, unknown> | null>;
+    ): Promise<Row | null>;
     static hasMany(
         row: { id: number },
         RelatedModel: typeof Model,
         foreignKey: string,
-    ): Promise<Record<string, unknown>[]>;
+    ): Promise<Row[]>;
 
-    static first(): Promise<Record<string, unknown> | null>;
+    static first(): Promise<Row | null>;
     static count(): Promise<number>;
 }

package/src/model/Model.js

@@ -1,5 +1,6 @@
 import { ConnectionManager } from './ConnectionManager.js'
 import { QueryBuilder } from '../query/QueryBuilder.js'
+import { addObservers, fire, hasHook, observersOf } from './observers.js'
 
 export class Model {
   static table = null
@@ -17,6 +18,16 @@ export class Model {
     return ConnectionManager.getAdapter()
   }
 
+  /**
+   * Adds observers at runtime (see observers.js for the hooks):
+   *   User.observe(UserObserver)
+   * Usually they're declared on the model instead: static observers = [...]
+   */
+  static observe(...observers) {
+    addObservers(this, observers)
+    return this
+  }
+
   static async all() {
     const adapter = ConnectionManager.getAdapter()
     return adapter.all(`SELECT * FROM ${this.getTable()}`)
@@ -30,6 +41,46 @@ export class Model {
     return new QueryBuilder(this)
   }
 
+  /**
+   * Shortcut for query().where(...):
+   *   await Post.where("status", "published").get()
+   *   await Post.where("views", ">", 100).first()
+   *   await Post.where("deleted_at", null).get()      // IS NULL
+   */
+  static where(...args) {
+    return this.query().where(...args)
+  }
+
+  /** deleted_at IS NULL. Returns a QueryBuilder: await Post.whereNull("deleted_at").get() */
+  static whereNull(field) {
+    return this.query().whereNull(field)
+  }
+
+  /** verified_at IS NOT NULL. Returns a QueryBuilder. */
+  static whereNotNull(field) {
+    return this.query().whereNotNull(field)
+  }
+
+  /** id IN (1, 2, 3). Returns a QueryBuilder: await Post.whereIn("id", [1, 2]).get() */
+  static whereIn(field, values) {
+    return this.query().whereIn(field, values)
+  }
+
+  /** status NOT IN ("banned", "spam"). Returns a QueryBuilder. */
+  static whereNotIn(field, values) {
+    return this.query().whereNotIn(field, values)
+  }
+
+  /** Newest first. Returns a QueryBuilder: await Post.latest().get() */
+  static latest(column = 'created_at') {
+    return this.query().latest(column)
+  }
+
+  /** Oldest first. Returns a QueryBuilder: await Post.oldest().first() */
+  static oldest(column = 'created_at') {
+    return this.query().oldest(column)
+  }
+
   static async paginate({ page = 1, limit = 20, where = {} } = {}) {
     const safePage = Math.max(1, Math.floor(page))
     const safeLimit = Math.max(1, Math.min(100, Math.floor(limit)))
@@ -53,13 +104,27 @@ export class Model {
       },
     }
   }
+
   static async find(id) {
     const adapter = ConnectionManager.getAdapter()
     return adapter.get(`SELECT * FROM ${this.getTable()} WHERE id = ?`, [id])
   }
 
-  static async create(data) {
+  /** Like find(), but throws (with err.status = 404) when the row is missing. */
+  static async findOrFail(id) {
+    const row = await this.find(id)
+    if (!row) {
+      const error = new Error(`${this.name} with id ${id} not found.`)
+      error.status = 404
+      throw error
+    }
+    return row
+  }
+
+  static async create(input) {
     const adapter = ConnectionManager.getAdapter()
+    const observers = observersOf(this)
+    const data = await fire(this, observers, 'creating', { ...input })
     const fields = this.fillable.filter((f) => f in data)
 
     if (fields.length === 0) {
@@ -83,11 +148,17 @@ export class Model {
       columnValues,
     )
 
-    return this.find(result.lastInsertRowid)
+    const row = await this.find(result.lastInsertRowid)
+    await fire(this, observers, 'created', row)
+    return row
   }
 
-  static async update(id, data) {
+  static async update(id, input) {
     const adapter = ConnectionManager.getAdapter()
+    const observers = observersOf(this)
+    // The row as it was, for updating/updated hooks; only read when needed.
+    const before = hasHook(observers, ['updating', 'updated']) ? await this.find(id) : null
+    const data = await fire(this, observers, 'updating', { ...input }, before)
     const fields = this.fillable.filter((f) => f in data)
 
     if (fields.length === 0) {
@@ -110,15 +181,120 @@ export class Model {
       [...columnValues, id],
     )
 
-    return this.find(id)
+    const row = await this.find(id)
+    await fire(this, observers, 'updated', row, before)
+    return row
+  }
+
+  // Updates every row matching `where` in one statement and returns how
+  // many changed. Bulk: observers don't run. Useful for check-and-set:
+  //   const claimed = (await Job.updateWhere({ id, status: 'pending' }, { status: 'processing' })) === 1
+  static async updateWhere(where, values) {
+    const data = { ...values }
+    if (this.timestamps) data.updated_at = new Date().toISOString()
+    return ConnectionManager.getAdapter().updateWhere(this.getTable(), data, where)
   }
 
   static async delete(id) {
     const adapter = ConnectionManager.getAdapter()
+    const observers = observersOf(this)
+    // deleting/deleted hooks get the row; a missing row runs no hooks.
+    const row = hasHook(observers, ['deleting', 'deleted']) ? await this.find(id) : null
+    if (row) await fire(this, observers, 'deleting', row)
     await adapter.run(`DELETE FROM ${this.getTable()} WHERE id = ?`, [id])
+    if (row) await fire(this, observers, 'deleted', row)
     return true
   }
 
+  /**
+   * Delete one or more rows by id and return how many actually existed:
+   *   await Post.destroy(1)
+   *   await Post.destroy(1, 2, 3)
+   *   await Post.destroy([1, 2, 3])
+   */
+  static async destroy(...ids) {
+    const flat = ids.flat().filter((id) => id !== undefined && id !== null)
+    if (flat.length === 0) {
+      throw new Error(`${this.name}.destroy() needs at least one id.`)
+    }
+
+    let deleted = 0
+    for (const id of flat) {
+      if (await this.find(id)) {
+        await this.delete(id)
+        deleted++
+      }
+    }
+    return deleted
+  }
+
+  /**
+   * Find the first row matching `attributes`, or create it with
+   * `attributes` + `values`:
+   *   await User.firstOrCreate({ email: "a@b.com" }, { name: "Ann" })
+   */
+  static async firstOrCreate(attributes, values = {}) {
+    const keys = Object.keys(attributes ?? {})
+    if (keys.length === 0) {
+      throw new Error(
+        `${this.name}.firstOrCreate() needs at least one attribute to match on.`,
+      )
+    }
+
+    let query = this.query()
+    for (const key of keys) {
+      query = query.where(key, attributes[key])
+    }
+
+    const existing = await query.first()
+    if (existing) return existing
+
+    return this.create({ ...attributes, ...values })
+  }
+
+  /**
+   * Find the first row matching `attributes` and update it with `values`,
+   * or create it with `attributes` + `values`:
+   *   await Setting.updateOrCreate({ key: "theme" }, { value: "dark" })
+   */
+  static async updateOrCreate(attributes, values = {}) {
+    const keys = Object.keys(attributes ?? {})
+    if (keys.length === 0) {
+      throw new Error(
+        `${this.name}.updateOrCreate() needs at least one attribute to match on.`,
+      )
+    }
+
+    let query = this.query()
+    for (const key of keys) {
+      query = query.where(key, attributes[key])
+    }
+
+    const existing = await query.first()
+    if (!existing) {
+      return this.create({ ...attributes, ...values })
+    }
+
+    const hasFillableChange = this.fillable.some((f) => f in values)
+    if (!hasFillableChange) return existing
+
+    return this.update(existing.id, values)
+  }
+
+  /**
+   * One column as a plain array (or an object when a key column is given):
+   *   await User.pluck("email")           -> ["a@b.com", "c@d.com"]
+   *   await User.pluck("email", "id")     -> { 1: "a@b.com", 2: "c@d.com" }
+   */
+  static async pluck(column, keyColumn) {
+    return this.query().pluck(column, keyColumn)
+  }
+
+  /** True when the table has at least one row. */
+  static async exists() {
+    return this.query().exists()
+  }
+
   static async belongsTo(row, foreignKey, RelatedModel) {
     if (!row || row[foreignKey] === undefined || row[foreignKey] === null) {
       return null
@@ -141,4 +317,4 @@ export class Model {
   static async count() {
     return this.query().count()
   }
-}
+}

package/src/model/observers.js

@@ -0,0 +1,83 @@
+// Model observers: code that runs when rows are created, updated or deleted.
+//
+//   class UserObserver {
+//     async created(user) { await dispatch('SendWelcomeEmail', { userId: user.id }) }
+//   }
+//   class User extends Model {
+//     static observers = [UserObserver]
+//   }
+//
+// Hooks (all optional, may be async):
+//   creating(data)            before an insert; return an object to replace
+//                             the data, or throw to cancel
+//   created(row)              after the insert
+//   updating(data, before)    before an update (before = current row);
+//                             return an object to replace the data, or throw
+//   updated(row, before)      after the update
+//   deleting(row)             before a delete; throw to cancel
+//   deleted(row)              after the delete
+//
+// Every hook also gets the model class as its last argument.
+//
+// Observers come from `static observers` on the model and on every class it
+// extends (so traits can bring their own), plus Model.observe(...) calls.
+// An observer is a class (created once and reused) or a plain object.
+
+export const OBSERVER_EVENTS = ['creating', 'created', 'updating', 'updated', 'deleting', 'deleted']
+
+// Model class -> observers added at runtime with Model.observe().
+const registered = new WeakMap()
+// Observer class -> its single instance.
+const instances = new WeakMap()
+
+function instantiate(observer) {
+  if (typeof observer === 'function') {
+    if (!instances.has(observer)) instances.set(observer, new observer())
+    return instances.get(observer)
+  }
+  if (observer && typeof observer === 'object') return observer
+  throw new TypeError('An observer must be a class or an object with hook methods.')
+}
+
+export function addObservers(Model, observers) {
+  for (const observer of observers) instantiate(observer) // validate early
+  registered.set(Model, [...(registered.get(Model) ?? []), ...observers])
+}
+
+// Every observer for a model: its parents' first, then its own.
+export function observersOf(Model) {
+  const chain = []
+  for (let current = Model; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+    chain.unshift(current)
+  }
+  const list = []
+  for (const cls of chain) {
+    if (Object.hasOwn(cls, 'observers')) {
+      if (!Array.isArray(cls.observers)) {
+        throw new TypeError(`${cls.name}.observers must be an array of observers.`)
+      }
+      list.push(...cls.observers)
+    }
+    list.push(...(registered.get(cls) ?? []))
+  }
+  return list.map(instantiate)
+}
+
+// Runs one event's hooks in order. For "creating"/"updating", a hook may
+// return a new data object, which the next hook (and the write) receives.
+export async function fire(Model, observers, event, data, ...rest) {
+  let current = data
+  for (const observer of observers) {
+    const hook = observer[event]
+    if (typeof hook !== 'function') continue
+    const result = await hook.call(observer, current, ...rest, Model)
+    if ((event === 'creating' || event === 'updating') && result && typeof result === 'object') {
+      current = result
+    }
+  }
+  return current
+}
+
+export function hasHook(observers, events) {
+  return observers.some((observer) => events.some((event) => typeof observer[event] === 'function'))
+}

package/src/model/traits.d.ts

@@ -0,0 +1,30 @@
+import type { Model } from './Model.js';
+
+type Row = Record<string, unknown>;
+type ModelClass = typeof Model;
+
+/** A trait: takes a model class, returns a class extending it with more. */
+export type Trait<Added = {}> = <T extends ModelClass>(Base: T) => T & Added;
+
+// Any trait function: the class it returns is what use() adds.
+type AnyTrait = (Base: any) => any;
+
+/** Applies traits to a base model class, left to right. */
+export function use<T extends ModelClass>(Base: T): T;
+export function use<T extends ModelClass, A extends AnyTrait>(Base: T, a: A): T & ReturnType<A>;
+export function use<T extends ModelClass, A extends AnyTrait, B extends AnyTrait>(Base: T, a: A, b: B): T & ReturnType<A> & ReturnType<B>;
+export function use<T extends ModelClass, A extends AnyTrait, B extends AnyTrait, C extends AnyTrait>(
+    Base: T, a: A, b: B, c: C,
+): T & ReturnType<A> & ReturnType<B> & ReturnType<C>;
+export function use<T extends ModelClass>(Base: T, ...traits: AnyTrait[]): T;
+
+export interface SearchableStatics {
+    /** Rows where any of the trait's fields contains `term` (case-insensitive). */
+    search(term: string, options?: { limit?: number }): Promise<Row[]>;
+}
+
+/** Adds Model.search(term) over the given columns. */
+export function Searchable(options: { fields: string[] }): Trait<SearchableStatics>;
+
+// Only what is exported above is public (helper types stay private).
+export {};

package/src/model/traits.js

@@ -0,0 +1,61 @@
+// Traits: reusable model behaviour, as JavaScript mixins. A trait is a
+// function that takes a model class and returns a class extending it:
+//
+//   export const SoftLabels = (Base) => class extends Base {
+//     static async labelled(label) { return this.where('label', label).get() }
+//   }
+//
+//   class Post extends use(Model, Searchable({ fields: ['title', 'body'] }), SoftLabels) {
+//     static table = 'posts'
+//   }
+//
+// A trait can bring observer hooks too: `static observers = [...]` on the
+// class it returns runs alongside the model's own observers.
+
+export function use(Base, ...traits) {
+  return traits.reduce((Current, trait, i) => {
+    if (typeof trait !== 'function') {
+      throw new TypeError(`use(): trait ${i + 1} is not a function. Did you forget to call a trait factory, e.g. Searchable({ fields })?`)
+    }
+    const Next = trait(Current)
+    if (typeof Next !== 'function' || !(Next === Current || Object.prototype.isPrototypeOf.call(Current, Next))) {
+      throw new TypeError(`use(): trait ${i + 1} must return a class that extends the one it was given.`)
+    }
+    return Next
+  }, Base)
+}
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+// Adds Model.search(term) over the given columns:
+//   class Post extends use(Model, Searchable({ fields: ['title', 'body'] })) {}
+//   await Post.search('tylix')               // rows whose title or body contains it
+//   await Post.search('tylix', { limit: 10 })
+// Matching is case-insensitive (LIKE on every driver). It uses plain where()
+// queries, one per field, so it works on SQLite, MySQL, PostgreSQL and
+// MongoDB alike; for large tables use a full-text index instead.
+export function Searchable(options = {}) {
+  if (typeof options === 'function') {
+    throw new TypeError('Searchable is a trait factory: call it with options, e.g. use(Model, Searchable({ fields: ["title"] })).')
+  }
+  const { fields } = options
+  if (!Array.isArray(fields) || fields.length === 0 || !fields.every((f) => IDENTIFIER.test(f))) {
+    throw new TypeError('Searchable({ fields }) needs a list of column names, e.g. ["title", "body"].')
+  }
+  return (Base) =>
+    class extends Base {
+      static async search(term, { limit = 50 } = {}) {
+        const text = String(term ?? '').trim()
+        if (text === '') return []
+        const pattern = `%${text}%`
+        const found = new Map()
+        for (const field of fields) {
+          for (const row of await this.where(field, 'LIKE', pattern).get()) {
+            if (!found.has(row.id)) found.set(row.id, row)
+            if (found.size >= limit) return [...found.values()]
+          }
+        }
+        return [...found.values()]
+      }
+    }
+}

package/src/query/QueryBuilder.d.ts

@@ -5,7 +5,13 @@ export declare class QueryBuilder<TRow> {
 
     where(field: string, value: unknown): this;
     where(field: string, operator: WhereClause['operator'], value: unknown): this;
+    whereNull(field: string): this;
+    whereNotNull(field: string): this;
+    whereIn(field: string, values: readonly unknown[]): this;
+    whereNotIn(field: string, values: readonly unknown[]): this;
     orderBy(field: string, direction?: 'ASC' | 'DESC'): this;
+    latest(column?: string): this;
+    oldest(column?: string): this;
     limit(value: number): this;
     offset(value: number): this;
     toDescriptor(): QueryDescriptor;
@@ -13,4 +19,7 @@ export declare class QueryBuilder<TRow> {
     get(): Promise<TRow[]>;
     first(): Promise<TRow | null>;
     count(): Promise<number>;
+    pluck(column: string): Promise<unknown[]>;
+    pluck(column: string, keyColumn: string): Promise<Record<string, unknown>>;
+    exists(): Promise<boolean>;
 }

package/src/query/QueryBuilder.js

@@ -1,7 +1,7 @@
 /**
  * Fluent query builder returned by Model.query(). Accumulates a
  * structured descriptor and only hits the database when a terminal
- * method (get/first/count) is called.
+ * method (get/first/count/pluck/exists) is called.
  */
 export class QueryBuilder {
   constructor(ModelClass) {
@@ -12,6 +12,10 @@ export class QueryBuilder {
     this.offsetValue = undefined;
   }
 
+  // where("status", "active")        status = 'active'
+  // where("age", ">", 18)            age > 18
+  // where("deleted_at", null)        deleted_at IS NULL
+  // where("id", "IN", [1, 2, 3])     same as whereIn("id", [1, 2, 3])
   where(field, operatorOrValue, maybeValue) {
     const hasExplicitOperator = maybeValue !== undefined;
     const operator = hasExplicitOperator ? operatorOrValue : "=";
@@ -21,6 +25,36 @@ export class QueryBuilder {
     return this;
   }
 
+  // deleted_at IS NULL
+  whereNull(field) {
+    this.wheres.push({ field, operator: "IS NULL", value: null });
+    return this;
+  }
+
+  // deleted_at IS NOT NULL
+  whereNotNull(field) {
+    this.wheres.push({ field, operator: "IS NOT NULL", value: null });
+    return this;
+  }
+
+  // id IN (1, 2, 3). An empty array matches nothing.
+  whereIn(field, values) {
+    if (!Array.isArray(values)) {
+      throw new Error("whereIn() needs an array of values.");
+    }
+    this.wheres.push({ field, operator: "IN", value: [...values] });
+    return this;
+  }
+
+  // id NOT IN (1, 2, 3). An empty array excludes nothing.
+  whereNotIn(field, values) {
+    if (!Array.isArray(values)) {
+      throw new Error("whereNotIn() needs an array of values.");
+    }
+    this.wheres.push({ field, operator: "NOT IN", value: [...values] });
+    return this;
+  }
+
   orderBy(field, direction = "ASC") {
     const normalized = direction.toUpperCase();
     if (normalized !== "ASC" && normalized !== "DESC") {
@@ -30,6 +64,16 @@ export class QueryBuilder {
     return this;
   }
 
+  // Newest first (by created_at unless another column is given).
+  latest(column = "created_at") {
+    return this.orderBy(column, "DESC");
+  }
+
+  // Oldest first (by created_at unless another column is given).
+  oldest(column = "created_at") {
+    return this.orderBy(column, "ASC");
+  }
+
   limit(value) {
     this.limitValue = value;
     return this;
@@ -63,4 +107,19 @@ export class QueryBuilder {
     const rows = await this.get();
     return rows.length;
   }
-}
+
+  // pluck("email")        -> ["a@b.com", ...]
+  // pluck("email", "id")  -> { 1: "a@b.com", ... }
+  async pluck(column, keyColumn) {
+    const rows = await this.get();
+    if (keyColumn === undefined) {
+      return rows.map((row) => row[column]);
+    }
+    return Object.fromEntries(rows.map((row) => [row[keyColumn], row[column]]));
+  }
+
+  async exists() {
+    const row = await this.first();
+    return row !== null;
+  }
+}