@fragno-dev/db 0.3.0 → 0.4.1

package/src/adapters/generic-sql/query/select-builder.ts

@@ -1,6 +1,6 @@
-import type { AnyTable } from "../../../schema/create";
-import type { AnySelectClause } from "../../../query/simple-query-interface";
 import type { NamingResolver } from "../../../naming/sql-naming";
+import type { AnySelectClause } from "../../../query/simple-query-interface";
+import type { AnyTable } from "../../../schema/create";
 
 /**
  * Maps a select clause to SQL column names with optional aliases.

package/src/adapters/generic-sql/query/sql-query-compiler.test.ts

@@ -1,16 +1,18 @@
 import { describe, test, expect } from "vitest";
-import { Kysely, SqliteDialect } from "kysely";
+
 import Database from "better-sqlite3";
-import { schema, column, idColumn, referenceColumn } from "../../../schema/create";
+import { Kysely, SqliteDialect } from "kysely";
+
 import { createNamingResolver, type SqlNamingStrategy } from "../../../naming/sql-naming";
-import { PostgreSQLQueryCompiler } from "./dialect/postgres";
-import { MySQLQueryCompiler } from "./dialect/mysql";
-import { SQLiteQueryCompiler } from "./dialect/sqlite";
+import { schema, column, idColumn, referenceColumn } from "../../../schema/create";
 import {
   BetterSQLite3DriverConfig,
   NodePostgresDriverConfig,
   MySQL2DriverConfig,
 } from "../driver-config";
+import { MySQLQueryCompiler } from "./dialect/mysql";
+import { PostgreSQLQueryCompiler } from "./dialect/postgres";
+import { SQLiteQueryCompiler } from "./dialect/sqlite";
 
 // Test schema
 const testSchema = schema("test", (s) => {
@@ -80,6 +82,23 @@ describe("SQLQueryCompiler", () => {
       );
     });
 
+    test("compileFindMany includes id when read tracking is enabled", () => {
+      const db = new Kysely({
+        dialect: new SqliteDialect({ database: new Database(":memory:") }),
+      });
+      const compiler = new PostgreSQLQueryCompiler(db, new NodePostgresDriverConfig());
+
+      const query = compiler.compileFindMany(testSchema.tables.users, {
+        select: ["email"],
+        limit: 10,
+        readTracking: true,
+      });
+
+      expect(query.sql).toMatchInlineSnapshot(
+        `"select "users"."email" as "email", "users"."id" as "id", "users"."_internalId" as "_internalId", "users"."_version" as "_version" from "users" limit ?"`,
+      );
+    });
+
     test("compileFindMany with orderBy", () => {
       const db = new Kysely({
         dialect: new SqliteDialect({ database: new Database(":memory:") }),

package/src/adapters/generic-sql/query/sql-query-compiler.ts

@@ -8,15 +8,16 @@ import type {
 } from "kysely";
 import { sql } from "kysely";
 import type { SqlBool } from "kysely";
-import type { AnyColumn, AnyTable } from "../../../schema/create";
+
+import type { NamingResolver } from "../../../naming/sql-naming";
 import type { Condition } from "../../../query/condition-builder";
+import type { CompiledJoin } from "../../../query/orm/orm";
+import type { AnyColumn, AnyTable } from "../../../schema/create";
 import type { DriverConfig, SupportedDatabase } from "../driver-config";
 import type { SQLiteStorageMode } from "../sqlite-storage";
-import type { NamingResolver } from "../../../naming/sql-naming";
-import { buildWhere, fullSQLName } from "./where-builder";
-import { mapSelect, extendSelect } from "./select-builder";
-import type { CompiledJoin } from "../../../query/orm/orm";
 import { UnitOfWorkEncoder } from "../uow-encoder";
+import { mapSelect, extendSelect } from "./select-builder";
+import { buildWhere, fullSQLName } from "./where-builder";
 
 /**
  * Type helpers for Kysely query builders.
@@ -45,12 +46,13 @@ export type AnyInsertQueryBuilder<O = any> = InsertQueryBuilder<any, any, O>;
  * Options for compiling a find operation
  */
 export interface FindManyCompilerOptions {
-  select: true | string[];
+  select: true | readonly string[];
   where?: Condition;
   orderBy?: [AnyColumn, "asc" | "desc"][];
   limit?: number;
   offset?: number;
   join?: CompiledJoin[];
+  readTracking?: boolean;
 }
 
 /**
@@ -85,6 +87,11 @@ export interface DeleteCompilerOptions {
   returning?: boolean;
 }
 
+export type JoinAliasInfo = {
+  table: AnyTable;
+  alias: string;
+};
+
 /**
  * Abstract base class for SQL query compilation.
  *
@@ -147,7 +154,12 @@ export abstract class SQLQueryCompiler {
   /**
    * Build WHERE clause from a condition tree.
    */
