@fragno-dev/db 0.1.11 → 0.1.13

package/src/query/query.ts

@@ -8,6 +8,7 @@ import type {
   UpdateManyBuilder,
 } from "./unit-of-work";
 import type { Prettify } from "../util/types";
+import type { CursorResult } from "./cursor";
 
 export type AnySelectClause = SelectClause<AnyTable>;
 
@@ -17,7 +18,7 @@ export type RawColumnValues<T extends AnyTable> = {
   [K in keyof T["columns"] as string extends K ? never : K]: T["columns"][K]["$out"];
 };
 
-export type TableToColumnValues<T extends AnyTable> = RawColumnValues<T>;
+export type TableToColumnValues<T extends AnyTable> = Prettify<RawColumnValues<T>>;
 
 type PickNullable<T> = {
   [P in keyof T as null extends T[P] ? P : never]: T[P];
@@ -44,18 +45,16 @@ export type TableToUpdateValues<T extends AnyTable> = {
 type MainSelectResult<S extends SelectClause<T>, T extends AnyTable> = S extends true
   ? TableToColumnValues<T>
   : S extends (keyof T["columns"])[]
-    ? {
+    ? Prettify<{
         [K in S[number] as string extends K ? never : K]: K extends keyof T["columns"]
           ? T["columns"][K]["$out"]
           : never;
-      }
+      }>
     : never;
 
-export type SelectResult<
-  T extends AnyTable,
-  JoinOut,
-  Select extends SelectClause<T>,
-> = MainSelectResult<Select, T> & JoinOut;
+export type SelectResult<T extends AnyTable, JoinOut, Select extends SelectClause<T>> = Prettify<
+  MainSelectResult<Select, T> & JoinOut
+>;
 
 interface MapRelationType<Type> {
   one: Type | null;
@@ -68,15 +67,43 @@ export type JoinBuilder<T extends AnyTable, Out = {}> = {
         options?: FindManyOptions<Target, Select, JoinOut, false>,
       ) => JoinBuilder<
         T,
-        Out & {
-          [$K in K]: MapRelationType<SelectResult<Target, JoinOut, Select>>[Type];
-        }
+        Prettify<
+          Out & {
+            [$K in K]: MapRelationType<SelectResult<Target, JoinOut, Select>>[Type];
+          }
+        >
       >
     : never;
 };
 
 export type OrderBy<Column = string> = [columnName: Column, "asc" | "desc"];
 
+/**
+ * Extract Select type parameter from a FindBuilder type (handles Omit wrapper)
+ * @internal
+ */
+type ExtractSelect<T> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends FindBuilder<any, infer TSelect, any>
+    ? TSelect
+    : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      T extends Omit<FindBuilder<any, infer TSelect, any>, any>
+      ? TSelect
+      : true;
+
+/**
+ * Extract JoinOut type parameter from a FindBuilder type (handles Omit wrapper)
+ * @internal
+ */
+type ExtractJoinOut<T> =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends FindBuilder<any, any, infer TJoinOut>
+    ? TJoinOut
+    : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      T extends Omit<FindBuilder<any, any, infer TJoinOut>, any>
+      ? TJoinOut
+      : {};
+
 export type FindFirstOptions<
   T extends AnyTable = AnyTable,
   Select extends SelectClause<T> = SelectClause<T>,
@@ -109,31 +136,66 @@ export interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
   /**
    * Find multiple records using a builder pattern
    */
-  find: <
-    TableName extends keyof TSchema["tables"] & string,
-    Select extends SelectClause<TSchema["tables"][TableName]> = true,
-    JoinOut = {},
-  >(
+  find: {
+    // Overload when builder function is provided - infer Select and JoinOut from builder
+    <TableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
+      table: TableName,
+      builderFn: (
+        builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
+      ) => TBuilderResult,
+    ): Promise<
+      SelectResult<
+        TSchema["tables"][TableName],
+        ExtractJoinOut<TBuilderResult>,
+        Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TableName]>>
+      >[]
+    >;
+    // Overload when no builder function - return all columns
+    <TableName extends keyof TSchema["tables"] & string>(
+      table: TableName,
+    ): Promise<SelectResult<TSchema["tables"][TableName], {}, true>[]>;
+  };
+
+  /**
+   * Find multiple records with cursor pagination metadata
+   */
+  findWithCursor: <TableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
     table: TableName,
-    builderFn?: (
+    builderFn: (
       builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
-    ) => Omit<FindBuilder<TSchema["tables"][TableName], Select, JoinOut>, "build">,
-  ) => Promise<SelectResult<TSchema["tables"][TableName], JoinOut, Select>[]>;
+    ) => TBuilderResult,
+  ) => Promise<
+    CursorResult<
+      SelectResult<
+        TSchema["tables"][TableName],
+        ExtractJoinOut<TBuilderResult>,
+        Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TableName]>>
+      >
+    >
+  >;
 
   /**
    * Find the first record matching the criteria
    * Implemented as a wrapper around find() with pageSize(1)
    */
