@gobing-ai/ts-db 0.1.8 → 0.2.1

package/dist/entity-dao.d.ts

@@ -1,7 +1,8 @@
 import { type SQL } from 'drizzle-orm';
 import type { SQLiteColumn, SQLiteTable } from 'drizzle-orm/sqlite-core';
-import type { DbClient } from './adapter';
+import type { DbAdapter } from './adapter';
 import { BaseDao } from './base-dao';
+import { type OrderTerm, type Predicate } from './query-spec';
 /**
  * Type for tables compatible with EntityDao.
  * Must have standard columns: createdAt, updatedAt.
@@ -10,134 +11,136 @@ export type EntityTable = SQLiteTable & {
     createdAt: SQLiteColumn;
     updatedAt: SQLiteColumn;
 };
-/**
- * Type for tables with soft delete support.
- */
+/** Type for tables with soft delete support. */
 export type SoftDeletableTable = EntityTable & {
     inUsed: SQLiteColumn;
 };
-/**
- * Type for primary key columns.
- */
+/** Type for primary key columns (single column or a tuple for composite keys). */
 export type PKColumn = SQLiteColumn;
+/** A primary key value: a single value, or a tuple for composite keys. */
+export type PKValue = string | number | (string | number)[];
+/** Options for the structured `list` operation. */
+export interface EntityListSpec {
+    where?: Predicate;
+    orderBy?: readonly OrderTerm[];
+    limit?: number;
+    offset?: number;
+    includeDeleted?: boolean;
+}
+/** Options for keyset/cursor pagination. */
+export interface CursorListSpec {
+    /** Opaque cursor from a previous page (the last row's keyset value). */
+    cursor?: string | number;
+    /** Column the cursor walks (must be unique + ordered, e.g. the primary key). */
+    cursorColumn: SQLiteColumn;
+    /** Page size. */
+    limit: number;
+    where?: Predicate;
+    direction?: 'asc' | 'desc';
+    includeDeleted?: boolean;
+}
 /**
- * Generic CRUD base class for entity DAOs.
+ * Generic CRUD base class for entity DAOs — the STRUCTURED tier of the facade.
  *
- * Provides standard create, read, update, delete operations with:
- * - Type-safe public API using Drizzle's inference types
- * - Automatic soft delete filtering (if table has `inUsed` column)
+ * Extends {@link BaseDao} (raw tier) with typed create/read/update/delete over a
+ * single table, using RETURNING, drizzle-free predicate filters, soft-delete
+ * auto-filtering, batch insert, upsert, and cursor pagination. drizzle is hidden
+ * entirely — consumers use ts-db vocabulary. (G1/G3)
  *
- * @typeParam TTable - The table type (must extend EntityTable)
- * @typeParam TPK - The primary key column type
+ * @typeParam TTable - The table type (must extend EntityTable).
+ * @typeParam TPK - The primary key column type.
  *
  * @example
  * ```ts
- * export class UsersDao extends EntityDao<typeof users, typeof users.id> {
- *     constructor(db: DbClient) {
- *         super(db, users, users.id, 'users');
+ * class UsersDao extends EntityDao<typeof users, typeof users.id> {
+ *     constructor(adapter: DbAdapter) {
+ *         super(adapter, users, [users.id], 'users');
  *     }
- *
- *     // Add entity-specific methods here
- *     async findByEmail(email: string) {
+ *     findByEmail(email: string) {
  *         return this.findBy(users.email, email);
  *     }
  * }
  * ```
  */
