sqlite-zod-orm 3.25.0 → 3.26.1

package/README.md

@@ -228,6 +228,21 @@ db.exec('UPDATE users SET score = 0 WHERE role = ?', 'guest');
 - Debug mode (SQL logging)
 - Raw SQL escape hatch
 
+## Contributing
+
+SatiDB is opinionated by design. Before proposing new features, understand what it intentionally does **not** do:
+
+| ❌ Don't add | Why |
+|---|---|
+| Tagged SQL templates | The whole point is "zero SQL" — `db.raw()` is the escape hatch |
+| FTS5 wrapper | Wrapping it poorly is worse than not wrapping it — use `db.raw()` |
+| Query middleware | `measure-fn` handles observability, `hooks` handle lifecycle |
+| Cursor pagination | Offset pagination covers SQLite's single-process use case |
+| Schema introspection API | Zod schemas are compile-time known — runtime reflection invites dynamic queries |
+| Migration CLI | Auto-migration handles additive changes; use `db.exec()` for destructive ones |
+
+**The rule:** if the query builder can already do it, don't add a new API surface for it.
+
 ## Requirements
 
 - **Bun** ≥ 1.0 (uses `bun:sqlite` native bindings)

package/dist/index.js

@@ -23,8 +23,9 @@ var toAlpha = (num) => {
   } while (n >= 0);
   return result;
 };
