@gobing-ai/ts-db 0.1.7 → 0.2.1

package/dist/index.js

@@ -2,9 +2,11 @@ export { createDbAdapter } from './adapter.js';
 export { BunSqliteAdapter } from './adapters/bun-sqlite.js';
 export { D1Adapter } from './adapters/d1.js';
 export { BaseDao } from './base-dao.js';
+export { defineTable } from './define-table.js';
 export { embeddedMigrations } from './embedded-migrations.js';
-export { EntityDao } from './entity-dao.js';
+export { EntityDao, } from './entity-dao.js';
 export { applyMigrations } from './migrate.js';
+export { compileOrderBy, compilePredicate, } from './query-spec.js';
 export { QueueJobDao } from './queue-job-dao.js';
 export { appendOnlyColumns, buildAppendOnlyColumns, buildStandardColumns, buildStandardColumnsWithSoftDelete, nowTimestamp, standardColumns, standardColumnsWithSoftDelete, } from './schema/common.js';
 export { queueJobs } from './schema/queue-jobs.js';

package/dist/query-spec.d.ts

@@ -0,0 +1,57 @@
+import { type SQL } from 'drizzle-orm';
+import type { SQLiteColumn } from 'drizzle-orm/sqlite-core';
+/**
+ * A column reference for the ts-db predicate spec.
+ *
+ * Consumers obtain these from their own ts-db table definitions (e.g. `users.email`),
+ * never by importing from `drizzle-orm` — keeping the drizzle dependency internal.
+ */
+export type ColRef = SQLiteColumn;
+/** Binary comparison operators supported by the predicate spec. */
+export type ComparisonOp = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'like';
+/**
+ * Drizzle-free predicate vocabulary for `where`/`count` filters.
+ *
+ * Deliberately small (the "lean facade"): enough for the common 90% of filters.
+ * Anything beyond (joins, aggregates, window functions) belongs in a named DAO
+ * method that uses drizzle privately, never in this public spec.
+ */
+export type Predicate = {
+    col: ColRef;
+    op: ComparisonOp;
+    value: unknown;
+} | {
+    col: ColRef;
+    op: 'in';
+    values: readonly unknown[];
+} | {
+    col: ColRef;
+    op: 'isNull' | 'isNotNull';
+} | {
+    and: readonly Predicate[];
+} | {
+    or: readonly Predicate[];
+};
+/** A single ordering term: a column and an optional direction (default `asc`). */
+export interface OrderTerm {
+    col: ColRef;
+    dir?: 'asc' | 'desc';
+}
+/** Options accepted by the structured `list` operation. */
+export interface ListSpec {
+    where?: Predicate;
+    orderBy?: readonly OrderTerm[];
+    limit?: number;
+    offset?: number;
+    includeDeleted?: boolean;
+}
+/**
+ * Compile a ts-db {@link Predicate} into a drizzle `SQL` condition.
+ *
+ * Internal to ts-db — consumers never see drizzle's `SQL` type. Returns
+ * `undefined` for an empty `and`/`or` group so callers can omit the filter.
+ */
+export declare function compilePredicate(predicate: Predicate): SQL | undefined;
+/** Compile a list of {@link OrderTerm}s into drizzle order-by `SQL` clauses. */
+export declare function compileOrderBy(orderBy: readonly OrderTerm[]): SQL[];
+//# sourceMappingURL=query-spec.d.ts.map

package/dist/query-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-spec.d.ts","sourceRoot":"","sources":["../src/query-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkF,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AACvH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,YAAY,CAAC;AAElC,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GACf;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GACrD;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,QAAQ,GAAG,WAAW,CAAA;CAAE,GAC3C;IAAE,GAAG,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,CAAC;AAEnC,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CACxB;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACrB,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;AAYD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,GAAG,GAAG,SAAS,CAmBtE;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,GAAG,EAAE,CAEnE"}

package/dist/query-spec.js