-  findFirst: <
-    TableName extends keyof TSchema["tables"] & string,
-    Select extends SelectClause<TSchema["tables"][TableName]> = true,
-    JoinOut = {},
-  >(
-    table: TableName,
-    builderFn?: (
-      builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
-    ) => Omit<FindBuilder<TSchema["tables"][TableName], Select, JoinOut>, "build">,
-  ) => Promise<SelectResult<TSchema["tables"][TableName], JoinOut, Select> | null>;
+  findFirst: {
+    // Overload when builder function is provided - infer Select and JoinOut from builder
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    <TableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
+      table: TableName,
+      builderFn: (
+        builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">,
+      ) => TBuilderResult,
+    ): Promise<SelectResult<
+      TSchema["tables"][TableName],
+      ExtractJoinOut<TBuilderResult>,
+      Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TableName]>>
+    > | null>;
+    // Overload when no builder function - return all columns
+    <TableName extends keyof TSchema["tables"] & string>(
+      table: TableName,
+    ): Promise<SelectResult<TSchema["tables"][TableName], {}, true> | null>;
+  };
 
   /**
    * Create a single record
@@ -161,8 +223,8 @@ export interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
     table: TableName,
     id: FragnoId | string,
     builderFn: (
-      builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build" | "check">,
-    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build" | "check">,
+      builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
+    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
   ) => Promise<void>;
 
   /**
@@ -180,9 +242,7 @@ export interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
   delete: <TableName extends keyof TSchema["tables"] & string>(
     table: TableName,
     id: FragnoId | string,
-    builderFn?: (
-      builder: Omit<DeleteBuilder, "build" | "check">,
-    ) => Omit<DeleteBuilder, "build" | "check">,
+    builderFn?: (builder: Omit<DeleteBuilder, "build">) => Omit<DeleteBuilder, "build">,
   ) => Promise<void>;
 
   /**

package/src/query/result-transform.test.ts

@@ -226,7 +226,7 @@ describe("encodeValues", () => {
       });
     });
 
-    it("should fallback to external ID for reference when internal ID unavailable", () => {
+    it("should convert FragnoId without internalId to ReferenceSubquery for reference columns", () => {
       const fragnoId = new FragnoId({
         externalId: "user123",
         version: 1,
@@ -238,10 +238,10 @@ describe("encodeValues", () => {
         "postgresql",
       );
 
-      expect(result).toEqual({
-        title: "Test Post",
-        userId: "user123",
-      });
+      // FragnoId without internalId should be converted to ReferenceSubquery for database lookup
+      expect(result["title"]).toBe("Test Post");
+      expect(result["userId"]).toBeInstanceOf(ReferenceSubquery);
+      expect((result["userId"] as ReferenceSubquery).externalIdValue).toBe("user123");
     });
 
     it("should handle FragnoId across different providers", () => {

package/src/query/result-transform.ts

@@ -123,18 +123,36 @@ export function encodeValues(
     }
 
     if (value !== undefined) {
-      // Handle string references - convert external ID to internal ID via subquery
-      if (col.role === "reference" && typeof value === "string") {
-        // Find relation that uses this column
-        const relation = Object.values(table.relations).find((rel) =>
-          rel.on.some(([localCol]) => localCol === k),
-        );
-        if (relation) {
-          result[col.name] = new ReferenceSubquery(relation.table, value);
-          continue;
+      // Handle string references and FragnoId objects
+      if (col.role === "reference") {
+        if (typeof value === "string") {
+          // String external ID - generate subquery
+          const relation = Object.values(table.relations).find((rel) =>
+            rel.on.some(([localCol]) => localCol === k),
+          );
+          if (relation) {
+            result[col.name] = new ReferenceSubquery(relation.table, value);
+            continue;
+          }
+          throw new Error(`Reference column ${k} not found in table ${table.name}`);
+        } else if (value instanceof FragnoId) {
+          // FragnoId object
+          if (value.internalId !== undefined) {
+            // If internal ID is populated, use it directly (no subquery needed)
+            result[col.name] = value.internalId;
+            continue;
+          } else {
+            // If internal ID is not populated, use external ID via subquery
+            const relation = Object.values(table.relations).find((rel) =>
+              rel.on.some(([localCol]) => localCol === k),
+            );
+            if (relation) {
+              result[col.name] = new ReferenceSubquery(relation.table, value.externalId);
+              continue;
+            }
+            throw new Error(`Reference column ${k} not found in table ${table.name}`);
+          }
         }
-
-        throw new Error(`Reference column ${k} not found in table ${table.name}`);
       }
 
       result[col.name] = serialize(value, col, provider);

package/src/query/unit-of-work.ts

@@ -4,6 +4,8 @@ import type { Condition, ConditionBuilder } from "./condition-builder";
 import type { SelectClause, TableToInsertValues, TableToUpdateValues, SelectResult } from "./query";
 import { buildCondition } from "./condition-builder";
 import type { CompiledJoin } from "./orm/orm";
+import type { CursorResult } from "./cursor";
+import { Cursor } from "./cursor";
 
 /**
  * Builder for updateMany operations that supports both whereIndex and set chaining
@@ -112,11 +114,11 @@ type FindOptions<
   /**
    * Cursor for pagination - continue after this cursor
    */
