@tylix/orm 0.5.1 → 0.7.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.5.1",
+  "version": "0.7.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.5.1",
+    "@tylix/shared": "^0.7.0",
     "mongodb": "^6.5.0",
     "mysql2": "^3.23.1",
     "pg": "^8.11.0"

package/src/adapters/DatabaseAdapter.d.ts

@@ -5,6 +5,15 @@ export interface RunResult {
 }
 
 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')
   }
@@ -44,6 +64,15 @@ export class DatabaseAdapter {
     throw new Error('listTables() not implemented')
   }
 
+  /**
+   * The SQL keyword used for LIKE conditions. Case-insensitive on MySQL and
+   * SQLite already; PostgresAdapter overrides this with "ILIKE" so all SQL
+   * drivers match the same rows.
+   */
+  get likeOperator() {
+    return 'LIKE'
+  }
+
   /**
    * Runs a structured query descriptor ({ wheres, orders, limitValue,
    * offsetValue }) against `table` and returns matching rows.
@@ -55,7 +84,9 @@ export class DatabaseAdapter {
    * overrides this entirely since it has no SQL layer to delegate to.
    */
   async query(table, descriptor = {}) {
-    const { sql, params } = buildSelectSql(table, descriptor)
+    const { sql, params } = buildSelectSql(table, descriptor, {
+      likeOperator: this.likeOperator,
+    })
     return this.all(sql, params)
   }
-}
+}

package/src/adapters/MongoAdapter.js

@@ -2,6 +2,50 @@ import { MongoClient } from 'mongodb'
 import { DatabaseAdapter } from './DatabaseAdapter.js'
 import { normalizeDatabaseError } from './DatabaseError.js'
 
+// Same rule the SQL builder uses: plain identifiers only, with optional
+// dots for nested fields. Rejects "$where", "$or", spaces, quotes, etc.
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/
+
+// Same cap as the SQL builder, so a query that works on one driver
+// doesn't fail on another.
+const MAX_LIST_VALUES = 1000
+
+function assertField(name) {
+  if (typeof name !== 'string' || !IDENTIFIER.test(name)) {
+    throw new Error(`Invalid column name "${String(name)}".`)
+  }
+  return name
+}
+
+// Validates the array given to IN / NOT IN, with the same rules as SQL.
+function assertList(values, operator) {
+  if (!Array.isArray(values)) {
+    throw new Error(`Operator "${operator}" needs an array of values.`)
+  }
+  if (values.length > MAX_LIST_VALUES) {
+    throw new Error(
+      `Operator "${operator}" accepts at most ${MAX_LIST_VALUES} values, got ${values.length}.`,
+    )
+  }
+  if (values.some((v) => v === null || v === undefined)) {
+    throw new Error(
+      `"${operator}" lists cannot contain null or undefined. Use whereNull() / whereNotNull() for null checks.`,
+    )
+  }
+  return values
+}
+
+// SQL LIKE -> anchored, case-insensitive regex ("%" = any run, "_" = any
+// single character). Case-insensitive to match MySQL and SQLite.
+function likeToRegex(pattern) {
+  if (typeof pattern !== 'string') {
+    throw new Error('LIKE needs a string pattern.')
+  }
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const source = escaped.replace(/%/g, '.*').replace(/_/g, '.')
+  return new RegExp(`^${source}$`, 'is')
+}
+
 export function parseQuery(sql) {
   const trimmed = sql.trim().replace(/\s+/g, ' ')
 
@@ -67,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
@@ -277,29 +332,52 @@ export class MongoAdapter extends DatabaseAdapter {
   async query(table, { wheres = [], orders = [], limitValue, offsetValue } = {}) {
     this.ensureConnected()
 
-    const filter = {}
+    let filter = {}
     const sort = {}
     const description = () => {
-      let text = `db.${table}.find(${JSON.stringify(filter)})`
-      if (Object.keys(sort).length) text += `.sort(${JSON.stringify(sort)})`
+      const show = (value) =>
+        JSON.stringify(value, (key, v) => (v instanceof RegExp ? String(v) : v))
+      let text = `db.${table}.find(${show(filter)})`
+      if (Object.keys(sort).length) text += `.sort(${show(sort)})`
       if (offsetValue !== undefined) text += `.skip(${offsetValue})`
       if (limitValue !== undefined) text += `.limit(${limitValue})`
       return text
     }
 
     return this.guard({ get sql() { return description() } }, async () => {
-      for (const w of wheres) {
-        if (w.operator === '=') filter[w.field] = w.value
-        else if (w.operator === '!=') filter[w.field] = { $ne: w.value }
-        else if (w.operator === '>') filter[w.field] = { $gt: w.value }
-        else if (w.operator === '<') filter[w.field] = { $lt: w.value }
-        else if (w.operator === '>=') filter[w.field] = { $gte: w.value }
-        else if (w.operator === '<=') filter[w.field] = { $lte: w.value }
-        else
-          throw new Error(
-            `Unsupported where operator "${w.operator}" for MongoAdapter`,
-          )
-      }
+      // Every condition goes into $and, so several conditions on the same
+      // field (age > 18 AND age < 65) all apply, like SQL. Values are
+      // always wrapped in an operator, so an object from the client can
+      // never be interpreted as a query operator itself.
+      const conditions = wheres.map((w) => {
+        const field = assertField(w.field)
+        const operator = String(w.operator).trim().replace(/\s+/g, ' ').toUpperCase()
+
+        if (operator === '=') return { [field]: { $eq: w.value } }
+        if (operator === '!=' || operator === '<>')
+          return { [field]: { $ne: w.value } }
+        if (operator === '>') return { [field]: { $gt: w.value } }
+        if (operator === '<') return { [field]: { $lt: w.value } }
+        if (operator === '>=') return { [field]: { $gte: w.value } }
+        if (operator === '<=') return { [field]: { $lte: w.value } }
+        if (operator === 'LIKE')
+          return { [field]: { $regex: likeToRegex(w.value) } }
+
+        // Mongo treats a missing field as null, so IS NULL also matches
+        // documents that don't have the field at all.
+        if (operator === 'IS NULL') return { [field]: { $eq: null } }
+        if (operator === 'IS NOT NULL') return { [field]: { $ne: null } }
+        if (operator === 'IN')
+          return { [field]: { $in: assertList(w.value, operator) } }
+        if (operator === 'NOT IN')
+          return { [field]: { $nin: assertList(w.value, operator) } }
+
+        throw new Error(
+          `Unsupported where operator "${w.operator}" for MongoAdapter`,
+        )
+      })
+
+      if (conditions.length > 0) filter = { $and: conditions }
 
       let cursor = this.db
         .collection(table)
@@ -307,7 +385,8 @@ export class MongoAdapter extends DatabaseAdapter {
 
       if (orders.length > 0) {
         orders.forEach((o) => {
-          sort[o.field] = o.direction.toUpperCase() === 'DESC' ? -1 : 1
+          sort[assertField(o.field)] =
+            o.direction.toUpperCase() === 'DESC' ? -1 : 1
         })
         cursor = cursor.sort(sort)
       }

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.
+    }
+  }
+}