@@ -0,0 +1,40 @@
+import { and, asc, desc, eq, gt, gte, inArray, isNotNull, isNull, like, lt, lte, ne, or } from 'drizzle-orm';
+const COMPARISON_BUILDERS = {
+    eq: (col, value) => eq(col, value),
+    ne: (col, value) => ne(col, value),
+    gt: (col, value) => gt(col, value),
+    gte: (col, value) => gte(col, value),
+    lt: (col, value) => lt(col, value),
+    lte: (col, value) => lte(col, value),
+    like: (col, value) => like(col, value),
+};
+/**
+ * Compile a ts-db {@link Predicate} into a drizzle `SQL` condition.
+ *
+ * Internal to ts-db — consumers never see drizzle's `SQL` type. Returns
+ * `undefined` for an empty `and`/`or` group so callers can omit the filter.
+ */
+export function compilePredicate(predicate) {
+    if ('and' in predicate) {
+        const parts = predicate.and.map(compilePredicate).filter((p) => p !== undefined);
+        return parts.length > 0 ? and(...parts) : undefined;
+    }
+    if ('or' in predicate) {
+        const parts = predicate.or.map(compilePredicate).filter((p) => p !== undefined);
+        return parts.length > 0 ? or(...parts) : undefined;
+    }
+    switch (predicate.op) {
+        case 'isNull':
+            return isNull(predicate.col);
+        case 'isNotNull':
+            return isNotNull(predicate.col);
+        case 'in':
+            return inArray(predicate.col, predicate.values);
+        default:
+            return COMPARISON_BUILDERS[predicate.op](predicate.col, predicate.value);
+    }
+}
+/** Compile a list of {@link OrderTerm}s into drizzle order-by `SQL` clauses. */
+export function compileOrderBy(orderBy) {
+    return orderBy.map((term) => (term.dir === 'desc' ? desc(term.col) : asc(term.col)));
+}

package/dist/queue-job-dao.d.ts