-  after?: string;
+  after?: Cursor | string;
   /**
    * Cursor for pagination - continue before this cursor
    */
-  before?: string;
+  before?: Cursor | string;
   /**
    * Number of results per page
    */
@@ -144,6 +146,7 @@ export type RetrievalOperation<
       table: TTable;
       indexName: string;
       options: FindOptions<TTable, SelectClause<TTable>>;
+      withCursor?: boolean;
     }
   | {
       type: "count";
@@ -262,12 +265,13 @@ export class FindBuilder<
     indexName: string;
     direction: "asc" | "desc";
   };
-  #afterCursor?: string;
-  #beforeCursor?: string;
+  #afterCursor?: Cursor | string;
+  #beforeCursor?: Cursor | string;
   #pageSizeValue?: number;
   #selectClause?: TSelect;
   #joinClause?: (jb: IndexedJoinBuilder<TTable, {}>) => IndexedJoinBuilder<TTable, TJoinOut>;
   #countMode = false;
+  #cursorMetadata?: Cursor;
 
   constructor(tableName: string, table: TTable) {
     this.#tableName = tableName;
@@ -357,17 +361,27 @@ export class FindBuilder<
 
   /**
    * Set cursor to continue pagination after this point (forward pagination)
+   * If a Cursor object is provided, its metadata will be used to set defaults for
+   * index, orderByIndex, and pageSize (if not explicitly set)
    */
-  after(cursor: string): this {
+  after(cursor: Cursor | string): this {
     this.#afterCursor = cursor;
+    if (cursor instanceof Cursor) {
+      this.#cursorMetadata = cursor;
+    }
     return this;
   }
 
   /**
    * Set cursor to continue pagination before this point (backward pagination)
+   * If a Cursor object is provided, its metadata will be used to set defaults for
+   * index, orderByIndex, and pageSize (if not explicitly set)
    */
-  before(cursor: string): this {
+  before(cursor: Cursor | string): this {
     this.#beforeCursor = cursor;
+    if (cursor instanceof Cursor) {
+      this.#cursorMetadata = cursor;
+    }
     return this;
   }
 
@@ -400,7 +414,47 @@ export class FindBuilder<
         indexName: string;
         options: Pick<FindOptions<TTable>, "where" | "useIndex">;
       } {
-    if (!this.#indexName) {
+    // Apply cursor metadata as defaults if available and not explicitly set
+    let indexName = this.#indexName;
+    let orderByIndex = this.#orderByIndexClause;
+    let pageSize = this.#pageSizeValue;
+
+    if (this.#cursorMetadata) {
+      // Use cursor metadata as defaults
+      if (!indexName) {
+        indexName = this.#cursorMetadata.indexName;
+      }
+      if (!orderByIndex) {
+        orderByIndex = {
+          indexName: this.#cursorMetadata.indexName,
+          direction: this.#cursorMetadata.orderDirection,
+        };
+      }
+      if (pageSize === undefined) {
+        pageSize = this.#cursorMetadata.pageSize;
+      }
+
+      // Validate that explicit params match cursor params
+      if (indexName && indexName !== this.#cursorMetadata.indexName) {
+        throw new Error(
+          `Index mismatch: builder specifies "${indexName}" but cursor specifies "${this.#cursorMetadata.indexName}"`,
+        );
+      }
+      if (
+        orderByIndex &&
+        (orderByIndex.indexName !== this.#cursorMetadata.indexName ||
+          orderByIndex.direction !== this.#cursorMetadata.orderDirection)
+      ) {
+        throw new Error(`Order mismatch: builder and cursor specify different ordering`);
+      }
+      if (pageSize !== undefined && pageSize !== this.#cursorMetadata.pageSize) {
+        throw new Error(
+          `Page size mismatch: builder specifies ${pageSize} but cursor specifies ${this.#cursorMetadata.pageSize}`,
+        );
+      }
+    }
+
+    if (!indexName) {
       throw new Error(
         `Must specify an index using .whereIndex() before finalizing find operation on table "${this.#tableName}"`,
       );
@@ -410,9 +464,9 @@ export class FindBuilder<
     if (this.#countMode) {
       return {
         type: "count",
-        indexName: this.#indexName,
+        indexName,
         options: {
-          useIndex: this.#indexName,
+          useIndex: indexName,
           where: this.#whereClause,
         },
       };
@@ -424,18 +478,24 @@ export class FindBuilder<
       compiledJoins = buildJoinIndexed(this.#table, this.#joinClause);
     }
 
+    // Convert Cursor objects to strings for after/before
+    const afterCursor =
+      this.#afterCursor instanceof Cursor ? this.#afterCursor.encode() : this.#afterCursor;
+    const beforeCursor =
+      this.#beforeCursor instanceof Cursor ? this.#beforeCursor.encode() : this.#beforeCursor;
+
     const options: FindOptions<TTable, TSelect> = {
-      useIndex: this.#indexName,
+      useIndex: indexName,
       select: this.#selectClause,
       where: this.#whereClause,
-      orderByIndex: this.#orderByIndexClause,
-      after: this.#afterCursor,
-      before: this.#beforeCursor,
-      pageSize: this.#pageSizeValue,
+      orderByIndex,
+      after: afterCursor,
+      before: beforeCursor,
+      pageSize,
       joins: compiledJoins,
     };
 
-    return { type: "find", indexName: this.#indexName, options };
+    return { type: "find", indexName, options };
   }
 }
 
@@ -939,7 +999,7 @@ export class UnitOfWork<
     builderFn?: (
       // We omit "build" because we don't want to expose it to the user
       builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
-    ) => Omit<FindBuilder<TSchema["tables"][TTableName], TSelect, TJoinOut>, "build">,
+    ) => Omit<FindBuilder<TSchema["tables"][TTableName], TSelect, TJoinOut>, "build"> | void,
   ): UnitOfWork<
     TSchema,
     [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], TJoinOut, TSelect>[]],
@@ -983,13 +1043,72 @@ export class UnitOfWork<
     >;
   }
 
+  /**
+   * Add a find operation with cursor metadata (retrieval phase only)
+   */
+  findWithCursor<
+    TTableName extends keyof TSchema["tables"] & string,
+    TSelect extends SelectClause<TSchema["tables"][TTableName]> = true,
+    TJoinOut = {},
+  >(
+    tableName: TTableName,
+    builderFn: (
+      // We omit "build" because we don't want to expose it to the user
+      builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
+    ) => Omit<FindBuilder<TSchema["tables"][TTableName], TSelect, TJoinOut>, "build"> | void,
+  ): UnitOfWork<
+    TSchema,
+    [
+      ...TRetrievalResults,
+      CursorResult<SelectResult<TSchema["tables"][TTableName], TJoinOut, TSelect>>,
+    ],
+    TRawInput
+  > {
+    if (this.#state !== "building-retrieval") {
+      throw new Error(
+        `findWithCursor() can only be called during retrieval phase. Current state: ${this.#state}`,
+      );
+    }
+
+    const table = this.#schema.tables[tableName];
+    if (!table) {
+      throw new Error(`Table ${tableName} not found in schema`);
+    }
+
+    // Create builder and pass to callback
+    const builder = new FindBuilder(tableName, table as TSchema["tables"][TTableName]);
+    builderFn(builder);
+    const { indexName, options, type } = builder.build();
+
+    this.#retrievalOps.push({
+      type,
+      // Safe: we know the table is part of the schema from the findWithCursor() method
+      table: table as TSchema["tables"][TTableName],
+      indexName,
+      // Safe: we're storing the options for later compilation
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      options: options as any,
+      withCursor: true,
+    });
+
+    return this as unknown as UnitOfWork<
+      TSchema,
+      [
+        ...TRetrievalResults,
+        CursorResult<SelectResult<TSchema["tables"][TTableName], TJoinOut, TSelect>>,
+      ],
+      TRawInput
+    >;
+  }
+
   /**
    * Add a create operation (mutation phase only)
+   * Returns a FragnoId with the external ID that can be used immediately in subsequent operations
    */
   create<TableName extends keyof TSchema["tables"] & string>(
     table: TableName,
     values: TableToInsertValues<TSchema["tables"][TableName]>,
-  ): this {
+  ): FragnoId {
     if (this.#state === "executed") {
       throw new Error(`create() can only be called during mutation phase.`);
     }
@@ -1041,7 +1160,7 @@ export class UnitOfWork<
       generatedExternalId: externalId,
     });
 
-    return this;
+    return FragnoId.fromExternal(externalId, 0);
   }
 
   /**
@@ -1053,8 +1172,8 @@ export class UnitOfWork<
     builderFn: (
       // We omit "build" because we don't want to expose it to the user
       builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
-    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
-  ): this {
+    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build"> | void,
+  ): void {
     if (this.#state === "executed") {
       throw new Error(`update() can only be called during mutation phase.`);
     }
@@ -1071,8 +1190,6 @@ export class UnitOfWork<
       checkVersion,
       set,
     });
-
-    return this;
   }
 
   /**
@@ -1084,8 +1201,8 @@ export class UnitOfWork<
     builderFn?: (
       // We omit "build" because we don't want to expose it to the user
       builder: Omit<DeleteBuilder, "build">,
-    ) => Omit<DeleteBuilder, "build">,
-  ): this {
+    ) => Omit<DeleteBuilder, "build"> | void,
+  ): void {
     if (this.#state === "executed") {
       throw new Error(`delete() can only be called during mutation phase.`);
     }
@@ -1101,8 +1218,6 @@ export class UnitOfWork<
       id: opId,
       checkVersion,
     });
-
-    return this;
   }
 
   /**