+/**
+ * A structural validator (e.g. a zod schema). Kept structural so EntityDao never
+ * imports zod/drizzle-zod — consumers wire `defineTable().insertSchema` here when
+ * they want boundary validation.
+ */
+export interface DaoValidator {
+    parse(input: unknown): unknown;
+}
+/** Optional EntityDao configuration. */
+export interface EntityDaoOptions {
+    /** Schema used to validate input before `create`/`createMany`/`upsert`. */
+    insertSchema?: DaoValidator;
+    /** Schema used to validate input before `update`. Falls back to `insertSchema` when absent. */
+    updateSchema?: DaoValidator;
+    /** Which write operations validate. Default: all (`create`, `createMany`, `upsert`, `update`) when a schema is present. */
+    validateOn?: ('create' | 'createMany' | 'upsert' | 'update')[];
+}
 export declare class EntityDao<TTable extends EntityTable, TPK extends SQLiteColumn> extends BaseDao {
     readonly table: TTable;
-    protected readonly primaryKey: TPK;
+    /** Primary key columns. A single-element array for single-PK tables, multiple for composite. */
+    protected readonly primaryKey: SQLiteColumn[];
     protected readonly collectionName: string;
-    constructor(db: DbClient, table: TTable, primaryKey: TPK, collectionName: string);
-    /**
-     * Check if the table has soft delete support (inUsed column).
-     */
+    private readonly validation;
+    constructor(adapter: DbAdapter, table: TTable, primaryKey: TPK | SQLiteColumn[], collectionName: string, options?: EntityDaoOptions);
+    /** Validate input against the configured schema for an operation, when enabled. */
+    private validate;
+    /** Check if the table has soft delete support (inUsed column). */
     protected get hasSoftDelete(): boolean;
-    /**
-     * Build a where condition that filters out soft-deleted records.
-     * Returns undefined if the table doesn't support soft delete.
-     */
+    /** Condition filtering out soft-deleted rows, or undefined when unsupported. */
     protected get activeCondition(): SQL | undefined;
+    /** Build the where-condition matching a primary key value (single or composite). */
+    private pkCondition;
+    private get insertBuilder();
     /**
-     * Create a new record.
-     *
-     * `createdAt` and `updatedAt` are auto-filled if not provided.
-     *
-     * @param data - The data to insert (createdAt/updatedAt optional).
-     * @returns The created record.
+     * Create a new record. `createdAt`/`updatedAt` are auto-filled if absent.
+     * Returns the row as written by the database (RETURNING).
      */
     create(data: Omit<TTable['$inferInsert'], 'createdAt' | 'updatedAt'> & {
         createdAt?: number;
         updatedAt?: number;
     }): Promise<TTable['$inferSelect']>;
     /**
-     * Find a record by its primary key.
-     *
-     * @param id - The primary key value.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns The record if found, otherwise undefined.
+     * Insert many records in a single multi-VALUES statement (efficient for ETL).
+     * Returns the written rows (RETURNING).
      */
-    findById(id: string | number, includeDeleted?: boolean): Promise<TTable['$inferSelect'] | undefined>;
+    createMany(data: (Omit<TTable['$inferInsert'], 'createdAt' | 'updatedAt'> & {
+        createdAt?: number;
+        updatedAt?: number;
+    })[]): Promise<TTable['$inferSelect'][]>;
     /**
-     * Find all records.
-     *
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns Array of records.
+     * Insert or update on conflict. `conflictColumns` identify the unique target;
+     * `update` (or all non-conflict columns) are written on conflict. Returns the row.
      */
+    upsert(data: Omit<TTable['$inferInsert'], 'createdAt' | 'updatedAt'> & {
+        createdAt?: number;
+        updatedAt?: number;
+    }, conflictColumns: SQLiteColumn[], updateColumns?: Partial<TTable['$inferInsert']>): Promise<TTable['$inferSelect']>;
+    /** Find a record by its primary key (single value or composite tuple). */
+    findById(id: PKValue, includeDeleted?: boolean): Promise<TTable['$inferSelect'] | undefined>;
+    /** Find all records (optionally including soft-deleted). */
     findAll(includeDeleted?: boolean): Promise<TTable['$inferSelect'][]>;
-    /**
-     * Update a record by its primary key.
-     *
-     * @param id - The primary key value.
-     * @param data - The data to update.
-     * @returns The updated record if found, otherwise undefined.
-     */
-    update(id: string | number, data: Partial<TTable['$inferInsert']>): Promise<TTable['$inferSelect'] | undefined>;
-    /**
-     * Delete a record by its primary key.
-     *
-     * @param id - The primary key value.
-     * @param soft - Whether to perform a soft delete (default: true if table supports it).
-     * @returns The deleted record (for soft delete), otherwise undefined.
-     */
-    delete(id: string | number, soft?: boolean): Promise<TTable['$inferSelect'] | undefined>;
-    /**
-     * Find a record by a specific column value.
-     *
-     * @param column - The column to search.
-     * @param value - The value to match.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns The record if found, otherwise undefined.
-     */
+    /** Find the first record matching a column value. */
     findBy<TCol extends SQLiteColumn>(column: TCol, value: TCol['_']['data'], includeDeleted?: boolean): Promise<TTable['$inferSelect'] | undefined>;
-    /**
-     * Find all records matching a specific column value.
-     *
-     * @param column - The column to search.
-     * @param value - The value to match.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns Array of matching records.
-     */
+    /** Find all records matching a column value. */
     findAllBy<TCol extends SQLiteColumn>(column: TCol, value: TCol['_']['data'], includeDeleted?: boolean): Promise<TTable['$inferSelect'][]>;
-    /**
-     * List records with pagination and optional filtering.
-     *
-     * @param options - List options (limit, offset, where).
-     * @returns Array of records.
-     */
-    list(options?: {
-        limit?: number;
-        offset?: number;
-        where?: SQL;
-        includeDeleted?: boolean;
-    }): Promise<TTable['$inferSelect'][]>;
-    /**
-     * Count records in the table.
-     *
-     * @param where - Optional filter condition.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns The count of matching records.
-     */
-    count(where?: SQL, includeDeleted?: boolean): Promise<number>;
+    /** Update a record by primary key. `updatedAt` is refreshed. Returns the updated row. */
+    update(id: PKValue, data: Partial<TTable['$inferInsert']>): Promise<TTable['$inferSelect'] | undefined>;
+    /** Delete a record by primary key. Soft-deletes when the table supports it (default). */
+    delete(id: PKValue, soft?: boolean): Promise<TTable['$inferSelect'] | undefined>;
+    /** List records with predicate filter, ordering, and offset pagination. */
+    list(spec?: EntityListSpec): Promise<TTable['$inferSelect'][]>;
+    /** List one keyset page; returns the rows and the cursor for the next page. */
+    listByCursor(spec: CursorListSpec): Promise<{
+        rows: TTable['$inferSelect'][];
+        nextCursor?: string | number;
+    }>;
+    /** Count records matching an optional predicate. */
+    count(where?: Predicate, includeDeleted?: boolean): Promise<number>;
+    /** Combine a caller predicate with the soft-delete active filter. */
+    private withActive;
 }
 //# sourceMappingURL=entity-dao.d.ts.map