@@ -1,4 +1,4 @@
-import type { DbClient } from './adapter';
+import type { DbAdapter } from './adapter';
 import { EntityDao } from './entity-dao';
 import { queueJobs } from './schema/queue-jobs';
 /**
@@ -21,7 +21,7 @@ export type QueueJobRecord = typeof queueJobs.$inferSelect;
  * methods for job lifecycle management (enqueue, process, retry, fail).
  */
 export declare class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id> {
-    constructor(db: DbClient);
+    constructor(adapter: DbAdapter);
     /**
      * Enqueue a new job.
      */

package/dist/queue-job-dao.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue-job-dao.d.ts","sourceRoot":"","sources":["../src/queue-job-dao.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,SAAS,CAAC,OAAO,SAAS,EAAE,OAAO,SAAS,CAAC,EAAE,CAAC;gBACjE,EAAE,EAAE,QAAQ;IAIxB;;OAEG;IACG,OAAO,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAClE,OAAO,CAAC,MAAM,CAAC;IAkBlB;;OAEG;IACG,YAAY,CACd,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAC1G,OAAO,CAAC,MAAM,EAAE,CAAC;IA+BpB;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAI9D;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAwBrC;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAapD;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAyB/D;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmC9D;;OAEG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAelD;;OAEG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1G;;OAEG;IACG,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBhE;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;CAwB3C"}
+{"version":3,"file":"queue-job-dao.d.ts","sourceRoot":"","sources":["../src/queue-job-dao.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,SAAS,CAAC,OAAO,SAAS,EAAE,OAAO,SAAS,CAAC,EAAE,CAAC;gBACjE,OAAO,EAAE,SAAS;IAI9B;;OAEG;IACG,OAAO,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAClE,OAAO,CAAC,MAAM,CAAC;IAkBlB;;OAEG;IACG,YAAY,CACd,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAC1G,OAAO,CAAC,MAAM,EAAE,CAAC;IA+BpB;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAI9D;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAwBrC;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAapD;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAyB/D;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmC9D;;OAEG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAelD;;OAEG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1G;;OAEG;IACG,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBhE;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;CAwB3C"}

package/dist/queue-job-dao.js

@@ -8,8 +8,8 @@ import { queueJobs } from './schema/queue-jobs.js';
  * methods for job lifecycle management (enqueue, process, retry, fail).
  */
 export class QueueJobDao extends EntityDao {
-    constructor(db) {
-        super(db, queueJobs, queueJobs.id, 'queue_jobs');
+    constructor(adapter) {
+        super(adapter, queueJobs, [queueJobs.id], 'queue_jobs');
     }
     /**
      * Enqueue a new job.
@@ -50,7 +50,7 @@ export class QueueJobDao extends EntityDao {
             };
         });
         if (rows.length > 0) {
-            await this.withTransaction(async (tx) => {
+            await this.tx(async (tx) => {
                 for (const row of rows) {
                     await tx.insert(queueJobs).values(row);
                 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@gobing-ai/ts-db",
-    "version": "0.1.7",
-    "description": "@gobing-ai/ts-db — Database abstraction layer with Drizzle ORM adapters, generic DAOs, and migration tooling.",
+    "version": "0.2.1",
+    "description": "@gobing-ai/ts-db — a drizzle-free database facade: typed DAOs over Bun SQLite / Cloudflare D1, a small predicate query spec, single-source-of-truth tables, and migrations. Drizzle stays an internal detail.",
     "keywords": [
         "typescript",
         "database",
@@ -50,15 +50,27 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-db-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-runtime": "^0.1.0"
+        "@gobing-ai/ts-runtime": "^0.2.1"
     },
     "peerDependencies": {
-        "drizzle-orm": ">=0.38.0"
+        "drizzle-orm": ">=0.38.0",
+        "drizzle-zod": ">=0.5.0",
+        "zod": ">=3.23.0"
+    },
+    "peerDependenciesMeta": {
+        "drizzle-zod": {
+            "optional": true
+        },
+        "zod": {
+            "optional": true
+        }
     },
     "devDependencies": {
         "@types/bun": "1.3.14",
         "drizzle-kit": "^0.30.0",
-        "drizzle-orm": "^0.38.0"
+        "drizzle-orm": "^0.38.0",
+        "drizzle-zod": "^0.5.1",
+        "zod": "^4.1.0"
     },
     "publishConfig": {
         "access": "public"

package/src/adapter.ts

@@ -1,3 +1,6 @@
+import type { BunSQLiteDatabase } from 'drizzle-orm/bun-sqlite';
+import type { DrizzleD1Database } from 'drizzle-orm/d1';
+
 /**
  * Minimal D1 binding interface — avoids depending on @cloudflare/workers-types.
  */
@@ -7,70 +10,40 @@ interface D1Binding {
 }
 
 /**
- * Generic database table descriptor carrying select and insert type info.
- */
-export interface DbTable<TSelect, TInsert = TSelect> {
-    readonly $inferSelect: TSelect;
-    readonly $inferInsert: TInsert;
-}
-
-type DbInsertBuilder<TTable extends DbTable<unknown, unknown>> = {
-    values(values: TTable['$inferInsert'] | TTable['$inferInsert'][]): PromiseLike<unknown>;
-};
-
-interface DbSelectWhereResult<TTable extends DbTable<unknown, unknown>> extends PromiseLike<TTable['$inferSelect'][]> {
-    limit(value: number): DbSelectWhereResult<TTable>;
-    offset(value: number): DbSelectWhereResult<TTable>;
-    orderBy(column: unknown): DbSelectWhereResult<TTable>;
-}
-
-type DbSelectFromResult<TTable extends DbTable<unknown, unknown>> = DbSelectWhereResult<TTable> & {
-    where(condition: unknown): DbSelectWhereResult<TTable>;
-};
-
-type DbSelectBuilder = {
-    from<TTable extends DbTable<unknown, unknown>>(table: TTable): DbSelectFromResult<TTable>;
-};
-
-type DbProjectionSelectBuilder<TProjection> = {
-    from(table: DbTable<unknown, unknown>): PromiseLike<TProjection[]> & {
-        where(condition: unknown): PromiseLike<TProjection[]>;
-    };
-};
-
-interface DbUpdateResult {
-    changes: number;
-}
-
-interface DbUpdateBuilder<TTable extends DbTable<unknown, unknown>> {
-    set(values: Partial<TTable['$inferInsert']>): { where(condition: unknown): PromiseLike<DbUpdateResult> };
-}
-
-/**
- * Abstract database client with insert/select/update/delete query builders.
+ * Internal typed drizzle database handle.
+ *
+ * This is the REAL drizzle database (bun:sqlite or D1 flavour), fully typed.
+ * It is `@internal` — ts-db's DAO base classes use it to build queries, but it
+ * is never part of the public API. Consumers depend only on the ts-db facade
+ * (DAOs, the predicate spec), never on drizzle types directly. (G1)
+ *
+ * @internal
  */
-export interface DbClient {
-    insert<TTable extends DbTable<unknown, unknown>>(table: TTable): DbInsertBuilder<TTable>;
-    select(): DbSelectBuilder;
-    select<TProjection>(projection: Record<string, unknown>): DbProjectionSelectBuilder<TProjection>;
-    update<TTable extends DbTable<unknown, unknown>>(table: TTable): DbUpdateBuilder<TTable>;
-    delete<TTable extends DbTable<unknown, unknown>>(
-        table: TTable,
-    ): {
-        where(condition: unknown): PromiseLike<DbUpdateResult>;
-    };
-}
+export type InternalDb = BunSQLiteDatabase<Record<string, unknown>> | DrizzleD1Database<Record<string, unknown>>;
 
 /**
- * Database adapter providing a unified client, raw SQL exec, and lifecycle management.
+ * Database adapter: construction, lifecycle, the internal typed drizzle db, and a
+ * raw string-SQL escape for DDL / dynamic identifiers.
+ *
+ * The internal drizzle db (`db`) is exposed only to ts-db's own DAO layer; the
+ * string-SQL methods are the sole raw escape, intended for DDL and dynamic
+ * identifiers and gated to DAO files by a consumer-side lint rule.
  */
 export interface DbAdapter {
-    getDb(): DbClient;
+    /**
+     * The internal typed drizzle database. ts-db DAO layer only — not public API.
+     * @internal
+     */
+    readonly db: InternalDb;
+    /** Run a raw SQL statement with no parameters (DDL). */
     exec(sql: string): Promise<void>;
     /** Parameterized write (INSERT/UPDATE/DELETE) that returns no rows. */
     run(sql: string, ...params: unknown[]): Promise<void>;
+    /** Parameterized read returning the first row, or undefined. */
     queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+    /** Parameterized read returning all rows. */
     queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    /** Close the underlying connection. */
     close(): void;
 }
 

package/src/adapters/bun-sqlite.ts

@@ -1,7 +1,7 @@
 import { Database } from 'bun:sqlite';
 import { isAbsolute, resolve } from 'node:path';
 import { type BunSQLiteDatabase, drizzle } from 'drizzle-orm/bun-sqlite';
-import type { DbAdapter, DbClient } from '../adapter';
+import type { DbAdapter, InternalDb } from '../adapter';
 import * as schema from '../schema/index';
 
 type SqliteStatementLike = {
@@ -74,8 +74,9 @@ export class BunSqliteAdapter implements DbAdapter {
         this.drizzleDb = drizzle({ client: this.sqlite, schema });
     }
 
-    getDb(): DbClient {
-        return this.drizzleDb as unknown as DbClient;
+    /** The internal typed drizzle database (ts-db DAO layer + migrations only). */
+    get db(): InternalDb {
+        return this.drizzleDb as unknown as InternalDb;
     }
 
     /** Returns the underlying drizzle instance for migration operations. */

package/src/adapters/d1.ts

@@ -1,5 +1,5 @@
 import { type DrizzleD1Database, drizzle } from 'drizzle-orm/d1';
-import type { DbAdapter, DbClient } from '../adapter';
+import type { DbAdapter, InternalDb } from '../adapter';
 import * as schema from '../schema/index';
 
 /**
@@ -36,8 +36,14 @@ export class D1Adapter implements DbAdapter {
         this.drizzleDb = drizzle(this.binding, { schema });
     }
 
-    getDb(): DbClient {
-        return this.drizzleDb as unknown as DbClient;
+    /** The internal typed drizzle database (ts-db DAO layer only). */
+    get db(): InternalDb {
+        return this.drizzleDb as unknown as InternalDb;
+    }
+
+    /** Returns the underlying drizzle instance for migration operations. */
+    getDrizzleDb(): DrizzleD1Database<typeof schema> {
+        return this.drizzleDb;
     }
 
     /** Returns the non-mutating binding for advanced direct D1 calls. */

package/src/base-dao.ts

@@ -1,18 +1,36 @@
-import type { DbClient } from './adapter';
+import type { SQLiteTable } from 'drizzle-orm/sqlite-core';
+import type { DbAdapter, InternalDb } from './adapter';
+import { compileOrderBy, compilePredicate, type ListSpec, type Predicate } from './query-spec';
 
 /**
- * Abstract base DAO providing transaction and timestamp utilities to all entity DAOs.
+ * A transaction-scoped handle passed to {@link BaseDao.tx} callbacks.
+ *
+ * Drizzle-free by design — exposes the same internal db shape DAOs use, so a
+ * transactional block can run the same structured/raw operations. (G3)
+ *
+ * @internal
+ */
+export type TxHandle = InternalDb;
+
+/**
+ * Abstract base DAO — the RAW tier of the ts-db facade.
+ *
+ * Owns the adapter and provides generic, table-agnostic data access:
+ * transactions and parameterized queries expressed through the ts-db predicate
+ * spec (never drizzle's `sql` tag). ETL / analytics / reporting DAOs extend this
+ * directly; {@link EntityDao} extends it to add typed CRUD over a single table.
+ *
+ * All signatures are ts-db's own vocabulary — drizzle never leaks to consumers. (G1)
  */
 export abstract class BaseDao {
-    /**
-     * DB transaction utility for subclasses.
-     *
-     * Constructor is `protected` — instantiate through concrete DAO subclasses,
-     * not BaseDao directly. Tests must declare an explicit public constructor
-     * that calls `super(db)` to expose the protected constructor publicly.
-     */
-    protected constructor(protected readonly db: DbClient) {}
+    protected constructor(protected readonly adapter: DbAdapter) {}
+
+    /** The internal typed drizzle db. Subclasses use it to build queries. @internal */
+    protected get db(): InternalDb {
+        return this.adapter.db;
+    }
 
+    /** Current timestamp in milliseconds (audit columns, etc.). */
     protected now(): number {
         return Date.now();
     }
@@ -20,18 +38,42 @@ export abstract class BaseDao {
     /**
      * Execute a function within a database transaction.
      *
-     * Works uniformly on both D1 (async) and bun:sqlite (sync wrapped in promise).
-     * The callback receives a transaction-scoped DbClient.
-     *
-     * @param fn - Function to execute within the transaction.
-     * @returns The return value of `fn`.
+     * Works uniformly on bun:sqlite (sync, wrapped in a promise) and D1 (async).
+     * The callback receives a transaction-scoped db handle.
      */
-    protected async withTransaction<T>(fn: (tx: DbClient) => Promise<T>): Promise<T> {
-        // Drizzle's .transaction() works on both backends:
-        // - bun:sqlite: sync wrapped in a promise
-        // - D1: native async
-        return (this.db as unknown as { transaction: (fn: unknown) => Promise<T> }).transaction(async (tx: DbClient) =>
+    protected async tx<T>(fn: (tx: TxHandle) => Promise<T>): Promise<T> {
+        return (this.db as { transaction: (cb: (tx: TxHandle) => Promise<T>) => Promise<T> }).transaction((tx) =>
             fn(tx),
         );
     }
+
+    /**
+     * Run a SELECT against a table, filtered/ordered/paged by a {@link ListSpec}.
+     *
+     * The raw-tier read primitive: drizzle-free input, typed rows out. Subclasses
+     * pass their table; `EntityDao` builds on this for `list`.
+     */
+    protected async query<T>(table: SQLiteTable, spec: ListSpec = {}): Promise<T[]> {
+        const condition = spec.where ? compilePredicate(spec.where) : undefined;
+        const order = spec.orderBy ? compileOrderBy(spec.orderBy) : [];
+
+        // drizzle's fluent builder is internal here; the public input is the spec.
+        let q = (this.db as InternalDb).select().from(table) as unknown as {
+            where: (c: unknown) => typeof q;
+            orderBy: (...o: unknown[]) => typeof q;
+            limit: (n: number) => typeof q;
+            offset: (n: number) => typeof q;
+        };
+        if (condition) q = q.where(condition);
+        if (order.length > 0) q = q.orderBy(...order);
+        if (spec.limit !== undefined) q = q.limit(spec.limit);
+        if (spec.offset !== undefined) q = q.offset(spec.offset);
+        return (await (q as unknown as Promise<T[]>)) ?? [];
+    }
+
+    /** Run a SELECT and return the first matching row, or undefined. */
+    protected async one<T>(table: SQLiteTable, where: Predicate): Promise<T | undefined> {
+        const rows = await this.query<T>(table, { where, limit: 1 });
+        return rows[0];
+    }
 }

package/src/define-table.ts

@@ -0,0 +1,66 @@
+import { type SQLiteColumnBuilderBase, sqliteTable } from 'drizzle-orm/sqlite-core';
+import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
+import type { ZodType } from 'zod';
+
+/**
+ * A table definition bundled with its drizzle-zod validation schemas.
+ *
+ * The single source of truth (G2): one table authored once yields the drizzle
+ * table (for queries/migrations) plus insert/select zod schemas (for boundary
+ * validation), with no parallel re-authoring.
+ *
+ * The zod schemas are derived lazily — only materialised the first time they are
+ * read — so a consumer that only needs the table pays nothing extra.
+ *
+ * `defineTable`, `insertSchema`, and `selectSchema` require the optional peers
+ * `zod` and `drizzle-zod`. Consumers that never validate need not install them
+ * and simply use `createDbAdapter` + raw `sqliteTable` + the column helpers.
+ */
+export interface DefinedTable<TTable> {
+    /** The underlying drizzle table — pass to DAOs, migrations, queries. */
+    readonly table: TTable;
+    /** Zod schema validating a row for insertion. */
+    readonly insertSchema: ZodType;
+    /** Zod schema validating a selected row. */
+    readonly selectSchema: ZodType;
+}
+
+/**
+ * Define a SQLite table and derive its validation schemas in one place (G2).
+ *
+ * @example
+ * ```ts
+ * export const users = defineTable('users', {
+ *     id: text('id').primaryKey(),
+ *     email: text('email').notNull().unique(),
+ *     ...standardColumns,
+ * });
+ * users.table          // drizzle table for DAOs/migrations
+ * users.insertSchema   // zod schema derived from the table
+ * ```
+ */
+export function defineTable<TName extends string, TColumns extends Record<string, SQLiteColumnBuilderBase>>(
+    name: TName,
+    columns: TColumns,
+): DefinedTable<ReturnType<typeof sqliteTable<TName, TColumns>>> {
+    const table = sqliteTable(name, columns);
+
+    let insert: ZodType | undefined;
+    let select: ZodType | undefined;
+
+    return {
+        table,
+        get insertSchema(): ZodType {
+            if (insert === undefined) {
+                insert = createInsertSchema(table) as unknown as ZodType;
+            }
+            return insert;
+        },
+        get selectSchema(): ZodType {
+            if (select === undefined) {
+                select = createSelectSchema(table) as unknown as ZodType;
+            }
+            return select;
+        },
+    };
+}