sqlite-zod-orm 3.5.1 → 3.6.0

package/README.md

@@ -41,6 +41,7 @@ const db = new Database(':memory:', {
   relations: {
     books: { author_id: 'authors' },
   },
+  pollInterval: 300, // global default for .on() and .subscribe() (default: 500ms)
 });
 ```
 

package/dist/index.js

@@ -177,7 +177,8 @@ class QueryBuilder {
   conditionResolver;
   revisionGetter;
   eagerLoader;
-  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader) {
+  defaultPollInterval;
+  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader, pollInterval) {
     this.tableName = tableName;
     this.executor = executor;
     this.singleExecutor = singleExecutor;
@@ -185,6 +186,7 @@ class QueryBuilder {
     this.conditionResolver = conditionResolver ?? null;
     this.revisionGetter = revisionGetter ?? null;
     this.eagerLoader = eagerLoader ?? null;
+    this.defaultPollInterval = pollInterval ?? 500;
     this.iqo = {
       selects: [],
       wheres: [],
@@ -357,7 +359,7 @@ class QueryBuilder {
     return results[0]?.count ?? 0;
   }
   subscribe(callback, options = {}) {
-    const { interval = 500, immediate = true } = options;
+    const { interval = this.defaultPollInterval, immediate = true } = options;
     const fingerprintSQL = this.buildFingerprintSQL();
     let lastFingerprint = null;
     const poll = () => {
@@ -4686,6 +4688,7 @@ class _Database {
   schemas;
   relationships;
   options;
+  pollInterval;
   _revisions = {};
   constructor(dbFile, schemas, options = {}) {
     this.db = new SqliteDatabase(dbFile);
@@ -4693,6 +4696,7 @@ class _Database {
     this.db.run("PRAGMA foreign_keys = ON");
     this.schemas = schemas;
     this.options = options;
+    this.pollInterval = options.pollInterval ?? 500;
     this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
     this.initializeTables();
     this.runMigrations();
@@ -4710,7 +4714,13 @@ class _Database {
         upsert: (conditions, data) => this.upsert(entityName, data, conditions),
         delete: (id) => this.delete(entityName, id),
         select: (...cols) => this._createQueryBuilder(entityName, cols),
-        on: (callback, options2) => this._createOnStream(entityName, callback, options2),
+        on: (event, callback, options2) => {
+          if (event === "insert")
+            return this._createOnStream(entityName, callback, options2?.interval);
+          if (event === "change")
+            return this._createChangeStream(entityName, callback, options2?.interval);
+          throw new Error(`Unknown event type: '${event}'. Supported: 'insert', 'change'`);
+        },
         _tableName: entityName
       };
       this[key] = accessor;
@@ -4760,8 +4770,8 @@ class _Database {
     const dataVersion = this.db.query("PRAGMA data_version").get()?.data_version ?? 0;
     return `${rev}:${dataVersion}`;
   }
-  _createOnStream(entityName, callback, options) {
-    const { interval = 500 } = options ?? {};
+  _createOnStream(entityName, callback, intervalOverride) {
+    const interval = intervalOverride ?? this.pollInterval;
     const maxRow = this.db.query(`SELECT MAX(id) as _max FROM "${entityName}"`).get();
     let lastMaxId = maxRow?._max ?? 0;
     let lastRevision = this._getRevision(entityName);
@@ -4789,6 +4799,61 @@ class _Database {
       stopped = true;
     };
   }
+  _createChangeStream(entityName, callback, intervalOverride) {
+    const interval = intervalOverride ?? this.pollInterval;
+    const allRows = this.db.query(`SELECT * FROM "${entityName}" ORDER BY id ASC`).all();
+    let snapshot = new Map;
+    let snapshotEntities = new Map;
+    for (const row of allRows) {
+      snapshot.set(row.id, JSON.stringify(row));
+      snapshotEntities.set(row.id, row);
+    }
+    let lastRevision = this._getRevision(entityName);
+    let stopped = false;
+    const poll = async () => {
+      if (stopped)
+        return;
+      const currentRevision = this._getRevision(entityName);
+      if (currentRevision !== lastRevision) {
+        lastRevision = currentRevision;
+        const currentRows = this.db.query(`SELECT * FROM "${entityName}" ORDER BY id ASC`).all();
+        const currentMap = new Map;
+        const currentEntities = new Map;
+        for (const row of currentRows) {
+          currentMap.set(row.id, JSON.stringify(row));
+          currentEntities.set(row.id, row);
+        }
+        for (const [id, json] of currentMap) {
+          if (stopped)
+            return;
+          if (!snapshot.has(id)) {
+            const entity = this._attachMethods(entityName, transformFromStorage(currentEntities.get(id), this.schemas[entityName]));
+            await callback({ type: "insert", row: entity });
+          } else if (snapshot.get(id) !== json) {
+            const entity = this._attachMethods(entityName, transformFromStorage(currentEntities.get(id), this.schemas[entityName]));
+            const oldEntity = this._attachMethods(entityName, transformFromStorage(snapshotEntities.get(id), this.schemas[entityName]));
+            await callback({ type: "update", row: entity, oldRow: oldEntity });
+          }
+        }
+        for (const [id] of snapshot) {
+          if (stopped)
+            return;
+          if (!currentMap.has(id)) {
+            const oldEntity = this._attachMethods(entityName, transformFromStorage(snapshotEntities.get(id), this.schemas[entityName]));
+            await callback({ type: "delete", row: oldEntity, oldRow: oldEntity });
+          }
+        }
+        snapshot = currentMap;
+        snapshotEntities = currentEntities;
+      }
+      if (!stopped)
+        setTimeout(poll, interval);
+    };
+    setTimeout(poll, interval);
+    return () => {
+      stopped = true;
+    };
+  }
   insert(entityName, data) {
     const schema = this.schemas[entityName];
     const validatedData = asZodObject(schema).passthrough().parse(data);
@@ -5044,7 +5109,7 @@ class _Database {
       }
       return null;
     };
-    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader);
+    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader, this.pollInterval);
     if (initialCols.length > 0)
       builder.select(...initialCols);
     return builder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL",
   "type": "module",
   "main": "./dist/index.js",

package/src/database.ts

@@ -29,6 +29,7 @@ class _Database<Schemas extends SchemaMap> {
     private schemas: Schemas;
     private relationships: Relationship[];
     private options: DatabaseOptions;
+    private pollInterval: number;
 
     /** In-memory revision counter per table — bumps on every write (insert/update/delete).
      *  Used by QueryBuilder.subscribe() fingerprint to detect ALL changes with zero overhead. */
@@ -40,6 +41,7 @@ class _Database<Schemas extends SchemaMap> {
         this.db.run('PRAGMA foreign_keys = ON');
         this.schemas = schemas;
         this.options = options;
+        this.pollInterval = options.pollInterval ?? 500;
         this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
         this.initializeTables();
         this.runMigrations();
@@ -57,8 +59,11 @@ class _Database<Schemas extends SchemaMap> {
                 upsert: (conditions, data) => this.upsert(entityName, data, conditions),
                 delete: (id) => this.delete(entityName, id),
                 select: (...cols: string[]) => this._createQueryBuilder(entityName, cols),
-                on: (callback: (row: any) => void, options?: { interval?: number }) =>
-                    this._createOnStream(entityName, callback, options),
+                on: (event: string, callback: (row: any) => void | Promise<void>, options?: { interval?: number }) => {
+                    if (event === 'insert') return this._createOnStream(entityName, callback, options?.interval);
+                    if (event === 'change') return this._createChangeStream(entityName, callback, options?.interval);
+                    throw new Error(`Unknown event type: '${event}'. Supported: 'insert', 'change'`);
+                },
                 _tableName: entityName,
             };
             (this as any)[key] = accessor;
@@ -152,9 +157,9 @@ class _Database<Schemas extends SchemaMap> {
     public _createOnStream(
         entityName: string,
         callback: (row: any) => void | Promise<void>,
-        options?: { interval?: number },
+        intervalOverride?: number,
     ): () => void {
-        const { interval = 500 } = options ?? {};
+        const interval = intervalOverride ?? this.pollInterval;
 
         // Initialize watermark to current max id (only emit NEW rows)
         const maxRow = this.db.query(`SELECT MAX(id) as _max FROM "${entityName}"`).get() as any;
@@ -199,6 +204,94 @@ class _Database<Schemas extends SchemaMap> {
         return () => { stopped = true; };
     }
 
+    /**
+     * Stream all mutations (insert / update / delete) as ChangeEvent objects.
+     *
+     * Maintains a full snapshot and diffs on each poll.
+     * Heavier than _createOnStream (which only tracks watermark), but catches all changes.
+     */
+    public _createChangeStream(
+        entityName: string,
+        callback: (event: any) => void | Promise<void>,
+        intervalOverride?: number,
+    ): () => void {
+        const interval = intervalOverride ?? this.pollInterval;
+
+        // Build initial snapshot: Map<id, serialized row>
+        const allRows = this.db.query(`SELECT * FROM "${entityName}" ORDER BY id ASC`).all() as any[];
+        let snapshot = new Map<number, string>();
+        let snapshotEntities = new Map<number, any>();
+        for (const row of allRows) {
+            snapshot.set(row.id, JSON.stringify(row));
+            snapshotEntities.set(row.id, row);
+        }
+
+        let lastRevision: string = this._getRevision(entityName);
+        let stopped = false;
+
+        const poll = async () => {
+            if (stopped) return;
+
+            const currentRevision = this._getRevision(entityName);
+            if (currentRevision !== lastRevision) {
+                lastRevision = currentRevision;
+
+                const currentRows = this.db.query(`SELECT * FROM "${entityName}" ORDER BY id ASC`).all() as any[];
+                const currentMap = new Map<number, string>();
+                const currentEntities = new Map<number, any>();
+                for (const row of currentRows) {
+                    currentMap.set(row.id, JSON.stringify(row));
+                    currentEntities.set(row.id, row);
+                }
+
+                // Detect inserts and updates
+                for (const [id, json] of currentMap) {
+                    if (stopped) return;
+                    if (!snapshot.has(id)) {
+                        // INSERT
+                        const entity = this._attachMethods(
+                            entityName,
+                            transformFromStorage(currentEntities.get(id), this.schemas[entityName]!)
+                        );
+                        await callback({ type: 'insert', row: entity });
+                    } else if (snapshot.get(id) !== json) {
+                        // UPDATE
+                        const entity = this._attachMethods(
+                            entityName,
+                            transformFromStorage(currentEntities.get(id), this.schemas[entityName]!)
+                        );
+                        const oldEntity = this._attachMethods(
+                            entityName,
+                            transformFromStorage(snapshotEntities.get(id), this.schemas[entityName]!)
+                        );
+                        await callback({ type: 'update', row: entity, oldRow: oldEntity });
+                    }
+                }
+
+                // Detect deletes
+                for (const [id] of snapshot) {
+                    if (stopped) return;
+                    if (!currentMap.has(id)) {
+                        const oldEntity = this._attachMethods(
+                            entityName,
+                            transformFromStorage(snapshotEntities.get(id), this.schemas[entityName]!)
+                        );
+                        await callback({ type: 'delete', row: oldEntity, oldRow: oldEntity });
+                    }
+                }
+
+                snapshot = currentMap;
+                snapshotEntities = currentEntities;
+            }
+
+            if (!stopped) setTimeout(poll, interval);
+        };
+
+        setTimeout(poll, interval);
+
+        return () => { stopped = true; };
+    }
+
     // ===========================================================================
     // CRUD
     // ===========================================================================
@@ -547,7 +640,7 @@ class _Database<Schemas extends SchemaMap> {
             return null;
         };
 
-        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader);
+        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter, eagerLoader, this.pollInterval);
         if (initialCols.length > 0) builder.select(...initialCols);
         return builder;
     }

package/src/index.ts

@@ -7,7 +7,7 @@ export { Database } from './database';
 export type { DatabaseType } from './database';
 
 export type {
-    SchemaMap, DatabaseOptions, Relationship,
+    SchemaMap, DatabaseOptions, Relationship, ChangeEvent,
     EntityAccessor, TypedAccessors, AugmentedEntity, UpdateBuilder,
     InferSchema, EntityData, IndexDef,
     ProxyColumns, ColumnRef,

package/src/query-builder.ts

@@ -174,6 +174,7 @@ export class QueryBuilder<T extends Record<string, any>> {
     private conditionResolver: ((conditions: Record<string, any>) => Record<string, any>) | null;
     private revisionGetter: (() => string) | null;
     private eagerLoader: ((parentTable: string, relation: string, parentIds: number[]) => { key: string; groups: Map<number, any[]> } | null) | null;
+    private defaultPollInterval: number;
 
     constructor(
         tableName: string,
@@ -183,6 +184,7 @@ export class QueryBuilder<T extends Record<string, any>> {
         conditionResolver?: ((conditions: Record<string, any>) => Record<string, any>) | null,
         revisionGetter?: (() => string) | null,
         eagerLoader?: ((parentTable: string, relation: string, parentIds: number[]) => { key: string; groups: Map<number, any[]> } | null) | null,
+        pollInterval?: number,
     ) {
         this.tableName = tableName;
         this.executor = executor;
@@ -191,6 +193,7 @@ export class QueryBuilder<T extends Record<string, any>> {
         this.conditionResolver = conditionResolver ?? null;
         this.revisionGetter = revisionGetter ?? null;
         this.eagerLoader = eagerLoader ?? null;
+        this.defaultPollInterval = pollInterval ?? 500;
         this.iqo = {
             selects: [],
             wheres: [],
@@ -497,7 +500,7 @@ export class QueryBuilder<T extends Record<string, any>> {
         callback: (rows: T[]) => void,
         options: { interval?: number; immediate?: boolean } = {},
     ): () => void {
-        const { interval = 500, immediate = true } = options;
+        const { interval = this.defaultPollInterval, immediate = true } = options;
 
         // Build the fingerprint SQL (COUNT + MAX(id)) using the same WHERE
         const fingerprintSQL = this.buildFingerprintSQL();

package/src/types.ts

@@ -30,6 +30,11 @@ export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
      * `books: { author_id: 'authors' }` → FOREIGN KEY, lazy nav, fluent join.
      */
     relations?: R;
+    /**
+     * Global polling interval (ms) for `.on()` and `.subscribe()`.
+     * Can be overridden per-call. Default: 500ms.
+     */
+    pollInterval?: number;
 };
 
 export type Relationship = {
@@ -40,6 +45,13 @@ export type Relationship = {
     foreignKey: string;
 };
 
+/** Change event emitted by .on('change', callback) */
+export type ChangeEvent<T = any> = {
+    type: 'insert' | 'update' | 'delete';
+    row: T;
+    oldRow?: T;   // present on 'update' and 'delete'
+};
+
 // =============================================================================
 // Type Helpers
 // =============================================================================
@@ -144,12 +156,18 @@ export type NavEntityAccessor<
     delete: (id: number) => void;
     select: (...cols: (keyof z.infer<S[Table & keyof S]> & string)[]) => QueryBuilder<NavEntity<S, R, Table>>;
     /**
-     * Stream new rows one at a time, in insertion order.
-     * Only emits rows inserted AFTER subscription starts.
+     * Listen for table events.
+     *
+     * `'insert'` — streams new rows one at a time, in insertion order.
+     * `'change'` — streams all mutations: { type: 'insert'|'update'|'delete', row, oldRow? }.
+     *
      * Callbacks are awaited — strict ordering guaranteed even with async handlers.
      * @returns Unsubscribe function.
      */
-    on: (callback: (row: NavEntity<S, R, Table>) => void | Promise<void>, options?: { interval?: number }) => () => void;
+    on: {
+        (event: 'insert', callback: (row: NavEntity<S, R, Table>) => void | Promise<void>, options?: { interval?: number }): () => void;
+        (event: 'change', callback: (event: ChangeEvent<NavEntity<S, R, Table>>) => void | Promise<void>, options?: { interval?: number }): () => void;
+    };
     _tableName: string;
     readonly _schema?: S[Table & keyof S];
 };
@@ -176,12 +194,18 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     delete: (id: number) => void;
     select: (...cols: (keyof InferSchema<S> & string)[]) => QueryBuilder<AugmentedEntity<S>>;
     /**
-     * Stream new rows one at a time, in insertion order.
-     * Only emits rows inserted AFTER subscription starts.
+     * Listen for table events.
+     *
+     * `'insert'` — streams new rows one at a time, in insertion order.
+     * `'change'` — streams all mutations: { type: 'insert'|'update'|'delete', row, oldRow? }.
+     *
      * Callbacks are awaited — strict ordering guaranteed even with async handlers.
      * @returns Unsubscribe function.
      */
-    on: (callback: (row: AugmentedEntity<S>) => void | Promise<void>, options?: { interval?: number }) => () => void;
+    on: {
+        (event: 'insert', callback: (row: AugmentedEntity<S>) => void | Promise<void>, options?: { interval?: number }): () => void;
+        (event: 'change', callback: (event: ChangeEvent<AugmentedEntity<S>>) => void | Promise<void>, options?: { interval?: number }): () => void;
+    };
     _tableName: string;
     readonly _schema?: S;
 };