@fragno-dev/db 0.1.15 → 0.2.0

package/src/adapters/generic-sql/uow-decoder.test.ts

@@ -0,0 +1,399 @@
+import { describe, it, expect } from "vitest";
+import { schema, idColumn, column, FragnoId } from "../../schema/create";
+import { UnitOfWorkDecoder } from "./uow-decoder";
+import { SQLocalDriverConfig } from "./driver-config";
+import type { RetrievalOperation } from "../../query/unit-of-work/unit-of-work";
+import type { AnySchema } from "../../schema/create";
+
+describe("UnitOfWorkDecoder", () => {
+  const driverConfig = new SQLocalDriverConfig();
+
+  const testSchema = schema((s) => {
+    return s
+      .addTable("users", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("name", column("string"))
+          .addColumn("email", column("string"))
+          .addColumn("age", column("integer").nullable())
+          .createIndex("idx_email", ["email"], { unique: true });
+      })
+      .addTable("posts", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("title", column("string"))
+          .addColumn("content", column("string"))
+          .createIndex("idx_title", ["title"]);
+      });
+  });
+
+  const decoder = new UnitOfWorkDecoder(driverConfig);
+
+  describe("decode", () => {
+    it("should decode regular find operations", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const rawResults = [
+        [
+          { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+          { id: "user2", name: "Bob", email: "bob@example.com", age: null },
+        ],
+      ];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      expect(results[0]).toEqual([
+        { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+        { id: "user2", name: "Bob", email: "bob@example.com", age: null },
+      ]);
+    });
+
+    it("should decode count operations", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "count",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const rawResults = [[{ count: 42 }]];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      expect(results[0]).toBe(42);
+    });
+
+    it("should decode cursor-paginated operations", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+          pageSize: 2,
+          orderByIndex: {
+            indexName: "_primary",
+            direction: "asc",
+          },
+        },
+        withCursor: true,
+      };
+
+      // Fetch pageSize + 1 to detect hasNextPage
+      const rawResults = [
+        [
+          { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+          { id: "user2", name: "Bob", email: "bob@example.com", age: 25 },
+          { id: "user3", name: "Charlie", email: "charlie@example.com", age: 35 },
+        ],
+      ];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      const cursorResult = results[0] as {
+        items: unknown[];
+        cursor?: unknown;
+        hasNextPage: boolean;
+      };
+
+      expect(cursorResult.items).toHaveLength(2);
+      expect(cursorResult.items).toEqual([
+        { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+        { id: "user2", name: "Bob", email: "bob@example.com", age: 25 },
+      ]);
+      expect(cursorResult.hasNextPage).toBe(true);
+      expect(cursorResult.cursor).toBeDefined();
+    });
+
+    it("should decode cursor-paginated operations without hasNextPage when exactly pageSize rows", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+          pageSize: 2,
+          orderByIndex: {
+            indexName: "_primary",
+            direction: "asc",
+          },
+        },
+        withCursor: true,
+      };
+
+      const rawResults = [
+        [
+          { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+          { id: "user2", name: "Bob", email: "bob@example.com", age: 25 },
+        ],
+      ];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      const cursorResult = results[0] as {
+        items: unknown[];
+        cursor?: unknown;
+        hasNextPage: boolean;
+      };
+
+      expect(cursorResult.items).toHaveLength(2);
+      expect(cursorResult.hasNextPage).toBe(false);
+      expect(cursorResult.cursor).toBeUndefined();
+    });
+
+    it("should decode multiple operations", () => {
+      const findOperation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const countOperation: RetrievalOperation<AnySchema> = {
+        type: "count",
+        schema: testSchema,
+        table: testSchema.tables.posts,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const rawResults = [
+        [{ id: "user1", name: "Alice", email: "alice@example.com", age: 30 }],
+        [{ count: 5 }],
+      ];
+
+      const results = decoder.decode(rawResults, [findOperation, countOperation]);
+
+      expect(results).toHaveLength(2);
+      expect(results[0]).toEqual([
+        { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+      ]);
+      expect(results[1]).toBe(5);
+    });
+
+    it("should throw error when rawResults and operations lengths don't match", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const rawResults = [[{ id: "user1", name: "Alice" }], [{ id: "user2", name: "Bob" }]];
+
+      expect(() => decoder.decode(rawResults, [operation])).toThrow(
+        "rawResults and ops must have the same length",
+      );
+    });
+
+    it("should handle empty results for regular find", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const rawResults = [[]];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      expect(results[0]).toEqual([]);
+    });
+
+    it("should handle count result with no rows", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "count",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const rawResults = [[]];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      expect(results[0]).toBe(0);
+    });
+
+    it("should generate cursor for custom index", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "idx_email",
+        options: {
+          useIndex: "idx_email",
+          pageSize: 1,
+          orderByIndex: {
+            indexName: "idx_email",
+            direction: "asc",
+          },
+        },
+        withCursor: true,
+      };
+
+      const rawResults = [
+        [
+          { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+          { id: "user2", name: "Bob", email: "bob@example.com", age: 25 },
+        ],
+      ];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      const cursorResult = results[0] as {
+        items: unknown[];
+        cursor?: unknown;
+        hasNextPage: boolean;
+      };
+
+      expect(cursorResult.items).toHaveLength(1);
+      expect(cursorResult.hasNextPage).toBe(true);
+      expect(cursorResult.cursor).toBeDefined();
+    });
+
+    it("should handle cursor pagination without orderByIndex", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+          pageSize: 2,
+        },
+        withCursor: true,
+      };
+
+      const rawResults = [
+        [
+          { id: "user1", name: "Alice", email: "alice@example.com", age: 30 },
+          { id: "user2", name: "Bob", email: "bob@example.com", age: 25 },
+          { id: "user3", name: "Charlie", email: "charlie@example.com", age: 35 },
+        ],
+      ];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      const cursorResult = results[0] as {
+        items: unknown[];
+        cursor?: unknown;
+        hasNextPage: boolean;
+      };
+
+      expect(cursorResult.items).toHaveLength(2);
+      expect(cursorResult.hasNextPage).toBe(true);
+      expect(cursorResult.cursor).toBeUndefined(); // No cursor when orderByIndex is missing
+    });
+
+    it("should throw error for invalid count value", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "count",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+        },
+      };
+
+      const rawResults = [[{ count: "invalid" }]];
+
+      expect(() => decoder.decode(rawResults, [operation])).toThrow(
+        "Unexpected result for count, received: NaN",
+      );
+    });
+
+    it("should handle cursor pagination with FragnoId in cursor", () => {
+      const operation: RetrievalOperation<AnySchema> = {
+        type: "find",
+        schema: testSchema,
+        table: testSchema.tables.users,
+        indexName: "_primary",
+        options: {
+          useIndex: "_primary",
+          pageSize: 1,
+          orderByIndex: {
+            indexName: "_primary",
+            direction: "asc",
+          },
+        },
+        withCursor: true,
+      };
+
+      const rawResults = [
+        [
+          {
+            id: "user1",
+            _internalId: BigInt(123),
+            _version: 1,
+            name: "Alice",
+            email: "alice@example.com",
+            age: 30,
+          },
+          {
+            id: "user2",
+            _internalId: BigInt(456),
+            _version: 1,
+            name: "Bob",
+            email: "bob@example.com",
+            age: 25,
+          },
+        ],
+      ];
+
+      const results = decoder.decode(rawResults, [operation]);
+
+      expect(results).toHaveLength(1);
+      const cursorResult = results[0] as {
+        items: unknown[];
+        cursor?: unknown;
+        hasNextPage: boolean;
+      };
+
+      expect(cursorResult.items).toHaveLength(1);
+      expect(cursorResult.hasNextPage).toBe(true);
+      expect(cursorResult.cursor).toBeDefined();
+
+      // Verify the item has FragnoId
+      const firstItem = cursorResult.items[0] as Record<string, unknown>;
+      expect(firstItem["id"]).toBeInstanceOf(FragnoId);
+    });
+  });
+});

