@tylix/orm 0.6.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mbiyrukzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,29 +1,54 @@
 # @tylix/orm
 
-A lightweight ORM for Tylix applications with adapters for SQLite,
-PostgreSQL, MySQL, and MongoDB.
+Models, a query builder and migrations-ready adapters for SQLite,
+PostgreSQL, MySQL and MongoDB.
 
-## What's included
+```sh
+npm install @tylix/orm
+```
+
+## Models
+
+```js
+import { Model } from '@tylix/orm'
 
-- **Adapters** — `DatabaseAdapter` (base interface), `SqliteAdapter`,
-  `PostgresAdapter`, `MysqlAdapter`, `MongoAdapter`, selected at
-  runtime via `AdapterFactory`
-- **Model** — `Model` base class, backed by `ConnectionManager`
-- **Query** — `QueryBuilder` and `buildSelectSql` for building queries
-  independent of the underlying adapter
+export class Post extends Model {
+  static table = 'posts'
+  static fillable = ['title', 'body', 'user_id']
+}
+
+const post = await Post.create({ title: 'Hello', body: '...', user_id: 1 })
+const recent = await Post.where('user_id', 1).latest().limit(10).get()
+const page = await Post.paginate({ page: 2, limit: 20 })
+const claimed = await Job.updateWhere({ id, status: 'pending' }, { status: 'processing' }) // 1 or 0
+```
 
-## Usage
+## Observers and traits
 
 ```js
-import { Model, QueryBuilder } from '@tylix/orm'
+import { Model, Searchable, use } from '@tylix/orm'
 
-class Invoice extends Model {
-  static table = 'invoices'
+class Post extends use(Model, Searchable({ fields: ['title', 'body'] })) {
+  static table = 'posts'
+  static observers = [PostObserver] // creating/created, updating/updated, deleting/deleted
 }
+
+const results = await Post.search('tylix')
 ```
 
-Ships with a `d.ts` declaration file. Pairs with the model/migration
-templates in `@tylix/generator`.
+## Query timing
+
+```js
+import { onQuery } from '@tylix/orm'
+
+onQuery(({ driver, sql, durationMs }) => { /* log, measure */ })
+```
+
+The Tylix CLI uses this for slow-query warnings and metrics. Nothing is
+timed while no one listens.
+
+SQLite statements are prepared once and reused; a migration run by
+another process is picked up within a second.
 
 ## License
 

package/package.json

