sqlite-zod-orm 3.10.0 → 3.12.0

package/src/database.ts

@@ -41,6 +41,9 @@ type Listener = {
 class _Database<Schemas extends SchemaMap> {
     private db: SqliteDatabase;
     private _reactive: boolean;
+    private _timestamps: boolean;
+    private _softDeletes: boolean;
+    private _debug: boolean;
     private schemas: Schemas;
     private relationships: Relationship[];
     private options: DatabaseOptions;
@@ -67,6 +70,9 @@ class _Database<Schemas extends SchemaMap> {
         this.schemas = schemas;
         this.options = options;
         this._reactive = options.reactive !== false; // default true
+        this._timestamps = options.timestamps === true;
+        this._softDeletes = options.softDeletes === true;
+        this._debug = options.debug === true;
         this._pollInterval = options.pollInterval ?? 100;
         this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
 
@@ -77,12 +83,16 @@ class _Database<Schemas extends SchemaMap> {
             relationships: this.relationships,
             attachMethods: (name, entity) => attachMethods(this._ctx, name, entity),
             buildWhereClause: (conds, prefix) => buildWhereClause(conds, prefix),
+            debug: this._debug,
+            timestamps: this._timestamps,
+            softDeletes: this._softDeletes,
         };
 
         this.initializeTables();
         if (this._reactive) this.initializeChangeTracking();
         this.runMigrations();
         if (options.indexes) this.createIndexes(options.indexes);
+        if (options.unique) this.createUniqueConstraints(options.unique);
 
         // Create typed entity accessors (db.users, db.posts, etc.)
         for (const entityName of Object.keys(schemas)) {
@@ -96,9 +106,22 @@ class _Database<Schemas extends SchemaMap> {
                 },
                 upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
                 delete: ((id?: any) => {
-                    if (typeof id === 'number') return deleteEntity(this._ctx, entityName, id);
+                    if (typeof id === 'number') {
+                        if (this._softDeletes) {
+                            // Soft delete: set deletedAt instead of removing
+                            const now = new Date().toISOString();
+                            this.db.query(`UPDATE "${entityName}" SET "deletedAt" = ? WHERE id = ?`).run(now, id);
+                            return;
+                        }
+                        return deleteEntity(this._ctx, entityName, id);
+                    }
                     return createDeleteBuilder(this._ctx, entityName);
                 }) as any,
+                restore: ((id: number) => {
+                    if (!this._softDeletes) throw new Error('restore() requires softDeletes: true');
+                    if (this._debug) console.log('[satidb]', `UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`, [id]);
+                    this.db.query(`UPDATE "${entityName}" SET "deletedAt" = NULL WHERE id = ?`).run(id);
+                }) as any,
                 select: (...cols: string[]) => createQueryBuilder(this._ctx, entityName, cols),
                 on: (event: ChangeEvent, callback: (row: any) => void | Promise<void>) => {
                     return this._registerListener(entityName, event, callback);
@@ -117,6 +140,17 @@ class _Database<Schemas extends SchemaMap> {
         for (const [entityName, schema] of Object.entries(this.schemas)) {
             const storableFields = getStorableFields(schema);
             const columnDefs = storableFields.map(f => `"${f.name}" ${zodTypeToSqlType(f.type)}`);
+
+            // Add timestamp columns
+            if (this._timestamps) {
+                columnDefs.push('"createdAt" TEXT');
+                columnDefs.push('"updatedAt" TEXT');
+            }
+            // Add soft delete column
+            if (this._softDeletes) {
+                columnDefs.push('"deletedAt" TEXT');
+            }
+
             const constraints: string[] = [];
 
             const belongsToRels = this.relationships.filter(
@@ -200,6 +234,15 @@ class _Database<Schemas extends SchemaMap> {
         }
     }
 
+    private createUniqueConstraints(unique: Record<string, string[][]>): void {
+        for (const [tableName, groups] of Object.entries(unique)) {
+            for (const cols of groups) {
+                const idxName = `uq_${tableName}_${cols.join('_')}`;
+                this.db.run(`CREATE UNIQUE INDEX IF NOT EXISTS "${idxName}" ON "${tableName}" (${cols.map(c => `"${c}"`).join(', ')})`);
+            }
+        }
+    }
+
     // =========================================================================
     // Change Listeners — db.table.on('insert' | 'update' | 'delete', cb)
     // =========================================================================
@@ -278,7 +321,7 @@ class _Database<Schemas extends SchemaMap> {
         }
 
         // Clean up consumed changes
-        this.db.run('DELETE FROM "_changes" WHERE id <= ?', this._changeWatermark);
+        this.db.query('DELETE FROM "_changes" WHERE id <= ?').run(this._changeWatermark);
     }
 
     // =========================================================================
@@ -306,9 +349,42 @@ class _Database<Schemas extends SchemaMap> {
         return executeProxyQuery(
             this.schemas,
             callback as any,
-            (sql: string, params: any[]) => this.db.query(sql).all(...params) as T[],
+            (sql: string, params: any[]) => {
+                if (this._debug) console.log('[satidb]', sql, params);
+                return this.db.query(sql).all(...params) as T[];
+            },
         );
     }
+
+    // =========================================================================
+    // Raw SQL
+    // =========================================================================
+
+    /** Execute a raw SQL query and return results. */
+    public raw<T = any>(sql: string, ...params: any[]): T[] {
+        if (this._debug) console.log('[satidb]', sql, params);
+        return this.db.query(sql).all(...params) as T[];
+    }
+
+    /** Execute a raw SQL statement (INSERT/UPDATE/DELETE) without returning rows. */
+    public exec(sql: string, ...params: any[]): void {
+        if (this._debug) console.log('[satidb]', sql, params);
+        this.db.run(sql, ...params);
+    }
+
+    // =========================================================================
+    // Schema Introspection
+    // =========================================================================
+
+    /** Return the list of user-defined table names. */
+    public tables(): string[] {
+        return Object.keys(this.schemas);
+    }
+
+    /** Return column info for a table via PRAGMA table_info. */
+    public columns(tableName: string): { name: string; type: string; notnull: number; pk: number }[] {
+        return this.db.query(`PRAGMA table_info("${tableName}")`).all() as any[];
+    }
 }
 
 // =============================================================================

package/src/helpers.ts

@@ -13,6 +13,7 @@ import { transformForStorage } from './schema';
  * - Operators: `{ age: { $gt: 18 } }`
  * - $in: `{ status: { $in: ['active', 'pending'] } }`
  * - $or: `{ $or: [{ name: 'Alice' }, { name: 'Bob' }] }`
+ * - $isNull / $isNotNull: `{ deletedAt: { $isNull: true } }`
  */
 export function buildWhereClause(conditions: Record<string, any>, tablePrefix?: string): { clause: string; values: any[] } {
     const parts: string[] = [];
@@ -73,6 +74,16 @@ export function buildWhereClause(conditions: Record<string, any>, tablePrefix?:
                 continue;
             }
 
+            if (operator === '$isNull') {
+                parts.push(`${fieldName} IS NULL`);
+                continue;
+            }
+
+            if (operator === '$isNotNull') {
+                parts.push(`${fieldName} IS NOT NULL`);
+                continue;
+            }
+
             const sqlOp = ({ $gt: '>', $gte: '>=', $lt: '<', $lte: '<=', $ne: '!=' } as Record<string, string>)[operator];
             if (!sqlOp) throw new Error(`Unsupported operator '${operator}' on '${key}'`);
             parts.push(`${fieldName} ${sqlOp} ?`);

package/src/index.ts

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

package/src/iqo.ts

@@ -12,11 +12,11 @@ import { type ASTNode, compileAST } from './ast';
 // =============================================================================
 
 export type OrderDirection = 'asc' | 'desc';
-export type WhereOperator = '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$like' | '$notIn' | '$between';
+export type WhereOperator = '$gt' | '$gte' | '$lt' | '$lte' | '$ne' | '$in' | '$like' | '$notIn' | '$between' | '$isNull' | '$isNotNull';
 
 export interface WhereCondition {
     field: string;
-    operator: '=' | '>' | '>=' | '<' | '<=' | '!=' | 'IN' | 'LIKE' | 'NOT IN' | 'BETWEEN';
+    operator: '=' | '>' | '>=' | '<' | '<=' | '!=' | 'IN' | 'LIKE' | 'NOT IN' | 'BETWEEN' | 'IS NULL' | 'IS NOT NULL';
     value: any;
 }
 
@@ -34,11 +34,13 @@ export interface IQO {
     whereAST: ASTNode | null;
     joins: JoinClause[];
     groupBy: string[];
+    having: WhereCondition[];
     limit: number | null;
     offset: number | null;
     orderBy: { field: string; direction: OrderDirection }[];
     includes: string[];
     raw: boolean;
+    distinct: boolean;
 }
 
 export const OPERATOR_MAP: Record<WhereOperator, string> = {
@@ -51,6 +53,8 @@ export const OPERATOR_MAP: Record<WhereOperator, string> = {
     $like: 'LIKE',
     $notIn: 'NOT IN',
     $between: 'BETWEEN',
+    $isNull: 'IS NULL',
+    $isNotNull: 'IS NOT NULL',
 };
 
 export function transformValueForStorage(value: any): any {
@@ -81,7 +85,7 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
         }
     }
 
-    let sql = `SELECT ${selectParts.join(', ')} FROM ${tableName}`;
+    let sql = `SELECT ${iqo.distinct ? 'DISTINCT ' : ''}${selectParts.join(', ')} FROM ${tableName}`;
 
     // JOIN clauses
     for (const j of iqo.joins) {
@@ -119,6 +123,10 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
                 const [min, max] = w.value as [any, any];
                 whereParts.push(`${qualify(w.field)} BETWEEN ? AND ?`);
                 params.push(transformValueForStorage(min), transformValueForStorage(max));
+            } else if (w.operator === 'IS NULL') {
+                whereParts.push(`${qualify(w.field)} IS NULL`);
+            } else if (w.operator === 'IS NOT NULL') {
+                whereParts.push(`${qualify(w.field)} IS NOT NULL`);
             } else {
                 whereParts.push(`${qualify(w.field)} ${w.operator} ?`);
                 params.push(transformValueForStorage(w.value));
@@ -159,6 +167,24 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
         sql += ` GROUP BY ${iqo.groupBy.join(', ')}`;
     }
 
+    // HAVING
+    if (iqo.having && iqo.having.length > 0) {
+        const havingParts: string[] = [];
+        for (const h of iqo.having) {
+            if (h.operator === 'IS NULL') {
+                havingParts.push(`${h.field} IS NULL`);
+            } else if (h.operator === 'IS NOT NULL') {
+                havingParts.push(`${h.field} IS NOT NULL`);
+            } else {
+                havingParts.push(`${h.field} ${h.operator} ?`);
+                params.push(transformValueForStorage(h.value));
+            }
+        }
+        if (havingParts.length > 0) {
+            sql += ` HAVING ${havingParts.join(' AND ')}`;
+        }
+    }
+
     // ORDER BY
     if (iqo.orderBy.length > 0) {
         const parts = iqo.orderBy.map(o => `${o.field} ${o.direction.toUpperCase()}`);

package/src/query.ts

@@ -39,6 +39,7 @@ export function createQueryBuilder(ctx: DatabaseContext, entityName: string, ini
     const schema = ctx.schemas[entityName]!;
 
     const executor = (sql: string, params: any[], raw: boolean): any[] => {
+        if (ctx.debug) console.log('[satidb]', sql, params);
         const rows = ctx.db.query(sql).all(...params);
         if (raw) return rows;
         return rows.map((row: any) => ctx.attachMethods(entityName, transformFromStorage(row, schema)));
@@ -132,5 +133,11 @@ export function createQueryBuilder(ctx: DatabaseContext, entityName: string, ini
 
     const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, conditionResolver, eagerLoader);
     if (initialCols.length > 0) builder.select(...initialCols);
+
+    // Auto-filter soft-deleted rows unless withTrashed() is called
+    if (ctx.softDeletes) {
+        builder.where({ deletedAt: { $isNull: true } });
+    }
+
     return builder;
 }

package/src/types.ts

@@ -19,9 +19,14 @@ export const asZodObject = (s: z.ZodType<any>) => s as unknown as z.ZodObject<an
 /** Index definition: single column or composite columns */
 export type IndexDef = string | string[];
 
-/** Options for the Database constructor */
 export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
     indexes?: Record<string, IndexDef[]>;
+    /**
+     * Unique constraints per table. Each entry is an array of column groups.
+     * Single column: `{ users: [['email']] }` → UNIQUE INDEX.
+     * Compound: `{ users: [['email'], ['name', 'org_id']] }` → two UNIQUE indexes.
+     */
+    unique?: Record<string, string[][]>;
     /**
      * Declare relationships between tables.
      *
@@ -42,6 +47,24 @@ export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
      * `.on()` will throw. Default: `true`.
      */
     reactive?: boolean;
+    /**
+     * Auto-add `createdAt` and `updatedAt` TEXT columns to every table.
+     * `createdAt` is set on insert, `updatedAt` on insert + update.
+     * Default: `false`.
+     */
+    timestamps?: boolean;
+    /**
+     * Enable soft deletes. Adds a `deletedAt` TEXT column to every table.
+     * `delete()` sets `deletedAt` instead of removing the row.
+     * Use `.withTrashed()` on queries to include soft-deleted rows.
+     * Default: `false`.
+     */
+    softDeletes?: boolean;
+    /**
+     * Log every SQL query to the console. Useful for debugging.
+     * Default: `false`.
+     */
+    debug?: boolean;
 };
 
 export type Relationship = {
@@ -162,6 +185,7 @@ export type NavEntityAccessor<
     & ((data: Partial<Omit<z.input<S[Table & keyof S]>, 'id'>>) => UpdateBuilder<NavEntity<S, R, Table>>);
     upsert: (conditions?: Partial<z.infer<S[Table & keyof S]>>, data?: Partial<z.infer<S[Table & keyof S]>>) => NavEntity<S, R, Table>;
     delete: ((id: number) => void) & (() => DeleteBuilder<NavEntity<S, R, Table>>);
+    restore: (id: number) => void;
     select: (...cols: (keyof z.infer<S[Table & keyof S]> & string)[]) => QueryBuilder<NavEntity<S, R, Table>>;
     on: ((event: 'insert' | 'update', callback: (row: NavEntity<S, R, Table>) => void | Promise<void>) => () => void) &
     ((event: 'delete', callback: (row: { id: number }) => void | Promise<void>) => () => void);
@@ -192,6 +216,8 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     update: ((id: number, data: Partial<EntityData<S>>) => AugmentedEntity<S> | null) & ((data: Partial<EntityData<S>>) => UpdateBuilder<AugmentedEntity<S>>);
     upsert: (conditions?: Partial<InferSchema<S>>, data?: Partial<InferSchema<S>>) => AugmentedEntity<S>;
     delete: ((id: number) => void) & (() => DeleteBuilder<AugmentedEntity<S>>);
+    /** Undo a soft delete by setting deletedAt = null. Requires softDeletes. */
+    restore: (id: number) => void;
     select: (...cols: (keyof InferSchema<S> & string)[]) => QueryBuilder<AugmentedEntity<S>>;
     on: ((event: 'insert' | 'update', callback: (row: AugmentedEntity<S>) => void | Promise<void>) => () => void) &
     ((event: 'delete', callback: (row: { id: number }) => void | Promise<void>) => () => void);