package/src/adapters/generic-sql/uow-decoder.ts

@@ -0,0 +1,152 @@
+import type { UOWDecoder } from "../../query/unit-of-work/unit-of-work";
+import type { RetrievalOperation } from "../../query/unit-of-work/unit-of-work";
+import type { AnySchema, AnyTable } from "../../schema/create";
+import { decodeResult } from "../../query/value-decoding";
+import { createCursorFromRecord, type Cursor, type CursorResult } from "../../query/cursor";
+import type { DriverConfig } from "./driver-config";
+
+/**
+ * Decoder class for Unit of Work retrieval results.
+ *
+ * Transforms raw database results into application format (e.g., converting raw columns
+ * into FragnoId objects with external ID, internal ID, and version).
+ */
+export class UnitOfWorkDecoder implements UOWDecoder<unknown> {
+  readonly #driverConfig: DriverConfig;
+
+  constructor(driverConfig: DriverConfig) {
+    this.#driverConfig = driverConfig;
+  }
+
+  /**
+   * Decode raw database results from the retrieval phase
+   *
+   * @param rawResults - Array of raw result sets from database queries
+   * @param operations - Array of retrieval operations that produced these results
+   * @returns Decoded results in application format
+   */
+  decode(rawResults: unknown[], operations: RetrievalOperation<AnySchema>[]): unknown[] {
+    if (rawResults.length !== operations.length) {
+      throw new Error("rawResults and ops must have the same length");
+    }
+
+    return rawResults.map((rows, index) => {
+      const op = operations[index];
+      if (!op) {
+        throw new Error("op must be defined");
+      }
+
+      const rowArray = rows as Record<string, unknown>[];
+      return this.decodeResultSet(rowArray, op);
+    });
+  }
+
+  /**
+   * Decodes a result set based on the operation type.
+   *
+   * This is the main entry point for decoding query results, routing to the
+   * appropriate decoder based on whether it's a count, cursor, or regular query.
+   *
+   * @param rows - The raw database rows
+   * @param operation - The retrieval operation defining how to decode the result
+   * @returns The decoded result (number for count, CursorResult for cursor, array otherwise)
+   */
+  private decodeResultSet(
+    rows: Record<string, unknown>[],
+    operation: RetrievalOperation<AnySchema>,
+  ): number | Record<string, unknown>[] | CursorResult<unknown> {
+    // Handle count operations
+    if (operation.type === "count") {
+      return this.decodeCountResult(rows);
+    }
+
+    const decodedRows = rows.map((row) => decodeResult(row, operation.table, this.#driverConfig));
+
+    if (operation.withCursor) {
+      return this.decodeCursorResult(decodedRows, operation.table, operation);
+    }
+
+    return decodedRows;
+  }
+
+  /**
+   * Decodes a count query result to a number.
+   *
+   * @param rows - The raw database rows (should contain a single row with a count column)
+   * @returns The count as a number
+   * @throws If the count value is invalid or missing
+   */
+  private decodeCountResult(rows: Record<string, unknown>[]): number {
+    const firstRow = rows[0];
+    if (!firstRow) {
+      return 0;
+    }
+    const count = Number(firstRow["count"]);
+    if (Number.isNaN(count)) {
+      throw new Error(`Unexpected result for count, received: ${count}`);
+    }
+    return count;
+  }
+
+  /**
+   * Handles cursor generation and hasNextPage detection for cursor-paginated queries.
+   *
+   * Checks if we received more rows than the requested pageSize (we fetch pageSize + 1).
+   *
+   * @param decodedRows - The already-decoded database rows (pageSize + 1 rows)
+   * @param table - The table schema definition (needed for cursor generation)
+   * @param operation - The find operation containing pagination options
+   * @returns A CursorResult with items, cursor, and hasNextPage
+   */
+  private decodeCursorResult(
+    decodedRows: Record<string, unknown>[],
+    table: AnyTable,
+    operation: Extract<RetrievalOperation<AnySchema>, { type: "find" }>,
+  ): CursorResult<unknown> {
+    let cursor: Cursor | undefined;
+    let hasNextPage = false;
+    let items = decodedRows;
+
+    // Check if there are more results (we fetched pageSize + 1)
+    if (
+      operation.options.pageSize &&
+      operation.options.pageSize > 0 &&
+      decodedRows.length > operation.options.pageSize
+    ) {
+      hasNextPage = true;
+      // Trim to requested pageSize
+      items = decodedRows.slice(0, operation.options.pageSize);
+
+      // Generate cursor from the last item we're returning
+      if (operation.options.orderByIndex) {
+        const lastItem = items[items.length - 1];
+        const indexName = operation.options.orderByIndex.indexName;
+
+        // Get index columns
+        let indexColumns;
+        if (indexName === "_primary") {
+          indexColumns = [table.getIdColumn()];
+        } else {
+          const index = table.indexes[indexName];
+          if (index) {
+            indexColumns = index.columns;
+          }
+        }
+
+        if (indexColumns && lastItem) {
+          cursor = createCursorFromRecord(lastItem, indexColumns, {
+            indexName: operation.options.orderByIndex.indexName,
+            orderDirection: operation.options.orderByIndex.direction,
+            pageSize: operation.options.pageSize,
+          });
+        }
+      }
+    }
+
+    return {
+      items,
+      cursor,
+      hasNextPage,
+    };
+  }
+}