@@ -1,22 +1,49 @@
 {
   "name": "@tylix/orm",
-  "version": "0.6.0",
+  "version": "1.0.0",
+  "description": "The Tylix ORM: models with observers and traits, a query builder, and adapters for SQLite, PostgreSQL, MySQL and MongoDB.",
+  "license": "MIT",
+  "author": "Mbiyrukzz",
   "type": "module",
-  "main": "./src/index.js",
-  "types": "./src/index.d.ts",
   "keywords": [
     "tylix",
     "orm",
     "database",
     "mongodb",
     "mysql",
-    "postgresql"
+    "postgresql",
+    "sqlite",
+    "postgres"
   ],
+  "homepage": "https://github.com/Mbiyrukzz/tylix/tree/main/packages/orm#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mbiyrukzz/tylix.git",
+    "directory": "packages/orm"
+  },
+  "bugs": {
+    "url": "https://github.com/Mbiyrukzz/tylix/issues"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "!**/*.test.js",
+    "!**/*.test.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "test": "node --test src/**/*.test.js"
+    "test": "node --test 'src/**/*.test.js'"
   },
   "dependencies": {
-    "@tylix/shared": "^0.6.0",
+    "@tylix/shared": "^1.0.0",
     "mongodb": "^6.5.0",
     "mysql2": "^3.23.1",
     "pg": "^8.11.0"

package/src/adapters/DatabaseAdapter.d.ts

@@ -8,6 +8,12 @@ export declare class DatabaseAdapter {
     /** SQL keyword used for LIKE conditions: "LIKE" by default, "ILIKE" on Postgres. */
     readonly likeOperator: 'LIKE' | 'ILIKE';
 
+    /** Updates rows matching every field of `where` in one statement; resolves to how many changed. */
+    updateWhere(table: string, values: Record<string, unknown>, where: Record<string, unknown>): Promise<number>;
+
+    /** Resolves when the database answers (SELECT 1, or a ping on MongoDB). */
+    ping(): Promise<void>;
+
     connect(): Promise<this>;
     close(): Promise<void>;
     run(sql: string, params?: unknown[]): Promise<RunResult>;

package/src/adapters/DatabaseAdapter.js

@@ -32,6 +32,26 @@ export class DatabaseAdapter {
     throw new Error('columnType() not implemented')
   }
 
+  // Updates the rows matching every field in `where`; resolves to how
+  // many rows changed. One statement, so a check-and-set such as
+  // { status: 'pending' } -> { status: 'processing' } is atomic.
+  async updateWhere(table, values, where) {
+    const q = (name) => this.quoteIdentifier(name)
+    const sets = Object.keys(values).map((column) => `${q(column)} = ?`)
+    const conditions = Object.keys(where).map((column) => `${q(column)} = ?`)
+    if (sets.length === 0 || conditions.length === 0) throw new Error('updateWhere() needs values and at least one condition.')
+    const result = await this.run(`UPDATE ${q(table)} SET ${sets.join(', ')} WHERE ${conditions.join(' AND ')}`, [
+      ...Object.values(values),
+      ...Object.values(where),
+    ])
+    return Number(result?.changes ?? result?.rowCount ?? result?.affectedRows ?? 0)
+  }
+
+  // Resolves when the database answers; used by /ready.
+  async ping() {
+    await this.get('SELECT 1')
+  }
+
   async count(table) {
     throw new Error('count() not implemented')
   }

package/src/adapters/MongoAdapter.js

@@ -111,6 +111,17 @@ export class MongoAdapter extends DatabaseAdapter {
     this.counters = {}
   }
 
+  async updateWhere(table, values, where) {
+    this.ensureConnected()
+    const result = await this.db.collection(table).updateMany({ ...where }, { $set: { ...values } })
+    return result.modifiedCount
+  }
+
+  async ping() {
+    this.ensureConnected()
+    await this.db.command({ ping: 1 })
+  }
+
   async connect() {
     try {
       // Fail after 5s instead of the driver's default 30s, so a stopped

package/src/adapters/MysqlAdapter.js

@@ -1,6 +1,7 @@
 import mysql from 'mysql2/promise'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
 import { normalizeDatabaseError } from './DatabaseError.js'
+import { emitQuery, hasQueryListeners } from '../instrumentation.js'
 
 const COLUMN_TYPES = {
   increments: 'INT AUTO_INCREMENT PRIMARY KEY',
@@ -10,6 +11,7 @@ const COLUMN_TYPES = {
   longText: 'LONGTEXT',
   boolean: 'TINYINT(1)',
   integer: 'INT',
+  float: 'DOUBLE',
   date: 'DATE',
   datetime: 'DATETIME',
   json: 'JSON',
@@ -77,10 +79,14 @@ export class MysqlAdapter extends DatabaseAdapter {
   async execute(sql, params = []) {
     this.ensureConnected()
     const converted = params.map(toMysqlDateTime)
+    const timed = hasQueryListeners()
+    const start = timed ? performance.now() : 0
     try {
       const [result] = await this.connection.execute(sql, converted)
+      if (timed) emitQuery({ driver: 'mysql', sql, durationMs: performance.now() - start })
       return result
     } catch (err) {
+      if (timed) emitQuery({ driver: 'mysql', sql, durationMs: performance.now() - start, error: err })
       throw normalizeDatabaseError('mysql', err, { sql, params: converted })
     }
   }

package/src/adapters/PostgresAdapter.js

@@ -1,6 +1,7 @@
 import pg from 'pg'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
 import { normalizeDatabaseError } from './DatabaseError.js'
+import { emitQuery, hasQueryListeners } from '../instrumentation.js'
 
 const COLUMN_TYPES = {
   increments: 'SERIAL PRIMARY KEY',
@@ -8,6 +9,7 @@ const COLUMN_TYPES = {
   text: 'TEXT',
   boolean: 'BOOLEAN',
   integer: 'INTEGER',
+  float: 'DOUBLE PRECISION',
   date: 'DATE',
   datetime: 'TIMESTAMP',
   json: 'JSONB',
@@ -78,9 +80,14 @@ export class PostgresAdapter extends DatabaseAdapter {
   // SQL (with $1, $2 placeholders), exactly what PostgreSQL received.
   async execute(sql, params = []) {
     this.ensureConnected()
+    const timed = hasQueryListeners()
+    const start = timed ? performance.now() : 0
     try {
-      return await this.pool.query(sql, params)
+      const result = await this.pool.query(sql, params)
+      if (timed) emitQuery({ driver: 'postgres', sql, durationMs: performance.now() - start })
+      return result
     } catch (err) {
+      if (timed) emitQuery({ driver: 'postgres', sql, durationMs: performance.now() - start, error: err })
       throw normalizeDatabaseError('postgres', err, { sql, params })
     }
   }

package/src/adapters/SqliteAdapter.js

@@ -1,5 +1,15 @@
 import { DatabaseAdapter } from './DatabaseAdapter.js'
 import { normalizeDatabaseError } from './DatabaseError.js'
+import { emitQuery, hasQueryListeners } from '../instrumentation.js'
+
+// Prepared statements kept per connection, so a repeated query skips
+// SQLite's parse and plan step. Bounded: the oldest is dropped first.
+// A prepared "SELECT *" keeps the columns it was prepared with, so the
+// cache is cleared when the schema changes: at once for DDL run here, and
+// within a second for a migration run by another process.
+const STATEMENT_CACHE_SIZE = 500
+const SCHEMA_CHECK_MS = 1000
+const DDL = /^\s*(CREATE|ALTER|DROP)\b/i
 
 const COLUMN_TYPES = {
   increments: 'INTEGER PRIMARY KEY AUTOINCREMENT',
@@ -7,6 +17,7 @@ const COLUMN_TYPES = {
   text: 'TEXT',
   boolean: 'INTEGER',
   integer: 'INTEGER',
+  float: 'REAL',
   date: 'TEXT',
   datetime: 'TEXT',
   json: 'TEXT',
@@ -18,6 +29,9 @@ export class SqliteAdapter extends DatabaseAdapter {
     super()
     this.filename = filename
     this.db = null
+    this.statements = new Map()
+    this.schemaVersion = null
+    this.schemaCheckedAt = 0
   }
 
   async connect() {
@@ -34,6 +48,7 @@ export class SqliteAdapter extends DatabaseAdapter {
 
   async close() {
     if (this.db) {
+      this.statements.clear()
       this.db.close()
       this.db = null
     }
@@ -54,13 +69,51 @@ export class SqliteAdapter extends DatabaseAdapter {
   // is prepared, so prepare() is inside the try as well.
   execute(method, sql, params = []) {
     this.ensureConnected()
+    const timed = hasQueryListeners()
+    const start = timed ? performance.now() : 0
     try {
-      return this.db.prepare(sql)[method](...params)
+      const result = this.statement(sql)[method](...params)
+      if (timed) emitQuery({ driver: 'sqlite', sql, durationMs: performance.now() - start })
+      return result
     } catch (err) {
+      if (timed) emitQuery({ driver: 'sqlite', sql, durationMs: performance.now() - start, error: err })
       throw normalizeDatabaseError('sqlite', err, { sql, params })
     }
   }
 
+  statement(sql) {
+    if (DDL.test(sql)) {
+      this.statements.clear()
+      this.schemaCheckedAt = 0
+      return this.db.prepare(sql)
+    }
+    const now = Date.now()
+    if (now - this.schemaCheckedAt > SCHEMA_CHECK_MS) {
+      this.schemaCheckedAt = now
+      const { schema_version: version } = this.db.prepare('PRAGMA schema_version').get()
+      if (version !== this.schemaVersion) {
+        // Reading the schema table makes SQLite reload this connection's
+        // copy of the schema; reading the version alone does not, and new
+        // statements would still be prepared against the old columns.
+        if (this.schemaVersion !== null) this.db.prepare('SELECT 1 FROM sqlite_schema LIMIT 1').get()
+        this.statements.clear()
+        this.schemaVersion = version
+      }
+    }
+    let statement = this.statements.get(sql)
+    if (statement) {
+      // Most recently used goes last, so the first entry is the oldest.
+      this.statements.delete(sql)
+    } else {
+      statement = this.db.prepare(sql)
+      if (this.statements.size >= STATEMENT_CACHE_SIZE) {
+        this.statements.delete(this.statements.keys().next().value)
+      }
+    }
+    this.statements.set(sql, statement)
+    return statement
+  }
+
   async run(sql, params = []) {
     return this.execute('run', sql, params)
   }

package/src/index.d.ts

@@ -3,9 +3,11 @@ export * from "./adapters/SqliteAdapter.js";
 export * from "./adapters/PostgresAdapter.js";
 export * from "./model/ConnectionManager.js";
 export * from "./model/Model.js";
+export * from "./model/traits.js";
+export declare const OBSERVER_EVENTS: readonly ["creating", "created", "updating", "updated", "deleting", "deleted"];
 export * from "./adapters/AdapterFactory.js";
 export * from "./adapters/MysqlAdapter.js";
 export * from "./adapters/MongoAdapter.js";
 export * from "./query/QueryBuilder.js";
 export * from "./query/buildSelectSql.js";
-export * from "./query/types.js";
+export * from "./query/types.js";export * from "./instrumentation.js";

package/src/index.js

@@ -3,9 +3,12 @@ export * from './adapters/SqliteAdapter.js'
 export * from './adapters/PostgresAdapter.js'
 export * from './model/ConnectionManager.js'
 export * from './model/Model.js'
+export * from './model/traits.js'
+export { OBSERVER_EVENTS } from './model/observers.js'
 export * from './adapters/AdapterFactory.js'
 export * from './adapters/MysqlAdapter.js'
 export * from './adapters/MongoAdapter.js'
 export * from './query/QueryBuilder.js'
 export * from './query/buildSelectSql.js'
 export * from './ensureDatabaseExists.js'
+export * from './instrumentation.js'

package/src/instrumentation.d.ts

@@ -0,0 +1,10 @@
+export interface QueryEvent {
+  driver: string
+  sql: string
+  durationMs: number
+  error?: unknown
+}
+/** Called after every SQL statement; returns a function that removes the listener. */
+export function onQuery(listener: (event: QueryEvent) => void): () => void
+export function hasQueryListeners(): boolean
+export function emitQuery(event: QueryEvent): void

package/src/instrumentation.js

@@ -0,0 +1,26 @@
+// Query timing for logs and metrics. Every SQL adapter reports each
+// statement it runs, with its duration, to the listeners registered here:
+//
+//   const stop = onQuery(({ driver, sql, durationMs, error }) => { ... })
+//
+// With no listeners nothing is timed, so this costs nothing by default.
+const listeners = new Set()
+
+export function onQuery(listener) {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+export function hasQueryListeners() {
+  return listeners.size > 0
+}
+
+export function emitQuery(event) {
+  for (const listener of listeners) {
+    try {
+      listener(event)
+    } catch {
+      // A broken listener must never fail the query.
+    }
+  }
+}

package/src/model/Model.d.ts

@@ -20,10 +20,29 @@ 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;
@@ -43,6 +62,8 @@ export declare class Model {
     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>;
 

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()}`)
@@ -110,8 +121,10 @@ export class Model {
     return row
   }
 
-  static async create(data) {
+  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) {
@@ -135,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) {
@@ -162,12 +181,28 @@ 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
   }
 

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 {};