package/dist/entity-dao.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-dao.d.ts","sourceRoot":"","sources":["../src/entity-dao.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACpC,SAAS,EAAE,YAAY,CAAC;IACxB,SAAS,EAAE,YAAY,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG;IAC3C,MAAM,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,SAAS,CAAC,MAAM,SAAS,WAAW,EAAE,GAAG,SAAS,YAAY,CAAE,SAAQ,OAAO;aAGpE,KAAK,EAAE,MAAM;IAC7B,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG;IAClC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM;gBAHzC,EAAE,EAAE,QAAQ,EACI,KAAK,EAAE,MAAM,EACV,UAAU,EAAE,GAAG,EACf,cAAc,EAAE,MAAM;IAK7C;;OAEG;IACH,SAAS,KAAK,aAAa,IAAI,OAAO,CAErC;IAED;;;OAGG;IACH,SAAS,KAAK,eAAe,IAAI,GAAG,GAAG,SAAS,CAK/C;IAED;;;;;;;OAOG;IACG,MAAM,CACR,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3G,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAalC;;;;;;OAMG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,cAAc,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAcxG;;;;;OAKG;IACG,OAAO,CAAC,cAAc,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;IAUxE;;;;;;OAMG;IACG,MAAM,CACR,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GACtC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAY9C;;;;;;OAMG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAkB9F;;;;;;;OAOG;IACG,MAAM,CAAC,IAAI,SAAS,YAAY,EAClC,MAAM,EAAE,IAAI,EACZ,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EACxB,cAAc,UAAQ,GACvB,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAc9C;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,SAAS,YAAY,EACrC,MAAM,EAAE,IAAI,EACZ,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EACxB,cAAc,UAAQ,GACvB,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;IAYpC;;;;;OAKG;IACG,IAAI,CACN,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,GAAG,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAO,GACzF,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;IAwBpC;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,cAAc,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;CAepE"}
+{"version":3,"file":"entity-dao.d.ts","sourceRoot":"","sources":["../src/entity-dao.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAEhF;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACpC,SAAS,EAAE,YAAY,CAAC;IACxB,SAAS,EAAE,YAAY,CAAC;CAC3B,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG;IAC3C,MAAM,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC;AAEpC,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAE5D,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC3B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC3B,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,gFAAgF;IAChF,YAAY,EAAE,YAAY,CAAC;IAC3B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC7B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,+FAA+F;IAC/F,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,2HAA2H;IAC3H,UAAU,CAAC,EAAE,CAAC,QAAQ,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC;CAClE;AAED,qBAAa,SAAS,CAAC,MAAM,SAAS,WAAW,EAAE,GAAG,SAAS,YAAY,CAAE,SAAQ,OAAO;IACxF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC;IAC9C,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;gBAG1C,OAAO,EAAE,SAAS,EAClB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,GAAG,GAAG,YAAY,EAAE,EAChC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,gBAAqB;IASlC,mFAAmF;IACnF,OAAO,CAAC,QAAQ;IAUhB,kEAAkE;IAClE,SAAS,KAAK,aAAa,IAAI,OAAO,CAErC;IAED,gFAAgF;IAChF,SAAS,KAAK,eAAe,IAAI,GAAG,GAAG,SAAS,CAK/C;IAED,oFAAoF;IACpF,OAAO,CAAC,WAAW;IAWnB,OAAO,KAAK,aAAa,GAExB;IAED;;;OAGG;IACG,MAAM,CACR,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3G,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAUlC;;;OAGG;IACG,UAAU,CACZ,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG;QAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,EAAE,GACL,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;IAUpC;;;OAGG;IACG,MAAM,CACR,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1G,eAAe,EAAE,YAAY,EAAE,EAC/B,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAChD,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IA8BlC,0EAA0E;IACpE,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,cAAc,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAUhG,4DAA4D;IACtD,OAAO,CAAC,cAAc,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;IAIxE,qDAAqD;IAC/C,MAAM,CAAC,IAAI,SAAS,YAAY,EAClC,MAAM,EAAE,IAAI,EACZ,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EACxB,cAAc,UAAQ,GACvB,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAK9C,gDAAgD;IAC1C,SAAS,CAAC,IAAI,SAAS,YAAY,EACrC,MAAM,EAAE,IAAI,EACZ,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,EACxB,cAAc,UAAQ,GACvB,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;IAIpC,yFAAyF;IACnF,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAe7G,yFAAyF;IACnF,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;IAatF,2EAA2E;IACrE,IAAI,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;IAUxE,+EAA+E;IACzE,YAAY,CACd,IAAI,EAAE,cAAc,GACrB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAqB5E,oDAAoD;IAC9C,KAAK,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,cAAc,UAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBvE,qEAAqE;IACrE,OAAO,CAAC,UAAU;CAMrB"}

package/dist/entity-dao.js

@@ -1,218 +1,193 @@
 import { and, count as countFn, eq } from 'drizzle-orm';
 import { BaseDao } from './base-dao.js';
-/**
- * Generic CRUD base class for entity DAOs.
- *
- * Provides standard create, read, update, delete operations with:
- * - Type-safe public API using Drizzle's inference types
- * - Automatic soft delete filtering (if table has `inUsed` column)
- *
- * @typeParam TTable - The table type (must extend EntityTable)
- * @typeParam TPK - The primary key column type
- *
- * @example
- * ```ts
- * export class UsersDao extends EntityDao<typeof users, typeof users.id> {
- *     constructor(db: DbClient) {
- *         super(db, users, users.id, 'users');
- *     }
- *
- *     // Add entity-specific methods here
- *     async findByEmail(email: string) {
- *         return this.findBy(users.email, email);
- *     }
- * }
- * ```
- */
+import { compilePredicate } from './query-spec.js';
 export class EntityDao extends BaseDao {
     table;
+    /** Primary key columns. A single-element array for single-PK tables, multiple for composite. */
     primaryKey;
     collectionName;
-    constructor(db, table, primaryKey, collectionName) {
-        super(db);
+    validation;
+    constructor(adapter, table, primaryKey, collectionName, options = {}) {
+        super(adapter);
         this.table = table;
-        this.primaryKey = primaryKey;
+        this.primaryKey = Array.isArray(primaryKey) ? primaryKey : [primaryKey];
         this.collectionName = collectionName;
+        this.validation = options;
     }
-    /**
-     * Check if the table has soft delete support (inUsed column).
-     */
+    /** Validate input against the configured schema for an operation, when enabled. */
+    validate(op, input) {
+        // `update` is partial, so it only validates against an explicit partial
+        // `updateSchema`; the full insertSchema would reject a partial payload.
+        const schema = op === 'update' ? this.validation.updateSchema : this.validation.insertSchema;
+        if (schema === undefined)
+            return;
+        const enabled = this.validation.validateOn ?? ['create', 'createMany', 'upsert', 'update'];
+        if (!enabled.includes(op))
+            return;
+        schema.parse(input);
+    }
+    /** Check if the table has soft delete support (inUsed column). */
     get hasSoftDelete() {
         return 'inUsed' in this.table;
     }
-    /**
-     * Build a where condition that filters out soft-deleted records.
-     * Returns undefined if the table doesn't support soft delete.
-     */
+    /** Condition filtering out soft-deleted rows, or undefined when unsupported. */
     get activeCondition() {
         if (this.hasSoftDelete) {
             return eq(this.table.inUsed, 1);
         }
         return undefined;
     }
+    /** Build the where-condition matching a primary key value (single or composite). */
+    pkCondition(id) {
+        const values = Array.isArray(id) ? id : [id];
+        if (values.length !== this.primaryKey.length) {
+            throw new Error(`${this.collectionName}: primary key expects ${this.primaryKey.length} value(s), got ${values.length}`);
+        }
+        const parts = this.primaryKey.map((col, i) => eq(col, values[i]));
+        return parts.length === 1 ? parts[0] : and(...parts);
+    }
+    get insertBuilder() {
+        return this.db.insert(this.table);
+    }
     /**
-     * Create a new record.
-     *
-     * `createdAt` and `updatedAt` are auto-filled if not provided.
-     *
-     * @param data - The data to insert (createdAt/updatedAt optional).
-     * @returns The created record.
+     * Create a new record. `createdAt`/`updatedAt` are auto-filled if absent.
+     * Returns the row as written by the database (RETURNING).
      */
     async create(data) {
         const now = this.now();
-        const record = {
-            ...data,
-            createdAt: data.createdAt ?? now,
-            updatedAt: data.updatedAt ?? now,
-        };
-        await this.db.insert(this.table).values(record);
-        return record;
+        const record = { createdAt: now, updatedAt: now, ...data };
+        this.validate('create', record);
+        const rows = (await this.insertBuilder.values(record).returning());
+        return rows[0];
     }
     /**
-     * Find a record by its primary key.
-     *
-     * @param id - The primary key value.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns The record if found, otherwise undefined.
+     * Insert many records in a single multi-VALUES statement (efficient for ETL).
+     * Returns the written rows (RETURNING).
      */
+    async createMany(data) {
+        if (data.length === 0)
+            return [];
+        const now = this.now();
+        const records = data.map((d) => ({ createdAt: now, updatedAt: now, ...d }));
+        for (const record of records)
+            this.validate('createMany', record);
+        return (await this.insertBuilder.values(records).returning());
+    }
+    /**
+     * Insert or update on conflict. `conflictColumns` identify the unique target;
+     * `update` (or all non-conflict columns) are written on conflict. Returns the row.
+     */
+    async upsert(data, conflictColumns, updateColumns) {
+        const now = this.now();
+        const record = { createdAt: now, updatedAt: now, ...data };
+        this.validate('upsert', record);
+        // Default conflict-update = the supplied data minus identity columns
+        // (conflict target + primary key), so a conflict updates the row in place
+        // without rewriting the key it matched on. Identity columns are matched by
+        // their table property key (not DB column name) to handle snake_case columns.
+        const identityCols = new Set([...conflictColumns, ...this.primaryKey]);
+        const identityProps = new Set(Object.entries(this.table)
+            .filter(([, col]) => identityCols.has(col))
+            .map(([key]) => key));
+        const defaultSet = Object.fromEntries(Object.entries(data).filter(([key]) => !identityProps.has(key)));
+        const setOnConflict = { ...(updateColumns ?? defaultSet), updatedAt: now };
+        const rows = (await this.insertBuilder.values(record)
+            .onConflictDoUpdate({ target: conflictColumns, set: setOnConflict })
+            .returning());
+        return rows[0];
+    }
+    /** Find a record by its primary key (single value or composite tuple). */
     async findById(id, includeDeleted = false) {
-        const conditions = [eq(this.primaryKey, id)];
-        if (!includeDeleted && this.activeCondition) {
+        const conditions = [this.pkCondition(id)];
+        if (!includeDeleted && this.activeCondition)
             conditions.push(this.activeCondition);
-        }
-        const result = await this.db
+        const result = (await this.db
             .select()
             .from(this.table)
-            .where(and(...conditions));
+            .where(and(...conditions)));
         return result[0];
     }
-    /**
-     * Find all records.
-     *
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns Array of records.
-     */
+    /** Find all records (optionally including soft-deleted). */
     async findAll(includeDeleted = false) {
-        const query = this.db.select().from(this.table);
-        if (!includeDeleted && this.activeCondition) {
-            return query.where(this.activeCondition);
-        }
-        return query;
+        return this.list({ includeDeleted });
     }
-    /**
-     * Update a record by its primary key.
-     *
-     * @param id - The primary key value.
-     * @param data - The data to update.
-     * @returns The updated record if found, otherwise undefined.
-     */
+    /** Find the first record matching a column value. */
+    async findBy(column, value, includeDeleted = false) {
+        const rows = await this.list({ where: { col: column, op: 'eq', value }, limit: 1, includeDeleted });
+        return rows[0];
+    }
+    /** Find all records matching a column value. */
+    async findAllBy(column, value, includeDeleted = false) {
+        return this.list({ where: { col: column, op: 'eq', value }, includeDeleted });
+    }
+    /** Update a record by primary key. `updatedAt` is refreshed. Returns the updated row. */
     async update(id, data) {
-        const now = this.now();
-        const updateData = {
-            ...data,
-            updatedAt: now,
-        };
-        await this.db.update(this.table).set(updateData).where(eq(this.primaryKey, id));
-        return this.findById(id);
+        const updateData = { ...data, updatedAt: this.now() };
+        this.validate('update', updateData);
+        const rows = (await this.db
+            .update(this.table)
+            .set(updateData)
+            .where(this.pkCondition(id))
+            .returning());
+        return rows[0];
     }
-    /**
-     * Delete a record by its primary key.
-     *
-     * @param id - The primary key value.
-     * @param soft - Whether to perform a soft delete (default: true if table supports it).
-     * @returns The deleted record (for soft delete), otherwise undefined.
-     */
+    /** Delete a record by primary key. Soft-deletes when the table supports it (default). */
     async delete(id, soft) {
         const useSoftDelete = soft ?? this.hasSoftDelete;
         if (useSoftDelete && this.hasSoftDelete) {
-            const now = this.now();
-            await this.db
-                .update(this.table)
-                .set({ inUsed: 0, updatedAt: now })
-                .where(eq(this.primaryKey, id));
-            return this.findById(id, true);
+            return this.update(id, { inUsed: 0 });
         }
-        await this.db.delete(this.table).where(eq(this.primaryKey, id));
+        await this.db.delete(this.table).where(this.pkCondition(id));
         return undefined;
     }
-    /**
-     * Find a record by a specific column value.
-     *
-     * @param column - The column to search.
-     * @param value - The value to match.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns The record if found, otherwise undefined.
-     */
-    async findBy(column, value, includeDeleted = false) {
-        const conditions = [eq(column, value)];
-        if (!includeDeleted && this.activeCondition) {
-            conditions.push(this.activeCondition);
-        }
-        const result = await this.db
-            .select()
-            .from(this.table)
-            .where(and(...conditions));
-        return result[0];
+    /** List records with predicate filter, ordering, and offset pagination. */
+    async list(spec = {}) {
+        const where = this.withActive(spec.where, spec.includeDeleted);
+        return this.query(this.table, {
+            ...(where ? { where } : {}),
+            ...(spec.orderBy ? { orderBy: spec.orderBy } : {}),
+            ...(spec.limit !== undefined ? { limit: spec.limit } : {}),
+            ...(spec.offset !== undefined ? { offset: spec.offset } : {}),
+        });
     }
-    /**
-     * Find all records matching a specific column value.
-     *
-     * @param column - The column to search.
-     * @param value - The value to match.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns Array of matching records.
-     */
-    async findAllBy(column, value, includeDeleted = false) {
-        const conditions = [eq(column, value)];
-        if (!includeDeleted && this.activeCondition) {
-            conditions.push(this.activeCondition);
+    /** List one keyset page; returns the rows and the cursor for the next page. */
+    async listByCursor(spec) {
+        const dir = spec.direction ?? 'asc';
+        const filters = [];
+        if (spec.where)
+            filters.push(spec.where);
+        if (spec.cursor !== undefined) {
+            filters.push({ col: spec.cursorColumn, op: dir === 'asc' ? 'gt' : 'lt', value: spec.cursor });
         }
-        return this.db
-            .select()
-            .from(this.table)
-            .where(and(...conditions));
+        const where = this.withActive(filters.length > 0 ? { and: filters } : undefined, spec.includeDeleted);
+        const rows = await this.query(this.table, {
+            ...(where ? { where } : {}),
+            orderBy: [{ col: spec.cursorColumn, dir }],
+            limit: spec.limit,
+        });
+        const last = rows[rows.length - 1];
+        const nextCursor = rows.length === spec.limit && last
+            ? last[spec.cursorColumn.name]
+            : undefined;
+        return nextCursor !== undefined ? { rows, nextCursor } : { rows };
     }
-    /**
-     * List records with pagination and optional filtering.
-     *
-     * @param options - List options (limit, offset, where).
-     * @returns Array of records.
-     */
-    async list(options = {}) {
-        const { limit = 100, offset = 0, where, includeDeleted = false } = options;
-        const conditions = [];
-        if (!includeDeleted && this.activeCondition) {
-            conditions.push(this.activeCondition);
-        }
-        if (where) {
-            conditions.push(where);
-        }
-        const query = this.db.select().from(this.table);
-        if (conditions.length > 0) {
-            return query
-                .where(and(...conditions))
-                .limit(limit)
-                .offset(offset);
-        }
-        return query.limit(limit).offset(offset);
-    }
-    /**
-     * Count records in the table.
-     *
-     * @param where - Optional filter condition.
-     * @param includeDeleted - Whether to include soft-deleted records.
-     * @returns The count of matching records.
-     */
+    /** Count records matching an optional predicate. */
     async count(where, includeDeleted = false) {
-        const conditions = [];
-        if (!includeDeleted && this.activeCondition) {
-            conditions.push(this.activeCondition);
-        }
-        if (where) {
-            conditions.push(where);
-        }
-        const query = this.db.select({ value: countFn() }).from(this.table);
-        const result = conditions.length > 0 ? await query.where(and(...conditions)) : await query;
+        const condition = this.withActive(where, includeDeleted);
+        const compiled = condition ? compilePredicate(condition) : undefined;
+        const base = this.db
+            .select({ value: countFn() })
+            .from(this.table);
+        const result = (await (compiled ? base.where(compiled) : base));
         return result[0]?.value ?? 0;
     }
+    /** Combine a caller predicate with the soft-delete active filter. */
+    withActive(where, includeDeleted) {
+        if (includeDeleted || !this.hasSoftDelete)
+            return where;
+        const active = { col: this.table.inUsed, op: 'eq', value: 1 };
+        if (!where)
+            return active;
+        return { and: [where, active] };
+    }
 }

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type DbClient, type DbTable } from './adapter';
+export { createDbAdapter, type DbAdapter, type DbAdapterConfig, type InternalDb } from './adapter';
 export { BunSqliteAdapter, type BunSqliteOptions } from './adapters/bun-sqlite';
 export { D1Adapter } from './adapters/d1';
-export { BaseDao } from './base-dao';
+export { BaseDao, type TxHandle } from './base-dao';
+export { type DefinedTable, defineTable } from './define-table';
 export { type EmbeddedMigration, embeddedMigrations } from './embedded-migrations';
-export { EntityDao, type EntityTable, type PKColumn, type SoftDeletableTable } from './entity-dao';
+export { type CursorListSpec, type DaoValidator, EntityDao, type EntityDaoOptions, type EntityListSpec, type EntityTable, type PKColumn, type PKValue, type SoftDeletableTable, } from './entity-dao';
 export { applyMigrations, type MigrationOptions } from './migrate';
+export { type ColRef, type ComparisonOp, compileOrderBy, compilePredicate, type ListSpec, type OrderTerm, type Predicate, } from './query-spec';
 export { QueueJobDao, type QueueJobRecord, type QueueStats } from './queue-job-dao';
 export { appendOnlyColumns, buildAppendOnlyColumns, buildStandardColumns, buildStandardColumnsWithSoftDelete, nowTimestamp, standardColumns, standardColumnsWithSoftDelete, } from './schema/common';
 export { queueJobs } from './schema/queue-jobs';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/G,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,KAAK,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,EACH,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,kCAAkC,EAClC,YAAY,EACZ,eAAe,EACf,6BAA6B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,KAAK,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,KAAK,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EACH,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,cAAc,EACd,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,SAAS,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,EACH,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,kCAAkC,EAClC,YAAY,EACZ,eAAe,EACf,6BAA6B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}