-var maxResultLen = 80;
-var safeStringify = (value) => {
+var maxResultLen = 0;
+var safeStringify = (value, limit) => {
+  const cap = limit ?? maxResultLen;
   if (value === undefined)
     return "";
   if (value === null)
@@ -37,7 +38,9 @@ var safeStringify = (value) => {
     return value.toString();
   if (typeof value === "string") {
     const q = JSON.stringify(value);
-    return q.length > maxResultLen ? q.slice(0, maxResultLen - 1) + '\u2026"' : q;
+    if (cap === 0)
+      return q;
+    return q.length > cap ? q.slice(0, cap - 1) + '\u2026"' : q;
   }
   try {
     const seen = new WeakSet;
@@ -53,7 +56,9 @@ var safeStringify = (value) => {
         return `${val}n`;
       return val;
     });
-    return str.length > maxResultLen ? str.slice(0, maxResultLen) + "\u2026" : str;
+    if (cap === 0)
+      return str;
+    return str.length > cap ? str.slice(0, cap) + "\u2026" : str;
   } catch {
     return String(value);
   }
@@ -67,7 +72,7 @@ var formatDuration = (ms) => {
   const secs = Math.round(ms % 60000 / 1000);
   return `${mins}m ${secs}s`;
 };
-var timestamps = process.env.MEASURE_TIMESTAMPS === "1" || process.env.MEASURE_TIMESTAMPS === "true";
+var timestamps = typeof process !== "undefined" && (process.env.MEASURE_TIMESTAMPS === "1" || process.env.MEASURE_TIMESTAMPS === "true");
 var ts = () => {
   if (!timestamps)
     return "";
@@ -78,7 +83,9 @@ var ts = () => {
   const ms = String(now.getMilliseconds()).padStart(3, "0");
   return `[${h}:${m}:${s}.${ms}] `;
 };
-var silent = process.env.MEASURE_SILENT === "1" || process.env.MEASURE_SILENT === "true";
+var silent = typeof process !== "undefined" && (process.env.MEASURE_SILENT === "1" || process.env.MEASURE_SILENT === "true");
+var dotEndLabel = true;
+var dotChar = "\xB7";
 var logger = null;
 var buildActionLabel = (actionInternal) => {
   return typeof actionInternal === "object" && actionInternal !== null && "label" in actionInternal ? String(actionInternal.label) : String(actionInternal);
@@ -90,6 +97,20 @@ var extractBudget = (actionInternal) => {
     return Number(actionInternal.budget);
   return;
 };
+var extractTimeout = (actionInternal) => {
+  if (typeof actionInternal !== "object" || actionInternal === null)
+    return;
+  if ("timeout" in actionInternal)
+    return Number(actionInternal.timeout);
+  return;
+};
+var extractMaxResultLength = (actionInternal) => {
+  if (typeof actionInternal !== "object" || actionInternal === null)
+    return;
+  if ("maxResultLength" in actionInternal)
+    return Number(actionInternal.maxResultLength);
+  return;
+};
 var extractMeta = (actionInternal) => {
   if (typeof actionInternal !== "object" || actionInternal === null)
     return;
@@ -98,6 +119,8 @@ var extractMeta = (actionInternal) => {
     delete details.label;
   if ("budget" in details)
     delete details.budget;
+  if ("maxResultLength" in details)
+    delete details.maxResultLength;
   if (Object.keys(details).length === 0)
     return;
   return details;
@@ -126,16 +149,18 @@ var defaultLogger = (event, prefix) => {
       console.log(`${t}${id} ... ${event.label}${formatMeta(event.meta)}`);
       break;
     case "success": {
-      const resultStr = event.result !== undefined ? safeStringify(event.result) : "";
+      const endLabel = dotEndLabel ? dotChar.repeat(event.label.length) : event.label;
+      const resultStr = event.result !== undefined ? safeStringify(event.result, event.maxResultLength) : "";
       const arrow = resultStr ? ` \u2192 ${resultStr}` : "";
       const budgetWarn = event.budget && event.duration > event.budget ? ` \u26A0 OVER BUDGET (${formatDuration(event.budget)})` : "";
-      console.log(`${t}${id} \u2713 ${event.label} ${formatDuration(event.duration)}${arrow}${budgetWarn}`);
+      console.log(`${t}${id} ${endLabel} ${formatDuration(event.duration)}${arrow}${budgetWarn}`);
       break;
     }
     case "error": {
+      const endLabel = dotEndLabel ? dotChar.repeat(event.label.length) : event.label;
       const errorMsg = event.error instanceof Error ? event.error.message : String(event.error);
       const budgetWarn = event.budget && event.duration > event.budget ? ` \u26A0 OVER BUDGET (${formatDuration(event.budget)})` : "";
-      console.log(`${t}${id} \u2717 ${event.label} ${formatDuration(event.duration)} (${errorMsg})${budgetWarn}`);
+      console.log(`${t}${id} \u2717 ${endLabel} ${formatDuration(event.duration)} (${errorMsg})${budgetWarn}`);
       if (event.error instanceof Error) {
         console.error(`${id}`, event.error.stack ?? event.error.message);
         if (event.error.cause) {
@@ -151,13 +176,14 @@ var defaultLogger = (event, prefix) => {
       break;
   }
 };
-var createNestedResolver = (isAsync, fullIdChain, childCounterRef, depth, resolver, prefix) => {
+var createNestedResolver = (isAsync, fullIdChain, childCounterRef, depth, resolver, prefix, inheritedMaxLen) => {
   return (...args) => {
     const label = args[0];
     const fn = args[1];
+    const onError = args[2];
     if (typeof fn === "function") {
       const childParentChain = [...fullIdChain, childCounterRef.value++];
-      return resolver(fn, label, childParentChain, depth + 1);
+      return resolver(fn, label, childParentChain, depth + 1, typeof onError === "function" ? onError : undefined, inheritedMaxLen);
     } else {
       emit({
         type: "annotation",
@@ -171,20 +197,24 @@ var createNestedResolver = (isAsync, fullIdChain, childCounterRef, depth, resolv
   };
 };
 var globalRootCounter = 0;
-var createMeasureImpl = (prefix, counterRef) => {
+var createMeasureImpl = (prefix, counterRef, scopeOpts) => {
   const counter = counterRef ?? { get value() {
     return globalRootCounter;
   }, set value(v) {
     globalRootCounter = v;
   } };
+  const scopeMaxLen = scopeOpts?.maxResultLength;
   let _lastError = null;
-  const _measureInternal = async (fnInternal, actionInternal, parentIdChain, depth) => {
+  const _measureInternal = async (fnInternal, actionInternal, parentIdChain, depth, onError, inheritedMaxLen) => {
     const start = performance.now();
     const childCounterRef = { value: 0 };
     const label = buildActionLabel(actionInternal);
     const budget = extractBudget(actionInternal);
-    const currentId = toAlpha(parentIdChain.pop() ?? 0);
-    const fullIdChain = [...parentIdChain, currentId];
+    const timeout = extractTimeout(actionInternal);
+    const localMaxLen = extractMaxResultLength(actionInternal);
+    const effectiveMaxLen = localMaxLen ?? inheritedMaxLen;
+    const currentId = toAlpha(Number(parentIdChain.pop() ?? 0));
+    const fullIdChain = [...parentIdChain.map(String), currentId];
     const idStr = fullIdChain.join("-");
     emit({
       type: "start",
@@ -193,27 +223,46 @@ var createMeasureImpl = (prefix, counterRef) => {
       depth,
       meta: extractMeta(actionInternal)
     }, prefix);
-    const measureForNextLevel = createNestedResolver(true, fullIdChain, childCounterRef, depth, _measureInternal, prefix);
+    const measureForNextLevel = createNestedResolver(true, fullIdChain, childCounterRef, depth, _measureInternal, prefix, effectiveMaxLen);
     try {
-      const result = await fnInternal(measureForNextLevel);
+      let result;
+      if (timeout && timeout > 0) {
+        result = await Promise.race([
+          fnInternal(measureForNextLevel),
+          new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout (${formatDuration(timeout)})`)), timeout))
+        ]);
+      } else {
+        result = await fnInternal(measureForNextLevel);
+      }
       const duration = performance.now() - start;
-      emit({ type: "success", id: idStr, label, depth, duration, result, budget }, prefix);
+      emit({ type: "success", id: idStr, label, depth, duration, result, budget, maxResultLength: effectiveMaxLen }, prefix);
       return result;
     } catch (error) {
       const duration = performance.now() - start;
-      emit({ type: "error", id: idStr, label, depth, duration, error, budget }, prefix);
+      emit({ type: "error", id: idStr, label, depth, duration, error, budget, maxResultLength: effectiveMaxLen }, prefix);
       _lastError = error;
+      if (onError) {
+        try {
+          return onError(error);
+        } catch (onErrorError) {
+          emit({ type: "error", id: idStr, label: `${label} (onError)`, depth, duration: performance.now() - start, error: onErrorError, budget, maxResultLength: effectiveMaxLen }, prefix);
+          _lastError = onErrorError;
+          return null;
+        }
+      }
       return null;
     }
   };
-  const _measureInternalSync = (fnInternal, actionInternal, parentIdChain, depth) => {
+  const _measureInternalSync = (fnInternal, actionInternal, parentIdChain, depth, _onError, inheritedMaxLen) => {
     const start = performance.now();
     const childCounterRef = { value: 0 };
     const label = buildActionLabel(actionInternal);
     const hasNested = fnInternal.length > 0;
     const budget = extractBudget(actionInternal);
-    const currentId = toAlpha(parentIdChain.pop() ?? 0);
-    const fullIdChain = [...parentIdChain, currentId];
+    const localMaxLen = extractMaxResultLength(actionInternal);
+    const effectiveMaxLen = localMaxLen ?? inheritedMaxLen;
+    const currentId = toAlpha(Number(parentIdChain.pop() ?? 0));
+    const fullIdChain = [...parentIdChain.map(String), currentId];
     const idStr = fullIdChain.join("-");
     if (hasNested) {
       emit({
@@ -224,22 +273,22 @@ var createMeasureImpl = (prefix, counterRef) => {
         meta: extractMeta(actionInternal)
       }, prefix);
     }
-    const measureForNextLevel = createNestedResolver(false, fullIdChain, childCounterRef, depth, _measureInternalSync, prefix);
+    const measureForNextLevel = createNestedResolver(false, fullIdChain, childCounterRef, depth, _measureInternalSync, prefix, effectiveMaxLen);
     try {
       const result = fnInternal(measureForNextLevel);
       const duration = performance.now() - start;
-      emit({ type: "success", id: idStr, label, depth, duration, result, budget }, prefix);
+      emit({ type: "success", id: idStr, label, depth, duration, result, budget, maxResultLength: effectiveMaxLen }, prefix);
       return result;
     } catch (error) {
       const duration = performance.now() - start;
-      emit({ type: "error", id: idStr, label, depth, duration, error, budget }, prefix);
+      emit({ type: "error", id: idStr, label, depth, duration, error, budget, maxResultLength: effectiveMaxLen }, prefix);
       _lastError = error;
       return null;
     }
   };
-  const measureFn = async (arg1, arg2) => {
+  const measureFn = async (arg1, arg2, arg3) => {
     if (typeof arg2 === "function") {
-      return _measureInternal(arg2, arg1, [counter.value++], 0);
+      return _measureInternal(arg2, arg1, [counter.value++], 0, arg3, scopeMaxLen);
     } else {
       const currentId = toAlpha(counter.value++);
       emit({
@@ -349,7 +398,7 @@ var createMeasureImpl = (prefix, counterRef) => {
   };
   const measureSyncFn = (arg1, arg2) => {
     if (typeof arg2 === "function") {
-      return _measureInternalSync(arg2, arg1, [counter.value++], 0);
+      return _measureInternalSync(arg2, arg1, [counter.value++], 0, undefined, scopeMaxLen);
     } else {
       const currentId = toAlpha(counter.value++);
       emit({
@@ -385,9 +434,9 @@ var createMeasureImpl = (prefix, counterRef) => {
 var globalInstance = createMeasureImpl();
 var measure = globalInstance.measure;
 var measureSync = globalInstance.measureSync;
-var createMeasure = (scopePrefix) => {
+var createMeasure = (scopePrefix, opts) => {
   const scopeCounter = { value: 0 };
-  const scoped = createMeasureImpl(scopePrefix, scopeCounter);
+  const scoped = createMeasureImpl(scopePrefix, scopeCounter, opts);
   return {
     ...scoped,
     resetCounter: () => {
@@ -5221,7 +5270,7 @@ function createQueryBuilder(ctx, entityName, initialCols) {
   const schema = ctx.schemas[entityName];
   const executor = (sql, params, raw) => {
     return ctx._m(`SQL: ${sql.slice(0, 60)}`, () => {
-      const rows = ctx.db.query(sql).all(...params);
+      const rows = ctx._stmt(sql).all(...params);
       if (raw)
         return rows;
       return rows.map((row) => ctx.attachMethods(entityName, transformFromStorage(row, schema)));
@@ -5269,7 +5318,7 @@ function createQueryBuilder(ctx, entityName, initialCols) {
       if (belongsTo2) {
         const fk = belongsTo2.foreignKey;
         const placeholders = parentIds.map(() => "?").join(", ");
-        const childRows = ctx.db.query(`SELECT * FROM ${hasMany.to} WHERE ${fk} IN (${placeholders})`).all(...parentIds);
+        const childRows = ctx._stmt(`SELECT * FROM ${hasMany.to} WHERE ${fk} IN (${placeholders})`).all(...parentIds);
         const groups = new Map;
         const childSchema = ctx.schemas[hasMany.to];
         for (const rawRow of childRows) {
@@ -5381,21 +5430,21 @@ function buildWhereClause(conditions, tablePrefix) {
 
 // src/crud.ts
 function getById(ctx, entityName, id) {
-  const row = ctx.db.query(`SELECT * FROM "${entityName}" WHERE id = ?`).get(id);
+  const row = ctx._stmt(`SELECT * FROM "${entityName}" WHERE id = ?`).get(id);
   if (!row)
     return null;
   return ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]));
 }
 function getOne(ctx, entityName, conditions) {
   const { clause, values } = ctx.buildWhereClause(conditions);
-  const row = ctx.db.query(`SELECT * FROM "${entityName}" ${clause} LIMIT 1`).get(...values);
+  const row = ctx._stmt(`SELECT * FROM "${entityName}" ${clause} LIMIT 1`).get(...values);
   if (!row)
     return null;
   return ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]));
 }
 function findMany(ctx, entityName, conditions = {}) {
   const { clause, values } = ctx.buildWhereClause(conditions);
-  const rows = ctx.db.query(`SELECT * FROM "${entityName}" ${clause}`).all(...values);
+  const rows = ctx._stmt(`SELECT * FROM "${entityName}" ${clause}`).all(...values);
   return rows.map((row) => ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName])));
 }
 function insert(ctx, entityName, data) {
@@ -5419,7 +5468,7 @@ function insert(ctx, entityName, data) {
   const sql = columns.length === 0 ? `INSERT INTO "${entityName}" DEFAULT VALUES` : `INSERT INTO "${entityName}" (${quotedCols.join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`;
   let lastId = 0;
   ctx._m(`SQL: ${sql.slice(0, 40)}`, () => {
-    const result = ctx.db.query(sql).run(...Object.values(transformed));
+    const result = ctx._stmt(sql).run(...Object.values(transformed));
     lastId = result.lastInsertRowid;
   });
   const newEntity = getById(ctx, entityName, lastId);
@@ -5448,7 +5497,7 @@ function update(ctx, entityName, id, data) {
   const setClause = Object.keys(transformed).map((key) => `"${key}" = ?`).join(", ");
   const sql = `UPDATE "${entityName}" SET ${setClause} WHERE id = ?`;
   ctx._m(`SQL: UPDATE ${entityName} SET ...`, () => {
-    ctx.db.query(sql).run(...Object.values(transformed), id);
+    ctx._stmt(sql).run(...Object.values(transformed), id);
   });
   const updated = getById(ctx, entityName, id);
   if (hooks?.afterUpdate && updated)
@@ -5466,7 +5515,7 @@ function updateWhere(ctx, entityName, data, conditions) {
     throw new Error("update().where() requires at least one condition");
   const setCols = Object.keys(transformed);
   const setClause = setCols.map((key) => `"${key}" = ?`).join(", ");
-  const result = ctx.db.query(`UPDATE "${entityName}" SET ${setClause} ${clause}`).run(...setCols.map((key) => transformed[key]), ...whereValues);
+  const result = ctx._stmt(`UPDATE "${entityName}" SET ${setClause} ${clause}`).run(...setCols.map((key) => transformed[key]), ...whereValues);
   return result.changes ?? 0;
 }
 function createUpdateBuilder(ctx, entityName, data) {
@@ -5507,7 +5556,7 @@ function deleteEntity(ctx, entityName, id) {
     if (result === false)
       return;
   }
-  ctx.db.query(`DELETE FROM "${entityName}" WHERE id = ?`).run(id);
+  ctx._stmt(`DELETE FROM "${entityName}" WHERE id = ?`).run(id);
   if (hooks?.afterDelete)
     hooks.afterDelete(id);
 }
@@ -5518,11 +5567,11 @@ function deleteWhere(ctx, entityName, conditions) {
   if (ctx.softDeletes) {
     const now = new Date().toISOString();
     const sql2 = `UPDATE "${entityName}" SET "deletedAt" = ? ${clause}`;
-    const result2 = ctx._m(`SQL: ${sql2.slice(0, 50)}`, () => ctx.db.query(sql2).run(now, ...values));
+    const result2 = ctx._m(`SQL: ${sql2.slice(0, 50)}`, () => ctx._stmt(sql2).run(now, ...values));
     return result2.changes ?? 0;
   }
   const sql = `DELETE FROM "${entityName}" ${clause}`;
-  const result = ctx._m(`SQL: ${sql.slice(0, 50)}`, () => ctx.db.query(sql).run(...values));
+  const result = ctx._m(`SQL: ${sql.slice(0, 50)}`, () => ctx._stmt(sql).run(...values));
   return result.changes ?? 0;
 }
 function createDeleteBuilder(ctx, entityName) {
@@ -5561,7 +5610,7 @@ function insertMany(ctx, entityName, rows) {
       const columns = Object.keys(transformed);
       const quotedCols = columns.map((c) => `"${c}"`);
       const sql = columns.length === 0 ? `INSERT INTO "${entityName}" DEFAULT VALUES` : `INSERT INTO "${entityName}" (${quotedCols.join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`;
-      const result = ctx.db.query(sql).run(...Object.values(transformed));
+      const result = ctx._stmt(sql).run(...Object.values(transformed));
       ids2.push(result.lastInsertRowid);
     }
     return ids2;
@@ -5647,6 +5696,15 @@ class _Database {
   _pollTimer = null;
   _pollInterval;
   _measure;
+  _stmtCache = new Map;
+  _stmt(sql) {
+    let stmt = this._stmtCache.get(sql);
+    if (!stmt) {
+      stmt = this.db.query(sql);
+      this._stmtCache.set(sql, stmt);
+    }
+    return stmt;
+  }
   _m(label, fn) {
     if (this._debug)
       return this._measure.measureSync.assert(label, fn);
@@ -5678,7 +5736,8 @@ class _Database {
       hooks: options.hooks ?? {},
       computed: options.computed ?? {},
       cascade: options.cascade ?? {},
-      _m: (label, fn) => this._m(label, fn)
+      _m: (label, fn) => this._m(label, fn),
+      _stmt: (sql) => this._stmt(sql)
     };
     this._m("Init tables", () => this.initializeTables());
     if (this._reactive)
@@ -5717,16 +5776,16 @@ class _Database {
                   if (rel) {
                     if (this._softDeletes) {
                       const now = new Date().toISOString();
-                      this.db.query(`UPDATE "${childTable}" SET "deletedAt" = ? WHERE "${rel.foreignKey}" = ?`).run(now, id);
+                      this._stmt(`UPDATE "${childTable}" SET "deletedAt" = ? WHERE "${rel.foreignKey}" = ?`).run(now, id);
                     } else {
-                      this.db.query(`DELETE FROM "${childTable}" WHERE "${rel.foreignKey}" = ?`).run(id);
+                      this._stmt(`DELETE FROM "${childTable}" WHERE "${rel.foreignKey}" = ?`).run(id);
                     }
                   }
                 }
               }
               if (this._softDeletes) {
                 const now = new Date().toISOString();
-                this.db.query(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`).run(now, id);
+                this._stmt(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`).run(now, id);
                 if (hooks?.afterDelete)
                   hooks.afterDelete(id);
                 return;
@@ -5740,12 +5799,12 @@ class _Database {
           if (!this._softDeletes)
             throw new Error("restore() requires softDeletes: true");
           this._m(`${entityName}.restore(${id})`, () => {
-            this.db.query(`UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`).run(id);
+            this._stmt(`UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`).run(id);
           });
         },
         select: (...cols) => createQueryBuilder(this._ctx, entityName, cols),
         count: () => this._m(`${entityName}.count`, () => {
-          const row = this.db.query(`SELECT COUNT(*) as count FROM "${entityName}"${this._softDeletes ? ' WHERE "deletedAt" IS NULL' : ""}`).get();
+          const row = this._stmt(`SELECT COUNT(*) as count FROM "${entityName}"${this._softDeletes ? ' WHERE "deletedAt" IS NULL' : ""}`).get();
           return row?.count ?? 0;
         }),
         on: (event, callback) => {
@@ -5861,11 +5920,11 @@ class _Database {
     }
   }
   _processChanges() {
-    const head = this.db.query('SELECT MAX(id) as m FROM "_changes"').get();
+    const head = this._stmt('SELECT MAX(id) as m FROM "_changes"').get();
     const maxId = head?.m ?? 0;
     if (maxId <= this._changeWatermark)
       return;
-    const changes = this.db.query('SELECT id, tbl, op, row_id FROM "_changes" WHERE id > ? ORDER BY id').all(this._changeWatermark);
+    const changes = this._stmt('SELECT id, tbl, op, row_id FROM "_changes" WHERE id > ? ORDER BY id').all(this._changeWatermark);
     for (const change of changes) {
       const listeners = this._listeners.filter((l) => l.table === change.tbl && l.event === change.op);
       if (listeners.length > 0) {
@@ -5889,22 +5948,23 @@ class _Database {
       }
       this._changeWatermark = change.id;
     }
-    this.db.query('DELETE FROM "_changes" WHERE id <= ?').run(this._changeWatermark);
+    this._stmt('DELETE FROM "_changes" WHERE id <= ?').run(this._changeWatermark);
   }
   transaction(callback) {
     return this._m("transaction", () => this.db.transaction(callback)());
   }
   close() {
     this._stopPolling();
+    this._stmtCache.clear();
     this.db.close();
   }
   query(callback) {
     return this._m("query(proxy)", () => executeProxyQuery(this.schemas, callback, (sql, params) => {
-      return this.db.query(sql).all(...params);
+      return this._stmt(sql).all(...params);
     }));
   }
   raw(sql, ...params) {
-    return this._m(`raw: ${sql.slice(0, 60)}`, () => this.db.query(sql).all(...params));
+    return this._m(`raw: ${sql.slice(0, 60)}`, () => this._stmt(sql).all(...params));
   }
   exec(sql, ...params) {
     this._m(`exec: ${sql.slice(0, 60)}`, () => this.db.run(sql, ...params));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.25.0",
+  "version": "3.26.1",
   "description": "Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,10 +49,10 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "measure-fn": "^3.3.0",
+    "measure-fn": "^3.10.0",
     "zod": "^3.25.67"
   },
   "engines": {
     "bun": ">=1.0.0"
   }
-}
+}

package/src/context.ts

@@ -46,4 +46,10 @@ export interface DatabaseContext {
      * When debug is off, executes fn directly with zero overhead.
      */
     _m<T>(label: string, fn: () => T): T;
+
+    /**
+     * Get a cached prepared statement. Compiles SQL once, reuses on subsequent calls.
+     * Falls back to `db.query(sql)` if the statement was finalized.
+     */
+    _stmt(sql: string): ReturnType<SqliteDatabase['query']>;
 }

package/src/crud.ts

@@ -14,21 +14,21 @@ import type { DatabaseContext } from './context';
 // ---------------------------------------------------------------------------
 
 export function getById(ctx: DatabaseContext, entityName: string, id: number): AugmentedEntity<any> | null {
-    const row = ctx.db.query(`SELECT * FROM "${entityName}" WHERE id = ?`).get(id) as any;
+    const row = ctx._stmt(`SELECT * FROM "${entityName}" WHERE id = ?`).get(id) as any;
     if (!row) return null;
     return ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]!));
 }
 
 export function getOne(ctx: DatabaseContext, entityName: string, conditions: Record<string, any>): AugmentedEntity<any> | null {
     const { clause, values } = ctx.buildWhereClause(conditions);
-    const row = ctx.db.query(`SELECT * FROM "${entityName}" ${clause} LIMIT 1`).get(...values) as any;
+    const row = ctx._stmt(`SELECT * FROM "${entityName}" ${clause} LIMIT 1`).get(...values) as any;
     if (!row) return null;
     return ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]!));
 }
 
 export function findMany(ctx: DatabaseContext, entityName: string, conditions: Record<string, any> = {}): AugmentedEntity<any>[] {
     const { clause, values } = ctx.buildWhereClause(conditions);
-    const rows = ctx.db.query(`SELECT * FROM "${entityName}" ${clause}`).all(...values);
+    const rows = ctx._stmt(`SELECT * FROM "${entityName}" ${clause}`).all(...values);
     return rows.map((row: any) =>
         ctx.attachMethods(entityName, transformFromStorage(row, ctx.schemas[entityName]!))
     );
@@ -68,7 +68,7 @@ export function insert<T extends Record<string, any>>(ctx: DatabaseContext, enti
 
     let lastId = 0;
     ctx._m(`SQL: ${sql.slice(0, 40)}`, () => {
-        const result = ctx.db.query(sql).run(...Object.values(transformed));
+        const result = ctx._stmt(sql).run(...Object.values(transformed));
         lastId = result.lastInsertRowid as number;
     });
     const newEntity = getById(ctx, entityName, lastId);
@@ -103,7 +103,7 @@ export function update<T extends Record<string, any>>(ctx: DatabaseContext, enti
     const setClause = Object.keys(transformed).map(key => `"${key}" = ?`).join(', ');
     const sql = `UPDATE "${entityName}" SET ${setClause} WHERE id = ?`;
     ctx._m(`SQL: UPDATE ${entityName} SET ...`, () => {
-        ctx.db.query(sql).run(...Object.values(transformed), id);
+        ctx._stmt(sql).run(...Object.values(transformed), id);
     });
 
     const updated = getById(ctx, entityName, id);
@@ -125,7 +125,7 @@ export function updateWhere(ctx: DatabaseContext, entityName: string, data: Reco
 
     const setCols = Object.keys(transformed);
     const setClause = setCols.map(key => `"${key}" = ?`).join(', ');
-    const result = ctx.db.query(`UPDATE "${entityName}" SET ${setClause} ${clause}`).run(
+    const result = ctx._stmt(`UPDATE "${entityName}" SET ${setClause} ${clause}`).run(
         ...setCols.map(key => transformed[key]),
         ...whereValues
     );
@@ -181,7 +181,7 @@ export function deleteEntity(ctx: DatabaseContext, entityName: string, id: numbe
         if (result === false) return;
     }
 
-    ctx.db.query(`DELETE FROM "${entityName}" WHERE id = ?`).run(id);
+    ctx._stmt(`DELETE FROM "${entityName}" WHERE id = ?`).run(id);
 
     // afterDelete hook
     if (hooks?.afterDelete) hooks.afterDelete(id);
@@ -196,12 +196,12 @@ export function deleteWhere(ctx: DatabaseContext, entityName: string, conditions
         // Soft delete: set deletedAt instead of removing rows
         const now = new Date().toISOString();
         const sql = `UPDATE "${entityName}" SET "deletedAt" = ? ${clause}`;
-        const result = ctx._m(`SQL: ${sql.slice(0, 50)}`, () => ctx.db.query(sql).run(now, ...values));
+        const result = ctx._m(`SQL: ${sql.slice(0, 50)}`, () => ctx._stmt(sql).run(now, ...values));
         return (result as any).changes ?? 0;
     }
 
     const sql = `DELETE FROM "${entityName}" ${clause}`;
-    const result = ctx._m(`SQL: ${sql.slice(0, 50)}`, () => ctx.db.query(sql).run(...values));
+    const result = ctx._m(`SQL: ${sql.slice(0, 50)}`, () => ctx._stmt(sql).run(...values));
     return (result as any).changes ?? 0;
 }
 
@@ -247,7 +247,7 @@ export function insertMany<T extends Record<string, any>>(ctx: DatabaseContext,
             const sql = columns.length === 0
                 ? `INSERT INTO "${entityName}" DEFAULT VALUES`
                 : `INSERT INTO "${entityName}" (${quotedCols.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`;
-            const result = ctx.db.query(sql).run(...Object.values(transformed));
+            const result = ctx._stmt(sql).run(...Object.values(transformed));
             ids.push(result.lastInsertRowid as number);
         }
         return ids;

package/src/database.ts

@@ -67,6 +67,19 @@ class _Database<Schemas extends SchemaMap> {
     /** Scoped measure-fn instance for instrumentation. */
     private _measure: ReturnType<typeof createMeasure>;
 
+    /** Prepared statement cache — avoids re-compiling identical SQL. */
+    private _stmtCache = new Map<string, ReturnType<SqliteDatabase['query']>>();
+
+    /** Get or create a cached prepared statement. */
+    private _stmt(sql: string): ReturnType<SqliteDatabase['query']> {
+        let stmt = this._stmtCache.get(sql);
+        if (!stmt) {
+            stmt = this.db.query(sql);
+            this._stmtCache.set(sql, stmt);
+        }
+        return stmt;
+    }
+
     /**
      * Conditional measurement helper — wraps with measure-fn only when debug is on.
      * When debug is off, executes fn directly with zero overhead.
@@ -105,6 +118,7 @@ class _Database<Schemas extends SchemaMap> {
             computed: options.computed ?? {},
             cascade: options.cascade ?? {},
             _m: <T>(label: string, fn: () => T): T => this._m(label, fn),
+            _stmt: (sql: string) => this._stmt(sql),
         };
 
         this._m('Init tables', () => this.initializeTables());
@@ -146,9 +160,9 @@ class _Database<Schemas extends SchemaMap> {
                                     if (rel) {
                                         if (this._softDeletes) {
                                             const now = new Date().toISOString();
-                                            this.db.query(`UPDATE "${childTable}" SET "deletedAt" = ? WHERE "${rel.foreignKey}" = ?`).run(now, id);
+                                            this._stmt(`UPDATE "${childTable}" SET "deletedAt" = ? WHERE "${rel.foreignKey}" = ?`).run(now, id);
                                         } else {
-                                            this.db.query(`DELETE FROM "${childTable}" WHERE "${rel.foreignKey}" = ?`).run(id);
+                                            this._stmt(`DELETE FROM "${childTable}" WHERE "${rel.foreignKey}" = ?`).run(id);
                                         }
                                     }
                                 }
@@ -156,7 +170,7 @@ class _Database<Schemas extends SchemaMap> {
 
                             if (this._softDeletes) {
                                 const now = new Date().toISOString();
-                                this.db.query(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`).run(now, id);
+                                this._stmt(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`).run(now, id);
                                 if (hooks?.afterDelete) hooks.afterDelete(id);
                                 return;
                             }
@@ -168,12 +182,12 @@ class _Database<Schemas extends SchemaMap> {
                 restore: ((id: number) => {
                     if (!this._softDeletes) throw new Error('restore() requires softDeletes: true');
                     this._m(`${entityName}.restore(${id})`, () => {
-                        this.db.query(`UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`).run(id);
+                        this._stmt(`UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`).run(id);
                     });
                 }) as any,
                 select: (...cols: string[]) => createQueryBuilder(this._ctx, entityName, cols),
                 count: () => this._m(`${entityName}.count`, () => {
-                    const row = this.db.query(`SELECT COUNT(*) as count FROM "${entityName}"${this._softDeletes ? ' WHERE "deletedAt" IS NULL' : ''}`).get() as any;
+                    const row = this._stmt(`SELECT COUNT(*) as count FROM "${entityName}"${this._softDeletes ? ' WHERE "deletedAt" IS NULL' : ''}`).get() as any;
                     return row?.count ?? 0;
                 }),
                 on: (event: ChangeEvent, callback: (row: any) => void | Promise<void>) => {
@@ -339,11 +353,11 @@ class _Database<Schemas extends SchemaMap> {
      */
     private _processChanges(): void {
         // Fast path: check if anything changed at all (single scalar, index-only)
-        const head = this.db.query('SELECT MAX(id) as m FROM "_changes"').get() as any;
+        const head = this._stmt('SELECT MAX(id) as m FROM "_changes"').get() as any;
         const maxId: number = head?.m ?? 0;
         if (maxId <= this._changeWatermark) return;
 
-        const changes = this.db.query(
+        const changes = this._stmt(
             'SELECT id, tbl, op, row_id FROM "_changes" WHERE id > ? ORDER BY id'
         ).all(this._changeWatermark) as { id: number; tbl: string; op: string; row_id: number }[];
 
@@ -374,7 +388,7 @@ class _Database<Schemas extends SchemaMap> {
         }
 
         // Clean up consumed changes
-        this.db.query('DELETE FROM "_changes" WHERE id <= ?').run(this._changeWatermark);
+        this._stmt('DELETE FROM "_changes" WHERE id <= ?').run(this._changeWatermark);
     }
 
     // =========================================================================
@@ -385,9 +399,10 @@ class _Database<Schemas extends SchemaMap> {
         return this._m('transaction', () => this.db.transaction(callback)());
     }
 
-    /** Close the database: stops polling and releases the SQLite handle. */
+    /** Close the database: stops polling, clears cache, and releases the SQLite handle. */
     public close(): void {
         this._stopPolling();
+        this._stmtCache.clear();
         this.db.close();
     }
 
@@ -403,7 +418,7 @@ class _Database<Schemas extends SchemaMap> {
             this.schemas,
             callback as any,
             (sql: string, params: any[]) => {
-                return this.db.query(sql).all(...params) as T[];
+                return this._stmt(sql).all(...params) as T[];
             },
         ));
     }
@@ -414,7 +429,7 @@ class _Database<Schemas extends SchemaMap> {
 
     /** Execute a raw SQL query and return results. */
     public raw<T = any>(sql: string, ...params: any[]): T[] {
-        return this._m(`raw: ${sql.slice(0, 60)}`, () => this.db.query(sql).all(...params) as T[]);
+        return this._m(`raw: ${sql.slice(0, 60)}`, () => this._stmt(sql).all(...params) as T[]);
     }
 
     /** Execute a raw SQL statement (INSERT/UPDATE/DELETE) without returning rows. */

package/src/query.ts

@@ -40,7 +40,7 @@ export function createQueryBuilder(ctx: DatabaseContext, entityName: string, ini
 
     const executor = (sql: string, params: any[], raw: boolean): any[] => {
         return ctx._m(`SQL: ${sql.slice(0, 60)}`, () => {
-            const rows = ctx.db.query(sql).all(...params);
+            const rows = ctx._stmt(sql).all(...params);
             if (raw) return rows;
             return rows.map((row: any) => ctx.attachMethods(entityName, transformFromStorage(row, schema)));
         });
@@ -103,7 +103,7 @@ export function createQueryBuilder(ctx: DatabaseContext, entityName: string, ini
             if (belongsTo) {
                 const fk = belongsTo.foreignKey;
                 const placeholders = parentIds.map(() => '?').join(', ');
-                const childRows = ctx.db.query(
+                const childRows = ctx._stmt(
                     `SELECT * FROM ${hasMany.to} WHERE ${fk} IN (${placeholders})`
                 ).all(...parentIds) as any[];