-  protected buildWhereClause(condition: Condition, eb: AnyExpressionBuilder, table: AnyTable) {
+  protected buildWhereClause(
+    condition: Condition,
+    eb: AnyExpressionBuilder,
+    table: AnyTable,
+    tableAlias?: string,
+  ) {
     return buildWhere(
       condition,
       eb,
@@ -155,6 +167,7 @@ export abstract class SQLQueryCompiler {
       this.sqliteStorageMode,
       this.resolver,
       table,
+      tableAlias,
     );
   }
 
@@ -168,6 +181,8 @@ export abstract class SQLQueryCompiler {
     parentTableName: string,
     mappedSelect: string[],
     parentPath: string = "",
+    aliasCollector?: JoinAliasInfo[],
+    readTracking?: boolean,
   ): AnySelectQueryBuilder<O> {
     let result = query;
 
@@ -183,10 +198,17 @@ export abstract class SQLQueryCompiler {
       const fullPath = parentPath ? `${parentPath}:${relation.name}` : relation.name;
       // SQL table alias uses underscores (e.g., "author_inviter")
       const joinName = fullPath.replace(/:/g, "_");
+      if (aliasCollector) {
+        aliasCollector.push({ table: targetTable, alias: joinName });
+      }
 
-      // Update select
+      const joinSelectBuilder = extendSelect(joinOptions.select);
+      if (readTracking) {
+        joinSelectBuilder.extend(targetTable.getIdColumn().name);
+      }
+      const compiledJoinSelect = joinSelectBuilder.compile();
       mappedSelect.push(
-        ...mapSelect(joinOptions.select, targetTable, this.resolver, {
+        ...mapSelect(compiledJoinSelect.result, targetTable, this.resolver, {
           relation: fullPath, // Use full path with colons for column aliases
           tableName: joinName, // Use underscore version for table name
         }),
@@ -196,6 +218,10 @@ export abstract class SQLQueryCompiler {
         b.on((eb) => {
           const conditions = [];
           for (const [left, right] of relation.on) {
+            const leftCol = parentTable.columns[left];
+            const actualLeft =
+              leftCol?.role === "external-id" ? parentTable.getInternalIdColumn().name : left;
+            const actualLeftCol = parentTable.columns[actualLeft];
             // Foreign keys always use internal IDs
             // If the relation references an external ID column (any name), translate to "_internalId"
             const rightCol = targetTable.columns[right];
@@ -205,8 +231,11 @@ export abstract class SQLQueryCompiler {
               eb(
                 `${parentTableName}.${
                   this.resolver
-                    ? this.resolver.getColumnName(parentTable.name, parentTable.columns[left].name)
-                    : parentTable.columns[left].name
+                    ? this.resolver.getColumnName(
+                        parentTable.name,
+                        actualLeftCol ? actualLeftCol.name : parentTable.columns[left].name,
+                      )
+                    : (actualLeftCol ?? parentTable.columns[left]).name
                 }`,
                 "=",
                 eb.ref(
@@ -224,7 +253,7 @@ export abstract class SQLQueryCompiler {
           }
 
           if (joinOptions.where) {
-            conditions.push(this.buildWhereClause(joinOptions.where, eb, targetTable));
+            conditions.push(this.buildWhereClause(joinOptions.where, eb, targetTable, joinName));
           }
 
           return eb.and(conditions);
@@ -240,6 +269,8 @@ export abstract class SQLQueryCompiler {
           joinName,
           mappedSelect,
           fullPath,
+          aliasCollector,
+          readTracking,
         );
       }
     }
@@ -247,6 +278,33 @@ export abstract class SQLQueryCompiler {
     return result;
   }
 
+  /**
+   * Build a select query with joins applied, returning a list of table aliases used.
+   * Intended for conflict checks that need to mirror the join tree from queries.
+   */
+  buildJoinQuery(
+    table: AnyTable,
+    options: { where?: Condition; join?: CompiledJoin[] },
+  ): {
+    query: AnySelectQueryBuilder;
+    aliases: JoinAliasInfo[];
+  } {
+    const tableName = this.getTableName(table);
+    let query = this.db.selectFrom(tableName);
+    const aliases: JoinAliasInfo[] = [{ table, alias: tableName }];
+
+    if (options.where) {
+      query = query.where((eb) => this.buildWhereClause(options.where!, eb, table));
+    }
+
+    if (options.join && options.join.length > 0) {
+      const mappedSelect: string[] = [];
+      query = this.processJoins(query, options.join, table, tableName, mappedSelect, "", aliases);
+    }
+
+    return { query, aliases };
+  }
+
   /**
    * Compile a COUNT query.
    */
@@ -293,11 +351,23 @@ export abstract class SQLQueryCompiler {
 
     // Build SELECT with joins
     const selectBuilder = extendSelect(options.select);
+    if (options.readTracking) {
+      selectBuilder.extend(table.getIdColumn().name);
+    }
     const mappedSelect: string[] = [];
 
     // Process joins if provided
     if (options.join && options.join.length > 0) {
-      query = this.processJoins(query, options.join, table, this.getTableName(table), mappedSelect);
+      query = this.processJoins(
+        query,
+        options.join,
+        table,
+        this.getTableName(table),
+        mappedSelect,
+        "",
+        undefined,
+        options.readTracking,
+      );
     }
 
     const compiledSelect = selectBuilder.compile();

package/src/adapters/generic-sql/query/where-builder.test.ts

@@ -1,11 +1,13 @@
-import { Kysely, PostgresDialect } from "kysely";
 import { beforeAll, describe, expect, it } from "vitest";
-import { column, idColumn, referenceColumn, schema } from "../../../schema/create";
-import { fullSQLName, buildWhere, processReferenceSubqueries } from "./where-builder";
+
+import { Kysely, PostgresDialect } from "kysely";
+
+import { createNamingResolver, type SqlNamingStrategy } from "../../../naming/sql-naming";
+import { dbNow } from "../../../query/db-now";
 import { ReferenceSubquery } from "../../../query/value-encoding";
+import { column, idColumn, referenceColumn, schema } from "../../../schema/create";
 import { BetterSQLite3DriverConfig, NodePostgresDriverConfig } from "../driver-config";
-import { dbNow } from "../../../query/db-now";
-import { createNamingResolver, type SqlNamingStrategy } from "../../../naming/sql-naming";
+import { fullSQLName, buildWhere, processReferenceSubqueries } from "./where-builder";
 
 describe("where-builder", () => {
   const testSchema = schema("test", (s) => {

package/src/adapters/generic-sql/query/where-builder.ts

@@ -1,4 +1,10 @@
 import { sql, type BinaryOperator } from "kysely";
+
+import type { NamingResolver } from "../../../naming/sql-naming";
+import type { Condition } from "../../../query/condition-builder";
+import { getDbNowOffsetMs, isDbNow } from "../../../query/db-now";
+import { createSQLSerializer } from "../../../query/serialize/create-sql-serializer";
+import { ReferenceSubquery, resolveFragnoIdValue } from "../../../query/value-encoding";
 import {
   type AnyColumn,
   type AnyTable,
@@ -6,13 +12,9 @@ import {
   FragnoId,
   FragnoReference,
 } from "../../../schema/create";
-import type { Condition } from "../../../query/condition-builder";
-import { createSQLSerializer } from "../../../query/serialize/create-sql-serializer";
-import type { NamingResolver } from "../../../naming/sql-naming";
 import type { DriverConfig } from "../driver-config";
-import { sqliteStorageDefault, type SQLiteStorageMode } from "../sqlite-storage";
-import { ReferenceSubquery, resolveFragnoIdValue } from "../../../query/value-encoding";
-import { isDbNow } from "../../../query/db-now";
+import type { SQLiteStorageMode } from "../sqlite-storage";
+import { buildDbNowSql } from "./db-now-sql";
 import type { AnyKysely, AnyExpressionBuilder, AnyExpressionWrapper } from "./sql-query-compiler";
 
 /**
@@ -29,6 +31,21 @@ export function fullSQLName(column: AnyColumn, resolver?: NamingResolver): strin
   return `${tableName}.${columnName}`;
 }
 
+function fullSQLNameWithAlias(
+  column: AnyColumn,
+  resolver?: NamingResolver,
+  table?: AnyTable,
+  tableAlias?: string,
+): string {
+  if (table && tableAlias && column.tableName === table.name) {
+    const columnName = resolver
+      ? resolver.getColumnName(column.tableName, column.name)
+      : column.name;
+    return `${tableAlias}.${columnName}`;
+  }
+  return fullSQLName(column, resolver);
+}
+
 /**
  * Builds a WHERE clause expression from a Condition tree.
  *
@@ -51,6 +68,7 @@ export function buildWhere(
   sqliteStorageMode?: SQLiteStorageMode,
   resolver?: NamingResolver,
   table?: AnyTable,
+  tableAlias?: string,
 ): AnyExpressionWrapper {
   const serializer = createSQLSerializer(driverConfig, sqliteStorageMode);
 
@@ -61,18 +79,12 @@ export function buildWhere(
 
     if (!(val instanceof Column)) {
       if (isDbNow(val)) {
-        if (driverConfig.databaseType === "sqlite") {
-          const storageMode = sqliteStorageMode ?? sqliteStorageDefault;
-          const storage =
-            left.type === "date" ? storageMode.dateStorage : storageMode.timestampStorage;
-          if ((left.type === "timestamp" || left.type === "date") && storage === "epoch-ms") {
-            val = sql`(cast((julianday('now') - 2440587.5)*86400000 as integer))`;
-          } else {
-            val = sql`CURRENT_TIMESTAMP`;
-          }
-        } else {
-          val = sql`CURRENT_TIMESTAMP`;
-        }
+        val = buildDbNowSql({
+          driverConfig,
+          columnType: left.type,
+          offsetMs: getDbNowOffsetMs(val),
+          sqliteStorageMode,
+        });
       } else if (left.role === "reference" && table) {
         // Handle reference columns specially
         if (typeof val === "string") {
@@ -155,67 +167,74 @@ export function buildWhere(
         v = "like";
         rhs =
           val instanceof Column
-            ? sql`concat('%', ${eb.ref(fullSQLName(val, resolver))}, '%')`
+            ? sql`concat('%', ${eb.ref(fullSQLNameWithAlias(val, resolver, table, tableAlias))}, '%')`
             : `%${val}%`;
         break;
       case "not contains":
         v = "not like";
         rhs =
           val instanceof Column
-            ? sql`concat('%', ${eb.ref(fullSQLName(val, resolver))}, '%')`
+            ? sql`concat('%', ${eb.ref(fullSQLNameWithAlias(val, resolver, table, tableAlias))}, '%')`
             : `%${val}%`;
         break;
       case "starts with":
         v = "like";
         rhs =
           val instanceof Column
-            ? sql`concat(${eb.ref(fullSQLName(val, resolver))}, '%')`
+            ? sql`concat(${eb.ref(fullSQLNameWithAlias(val, resolver, table, tableAlias))}, '%')`
             : `${val}%`;
         break;
       case "not starts with":
         v = "not like";
         rhs =
           val instanceof Column
-            ? sql`concat(${eb.ref(fullSQLName(val, resolver))}, '%')`
+            ? sql`concat(${eb.ref(fullSQLNameWithAlias(val, resolver, table, tableAlias))}, '%')`
             : `${val}%`;
         break;
       case "ends with":
         v = "like";
         rhs =
           val instanceof Column
-            ? sql`concat('%', ${eb.ref(fullSQLName(val, resolver))})`
+            ? sql`concat('%', ${eb.ref(fullSQLNameWithAlias(val, resolver, table, tableAlias))})`
             : `%${val}`;
         break;
       case "not ends with":
         v = "not like";
         rhs =
           val instanceof Column
-            ? sql`concat('%', ${eb.ref(fullSQLName(val, resolver))})`
+            ? sql`concat('%', ${eb.ref(fullSQLNameWithAlias(val, resolver, table, tableAlias))})`
             : `%${val}`;
         break;
       default:
         v = op;
-        rhs = val instanceof Column ? eb.ref(fullSQLName(val, resolver)) : val;
+        rhs =
+          val instanceof Column
+            ? eb.ref(fullSQLNameWithAlias(val, resolver, table, tableAlias))
+            : val;
     }
 
-    return eb(fullSQLName(left, resolver), v, rhs);
+    return eb(fullSQLNameWithAlias(left, resolver, table, tableAlias), v, rhs);
   }
 
   // Nested conditions
   if (condition.type === "and") {
     return eb.and(
       condition.items.map((v) =>
-        buildWhere(v, eb, driverConfig, sqliteStorageMode, resolver, table),
+        buildWhere(v, eb, driverConfig, sqliteStorageMode, resolver, table, tableAlias),
       ),
     );
   }
 
   if (condition.type === "not") {
-    return eb.not(buildWhere(condition.item, eb, driverConfig, sqliteStorageMode, resolver, table));
+    return eb.not(
+      buildWhere(condition.item, eb, driverConfig, sqliteStorageMode, resolver, table, tableAlias),
+    );
   }
 
   return eb.or(
-    condition.items.map((v) => buildWhere(v, eb, driverConfig, sqliteStorageMode, resolver, table)),
+    condition.items.map((v) =>
+      buildWhere(v, eb, driverConfig, sqliteStorageMode, resolver, table, tableAlias),
+    ),
   );
 }
 

package/src/adapters/generic-sql/sql-adapter-pglite-migrations.test.ts

@@ -1,17 +1,12 @@
-import { KyselyPGlite } from "kysely-pglite";
 import { beforeAll, describe, expect, expectTypeOf, it } from "vitest";
-import { SqlAdapter } from "./generic-sql-adapter";
-import {
-  column,
-  idColumn,
-  referenceColumn,
-  schema,
-  type FragnoId,
-  type FragnoReference,
-} from "../../schema/create";
+
+import { KyselyPGlite } from "kysely-pglite";
+
+import { internalSchema } from "../../fragments/internal-fragment";
 import { Cursor } from "../../query/cursor";
+import { column, idColumn, referenceColumn, schema, type FragnoId } from "../../schema/create";
 import { PGLiteDriverConfig } from "./driver-config";
-import { internalSchema } from "../../fragments/internal-fragment";
+import { SqlAdapter } from "./generic-sql-adapter";
 
 describe("SqlAdapter PGLite", () => {
   const testSchema = schema("test", (s) => {
@@ -478,7 +473,6 @@ describe("SqlAdapter PGLite", () => {
     type PostTag = Prettify<InferArrayElement<typeof postTags>>;
     type Tag = Prettify<RemoveIndex<PostTag["tag"]>>;
     expectTypeOf<Tag>().toEqualTypeOf<{
-      id: FragnoId;
       name: string;
     } | null>();
 
@@ -487,10 +481,7 @@ describe("SqlAdapter PGLite", () => {
     expect(typeScriptPosts).toHaveLength(1);
     type Post = Prettify<(typeof typeScriptPosts)[number]["post"]>;
     expectTypeOf<Post>().toEqualTypeOf<{
-      id: FragnoId;
-      user_id: FragnoReference;
       title: string;
-      content: string;
     } | null>();
     expect(typeScriptPosts[0]!.post!.title).toBe("TypeScript Tips");
 

package/src/adapters/generic-sql/sql-adapter-pglite-pagination.test.ts

@@ -1,12 +1,15 @@
-import { PGlite } from "@electric-sql/pglite";
-import { KyselyPGlite } from "kysely-pglite";
 import { beforeAll, describe, expect, expectTypeOf, it } from "vitest";
-import { SqlAdapter } from "./generic-sql-adapter";
-import { column, idColumn, referenceColumn, schema } from "../../schema/create";
-import { Cursor } from "../../query/cursor";
-import { PGLiteDriverConfig } from "./driver-config";
+
+import { KyselyPGlite } from "kysely-pglite";
+
+import { PGlite } from "@electric-sql/pglite";
+
 import { internalSchema } from "../../fragments/internal-fragment";
+import { Cursor } from "../../query/cursor";
+import { column, idColumn, referenceColumn, schema } from "../../schema/create";
 import type { CompiledQuery } from "../../sql-driver/sql-driver";
+import { PGLiteDriverConfig } from "./driver-config";
+import { SqlAdapter } from "./generic-sql-adapter";
 
 describe("SqlAdapter PGLite", () => {
   const testSchema = schema("test", (s) => {
@@ -16,7 +19,8 @@ describe("SqlAdapter PGLite", () => {
           .addColumn("id", idColumn())
           .addColumn("name", column("string"))
           .addColumn("age", column("integer").nullable())
-          .createIndex("name_idx", ["name"]);
+          .createIndex("name_idx", ["name"])
+          .createIndex("name_id_idx", ["name", "id"]);
       })
       .addTable("emails", (t) => {
         return t
@@ -304,6 +308,47 @@ describe("SqlAdapter PGLite", () => {
     expect(emptyPage.cursor).toBeUndefined();
   });
 
+  it("should support composite cursor pagination with findWithCursor()", async () => {
+    const queryEngine = adapter.createQueryEngine(testSchema, "namespace");
+    const nameValue = "SqlAdapter PGLite Composite Cursor";
+
+    const createUow = queryEngine.createUnitOfWork("create-composite-cursor-users");
+    for (let i = 0; i < 5; i += 1) {
+      createUow.create("users", { name: nameValue, age: 50 + i });
+    }
+    await createUow.executeMutations();
+
+    const all = await queryEngine.find("users", (b) =>
+      b
+        .whereIndex("name_id_idx", (eb) => eb("name", "=", nameValue))
+        .orderByIndex("name_id_idx", "asc"),
+    );
+
+    const firstPage = await queryEngine.findWithCursor("users", (b) =>
+      b
+        .whereIndex("name_id_idx", (eb) => eb("name", "=", nameValue))
+        .orderByIndex("name_id_idx", "asc")
+        .pageSize(2),
+    );
+
+    const secondPage = await queryEngine.findWithCursor("users", (b) =>
+      b
+        .whereIndex("name_id_idx", (eb) => eb("name", "=", nameValue))
+        .after(firstPage.cursor!)
+        .orderByIndex("name_id_idx", "asc")
+        .pageSize(2),
+    );
+
+    const ids = (rows: { id: { externalId: string } }[]) => rows.map((row) => row.id.externalId);
+
+    expect(all.length).toBeGreaterThanOrEqual(5);
+    expect(firstPage.items).toHaveLength(2);
+    expect(firstPage.cursor).toBeInstanceOf(Cursor);
+    expect(firstPage.hasNextPage).toBe(true);
+    expect(ids(firstPage.items)).toEqual(ids(all).slice(0, 2));
+    expect(ids([...firstPage.items, ...secondPage.items])).toEqual(ids(all).slice(0, 4));
+  });
+
   it("should support findWithCursor() in Unit of Work", async () => {
     const queryEngine = adapter.createQueryEngine(testSchema, "namespace");
     const prefix = "SqlAdapter PGLite UOW Cursor";

package/src/adapters/generic-sql/sql-adapter-pglite-queries.test.ts

@@ -1,12 +1,15 @@
-import { PGlite } from "@electric-sql/pglite";
-import { KyselyPGlite } from "kysely-pglite";
-import { SqlAdapter } from "./generic-sql-adapter";
 import { beforeAll, describe, expect, expectTypeOf, it } from "vitest";
-import { column, idColumn, referenceColumn, schema } from "../../schema/create";
+
+import { KyselyPGlite } from "kysely-pglite";
+
+import { PGlite } from "@electric-sql/pglite";
+
+import { internalSchema } from "../../fragments/internal-fragment";
 import { Cursor } from "../../query/cursor";
-import { PGLiteDriverConfig } from "./driver-config";
+import { column, idColumn, referenceColumn, schema } from "../../schema/create";
 import type { CompiledQuery } from "../../sql-driver/sql-driver";
-import { internalSchema } from "../../fragments/internal-fragment";
+import { PGLiteDriverConfig } from "./driver-config";
+import { SqlAdapter } from "./generic-sql-adapter";
 
 describe("SqlAdapter PGLite", () => {
   let pgliteDatabase: PGlite;