@fragno-dev/db 0.3.0 → 0.4.1

package/src/query/cursor-client.test.ts

@@ -0,0 +1,70 @@
+import { beforeAll, describe, expect, it } from "vitest";
+
+import type { AnyColumn } from "../schema/create";
+import { Cursor, createCursorFromRecord, decodeCursor } from "./cursor-client";
+
+const ensureBase64Helpers = () => {
+  const g = globalThis as typeof globalThis & {
+    btoa?: (input: string) => string;
+    atob?: (input: string) => string;
+  };
+
+  if (!g.btoa) {
+    g.btoa = (input: string) => Buffer.from(input, "binary").toString("base64");
+  }
+
+  if (!g.atob) {
+    g.atob = (input: string) => Buffer.from(input, "base64").toString("binary");
+  }
+};
+
+beforeAll(() => {
+  ensureBase64Helpers();
+});
+
+describe("cursor-client", () => {
+  it("roundtrips cursor data with unicode values", () => {
+    const cursor = new Cursor({
+      indexName: "idx_created",
+      orderDirection: "asc",
+      pageSize: 25,
+      indexValues: {
+        createdAt: 1730000000000,
+        name: "München",
+      },
+    });
+
+    const encoded = cursor.encode();
+    const decoded = decodeCursor(encoded);
+
+    expect(decoded.indexName).toBe("idx_created");
+    expect(decoded.orderDirection).toBe("asc");
+    expect(decoded.pageSize).toBe(25);
+    expect(decoded.indexValues).toEqual({
+      createdAt: 1730000000000,
+      name: "München",
+    });
+  });
+
+  it("creates a cursor from a record", () => {
+    const column: AnyColumn = {
+      name: "createdAt",
+      type: "timestamp",
+      role: "regular",
+      isNullable: false,
+    } as AnyColumn;
+
+    const cursor = createCursorFromRecord({ createdAt: 123, other: "ignore" }, [column], {
+      indexName: "idx_created",
+      orderDirection: "desc",
+      pageSize: 10,
+    });
+
+    expect(cursor.indexValues).toEqual({ createdAt: 123 });
+    expect(cursor.orderDirection).toBe("desc");
+  });
+
+  it("rejects malformed cursor payloads", () => {
+    expect(() => decodeCursor("not-base64")).toThrowError(/Invalid cursor/);
+  });
+});

package/src/query/cursor-client.ts

@@ -0,0 +1,263 @@
+import type { AnyColumn } from "../schema/create";
+
+/**
+ * Cursor object containing all information needed for pagination
+ */
+export class Cursor {
+  readonly #indexName: string;
+  readonly #orderDirection: "asc" | "desc";
+  readonly #pageSize: number;
+  readonly #indexValues: Record<string, unknown>;
+
+  constructor(data: {
+    indexName: string;
+    orderDirection: "asc" | "desc";
+    pageSize: number;
+    indexValues: Record<string, unknown>;
+  }) {
+    this.#indexName = data.indexName;
+    this.#orderDirection = data.orderDirection;
+    this.#pageSize = data.pageSize;
+    this.#indexValues = data.indexValues;
+  }
+
+  /**
+   * Get the index name being used for pagination
+   */
+  get indexName(): string {
+    return this.#indexName;
+  }
+
+  /**
+   * Get the ordering direction
+   */
+  get orderDirection(): "asc" | "desc" {
+    return this.#orderDirection;
+  }
+
+  /**
+   * Get the page size
+   */
+  get pageSize(): number {
+    return this.#pageSize;
+  }
+
+  /**
+   * Get the cursor position values
+   */
+  get indexValues(): Record<string, unknown> {
+    return this.#indexValues;
+  }
+
+  /**
+   * Encode cursor to an opaque base64 string (safe to send to client)
+   */
+  encode(): string {
+    assertSerializableIndexValues(this.#indexValues);
+    const data: CursorData = {
+      v: 1,
+      indexName: this.#indexName,
+      orderDirection: this.#orderDirection,
+      pageSize: this.#pageSize,
+      indexValues: this.#indexValues,
+    };
+    return encodeCursorData(data);
+  }
+}
+
+/**
+ * Result of a cursor-based query containing items and pagination cursor
+ */
+export interface CursorResult<T> {
+  /**
+   * The query results
+   */
+  items: T[];
+  /**
+   * Cursor to fetch the next page (undefined if no more results)
+   */
+  cursor?: Cursor;
+  /**
+   * Whether there are more results available after this page
+   */
+  hasNextPage: boolean;
+}
+
+/**
+ * Cursor data structure for serialization
+ */
+export interface CursorData {
+  v: number; // version
+  indexName: string;
+  orderDirection: "asc" | "desc";
+  pageSize: number;
+  indexValues: Record<string, unknown>;
+}
+
+const getBase64Helpers = () => {
+  const { btoa, atob, TextEncoder, TextDecoder } = globalThis;
+
+  if (!btoa || !atob) {
+    throw new Error("Base64 helpers (btoa/atob) are not available in this environment.");
+  }
+
+  if (!TextEncoder || !TextDecoder) {
+    throw new Error("TextEncoder/TextDecoder are required for cursor encoding.");
+  }
+
+  const encodeBase64 = (input: string): string => {
+    const bytes = new TextEncoder().encode(input);
+    let binary = "";
+    for (const byte of bytes) {
+      binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+  };
+
+  const decodeBase64 = (input: string): string => {
+    const binary = atob(input);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder().decode(bytes);
+  };
+
+  return { encodeBase64, decodeBase64 };
+};
+
+/**
+ * Encode cursor data to a base64 string (internal)
+ */
+function encodeCursorData(data: CursorData): string {
+  let json: string;
+  try {
+    json = JSON.stringify(data);
+  } catch (error) {
+    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+  }
+
+  return getBase64Helpers().encodeBase64(json);
+}
+
+/**
+ * Decode a base64 cursor string back to a Cursor object
+ *
+ * @param cursor - The base64-encoded cursor string
+ * @returns Decoded Cursor object
+ * @throws Error if cursor is invalid or malformed
+ *
+ * @example
+ * ```ts
+ * const cursor = decodeCursor("eyJpbmRleFZhbHVlcyI6e30sImRpcmVjdGlvbiI6ImZvcndhcmQifQ==");
+ * ```
+ */
+export function decodeCursor(cursor: string): Cursor {
+  try {
+    const json = getBase64Helpers().decodeBase64(cursor);
+    const data = JSON.parse(json);
+    const record = data as Record<string, unknown>;
+
+    // Validate structure
+    if (
+      !isPlainObject(data) ||
+      !isPlainObject(record["indexValues"]) ||
+      typeof record["indexName"] !== "string" ||
+      record["indexName"].length === 0 ||
+      typeof record["orderDirection"] !== "string" ||
+      (record["orderDirection"] !== "asc" && record["orderDirection"] !== "desc") ||
+      typeof record["pageSize"] !== "number" ||
+      !Number.isFinite(record["pageSize"]) ||
+      !Number.isInteger(record["pageSize"]) ||
+      record["pageSize"] <= 0
+    ) {
+      throw new Error("Invalid cursor structure");
+    }
+
+    // Only support v1
+    if (typeof record["v"] !== "number") {
+      throw new Error("Unsupported cursor version: missing. Only v1 is supported.");
+    }
+    const version = record["v"];
+    if (version !== 1) {
+      throw new Error(`Unsupported cursor version: ${version}. Only v1 is supported.`);
+    }
+
+    return new Cursor({
+      indexName: record["indexName"],
+      orderDirection: record["orderDirection"],
+      pageSize: record["pageSize"],
+      indexValues: record["indexValues"],
+    });
+  } catch (error) {
+    throw new Error(`Invalid cursor: ${error instanceof Error ? error.message : "malformed data"}`);
+  }
+}
+
+/**
+ * Create a cursor from a record and pagination metadata
+ *
+ * @param record - The database record
+ * @param indexColumns - The columns that make up the index
+ * @param metadata - Pagination metadata (index name, order direction, page size)
+ * @returns Cursor object
+ *
+ * @example
+ * ```ts
+ * const cursor = createCursorFromRecord(
+ *   { id: "abc", name: "Alice", createdAt: 123 },
+ *   [table.columns.createdAt, table.columns.id],
+ *   {
+ *     indexName: "idx_created",
+ *     orderDirection: "asc",
+ *     pageSize: 10
+ *   }
+ * );
+ * ```
+ */
+export function createCursorFromRecord(
+  record: Record<string, unknown>,
+  indexColumns: AnyColumn[],
+  metadata: {
+    indexName: string;
+    orderDirection: "asc" | "desc";
+    pageSize: number;
+  },
+): Cursor {
+  const indexValues: Record<string, unknown> = {};
+
+  for (const col of indexColumns) {
+    const value = record[col.name];
+    if (value === undefined) {
+      throw new Error(`Record is missing value for index column "${col.name}".`);
+    }
+    indexValues[col.name] = value;
+  }
+
+  return new Cursor({
+    indexName: metadata.indexName,
+    orderDirection: metadata.orderDirection,
+    pageSize: metadata.pageSize,
+    indexValues,
+  });
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const assertSerializableIndexValues = (values: Record<string, unknown>): void => {
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) {
+      throw new Error(`Cursor index value "${key}" is undefined.`);
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new Error(`Cursor index value "${key}" must be a finite number.`);
+    }
+    if (typeof value === "bigint") {
+      throw new Error(`Cursor index value "${key}" must not be a BigInt.`);
+    }
+    if (typeof value === "function" || typeof value === "symbol") {
+      throw new Error(`Cursor index value "${key}" is not JSON-serializable.`);
+    }
+  }
+};

package/src/query/cursor.test.ts

@@ -1,11 +1,12 @@
 import { describe, it, expect } from "vitest";
-import { decodeCursor, createCursorFromRecord, serializeCursorValues, Cursor } from "./cursor";
-import { column, idColumn, schema } from "../schema/create";
+
 import {
   BetterSQLite3DriverConfig,
   MySQL2DriverConfig,
   NodePostgresDriverConfig,
 } from "../adapters/generic-sql/driver-config";
+import { column, idColumn, schema } from "../schema/create";
+import { decodeCursor, createCursorFromRecord, serializeCursorValues, Cursor } from "./cursor";
 
 describe("Cursor utilities", () => {
   describe("Cursor class encode and decode", () => {

package/src/query/cursor.ts

@@ -1,8 +1,8 @@
+import type { DriverConfig } from "../adapters/generic-sql/driver-config";
+import type { SQLiteStorageMode } from "../adapters/generic-sql/sqlite-storage";
 import type { AnyColumn } from "../schema/create";
 import { createSQLSerializer } from "./serialize/create-sql-serializer";
 import { resolveFragnoIdValue } from "./value-encoding";
-import type { DriverConfig } from "../adapters/generic-sql/driver-config";
-import type { SQLiteStorageMode } from "../adapters/generic-sql/sqlite-storage";
 
 /**
  * Cursor object containing all information needed for pagination
@@ -211,7 +211,10 @@ export function createCursorFromRecord(
     if (value === undefined) {
       throw new Error(`Record is missing value for index column "${col.name}".`);
     }
-    indexValues[col.name] = value;
+    // Resolve FragnoId/FragnoReference to primitive values for cursor serialization.
+    const resolved = resolveFragnoIdValue(value, col);
+    // BigInt values are not JSON-serializable, so store them as strings.
+    indexValues[col.name] = typeof resolved === "bigint" ? resolved.toString() : resolved;
   }
 
   return new Cursor({
@@ -263,6 +266,15 @@ export function serializeCursorValues(
       missingColumns.push(col.name);
       continue;
     }
+
+    // If the cursor value is already a FragnoId/FragnoReference, resolve it directly
+    // to avoid deserializing non-JSON objects.
+    const resolvedDirect = resolveFragnoIdValue(value, col);
+    if (resolvedDirect !== value) {
+      serialized[col.name] = serializer.serialize(resolvedDirect, col);
+      continue;
+    }
+
     // First deserialize from JSON format to application format
     // (e.g., "2025-11-07T09:36:57.959Z" string → Date object)
     const deserialized = serializer.deserialize(value, col);

package/src/query/db-now.ts

@@ -1,6 +1,73 @@
-export type DbNow = { tag: "db-now" };
+export type DbInterval = { tag: "db-interval"; ms: number };
 
-export const dbNow = (): DbNow => ({ tag: "db-now" });
+export type DbIntervalInput =
+  | number
+  | {
+      ms?: number;
+      seconds?: number;
+      minutes?: number;
+      hours?: number;
+      days?: number;
+    };
+
+export type DbNow = {
+  tag: "db-now";
+  offsetMs?: number;
+  plus: (interval: DbInterval | DbIntervalInput) => DbNow;
+};
+
+const toIntervalMs = (input: DbInterval | DbIntervalInput): number => {
+  if (typeof input === "number") {
+    if (!Number.isFinite(input)) {
+      throw new Error("DB_INTERVAL_INVALID");
+    }
+    return input;
+  }
+
+  if (typeof input === "object" && input !== null && "tag" in input) {
+    const tagged = input as DbInterval;
+    if (tagged.tag === "db-interval") {
+      if (!Number.isFinite(tagged.ms)) {
+        throw new Error("DB_INTERVAL_INVALID");
+      }
+      return tagged.ms;
+    }
+    throw new Error("DB_INTERVAL_INVALID");
+  }
+
+  const interval = input as Exclude<DbIntervalInput, number>;
+  const totalMs =
+    (interval.ms ?? 0) +
+    (interval.seconds ?? 0) * 1000 +
+    (interval.minutes ?? 0) * 60_000 +
+    (interval.hours ?? 0) * 3_600_000 +
+    (interval.days ?? 0) * 86_400_000;
+
+  if (!Number.isFinite(totalMs)) {
+    throw new Error("DB_INTERVAL_INVALID");
+  }
+
+  return totalMs;
+};
+
+const createDbNow = (offsetMs = 0): DbNow => ({
+  tag: "db-now",
+  offsetMs,
+  plus: (interval) => createDbNow(offsetMs + toIntervalMs(interval)),
+});
+
+export const dbNow = (): DbNow => createDbNow(0);
 
 export const isDbNow = (value: unknown): value is DbNow =>
   typeof value === "object" && value !== null && (value as { tag?: string }).tag === "db-now";
+
+export const getDbNowOffsetMs = (value: DbNow): number =>
+  typeof value.offsetMs === "number" ? value.offsetMs : 0;
+
+export const dbInterval = (input: DbIntervalInput): DbInterval => ({
+  tag: "db-interval",
+  ms: toIntervalMs(input),
+});
+
+export const isDbInterval = (value: unknown): value is DbInterval =>
+  typeof value === "object" && value !== null && (value as { tag?: string }).tag === "db-interval";

package/src/query/orm/orm.ts

@@ -1,3 +1,5 @@
+import type { AnyColumn, AnyRelation, AnyTable } from "../../schema/create";
+import { buildCondition, type Condition } from "../condition-builder";
 import type {
   AnySelectClause,
   FindFirstOptions,
@@ -5,8 +7,6 @@ import type {
   JoinBuilder,
   OrderBy,
 } from "../simple-query-interface";
-import { buildCondition, type Condition } from "../condition-builder";
-import type { AnyColumn, AnyRelation, AnyTable } from "../../schema/create";
 
 export interface CompiledJoin {
   relation: AnyRelation;

package/src/query/query-type.test.ts

@@ -1,5 +1,7 @@
 import { describe, expectTypeOf, it } from "vitest";
+
 import { column, FragnoId, idColumn, referenceColumn, schema } from "../schema/create";
+import type { ConditionBuilder } from "./condition-builder";
 import type {
   SimpleQueryInterface,
   FindFirstOptions,
@@ -9,7 +11,6 @@ import type {
   SelectClause,
   TableToInsertValues,
 } from "./simple-query-interface";
-import type { ConditionBuilder } from "./condition-builder";
 
 describe("query type tests", () => {
   // Create test schema

package/src/query/serialize/create-sql-serializer.ts

@@ -1,9 +1,9 @@
 import type { DriverConfig } from "../../adapters/generic-sql/driver-config";
 import type { SQLiteStorageMode } from "../../adapters/generic-sql/sqlite-storage";
-import { SQLSerializer } from "./sql-serializer";
-import { SQLiteSerializer } from "./dialect/sqlite-serializer";
-import { PostgreSQLSerializer } from "./dialect/postgres-serializer";
 import { MySQLSerializer } from "./dialect/mysql-serializer";
+import { PostgreSQLSerializer } from "./dialect/postgres-serializer";
+import { SQLiteSerializer } from "./dialect/sqlite-serializer";
+import { SQLSerializer } from "./sql-serializer";
 
 // Re-export SQLSerializer for convenience
 export { SQLSerializer } from "./sql-serializer";

package/src/query/serialize/dialect/mysql-serializer.ts

@@ -1,6 +1,6 @@
+import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
 import type { AnyColumn } from "../../../schema/create";
 import { SQLSerializer } from "../sql-serializer";
-import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
 
 /**
  * MySQL-specific serializer.

package/src/query/serialize/dialect/postgres-serializer.ts

@@ -1,6 +1,6 @@
+import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
 import type { AnyColumn } from "../../../schema/create";
 import { SQLSerializer } from "../sql-serializer";
-import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
 
 /**
  * PostgreSQL-specific serializer.

package/src/query/serialize/dialect/sqlite-serializer.test.ts

@@ -1,8 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { SQLiteSerializer } from "./sqlite-serializer";
-import type { AnyColumn } from "../../../schema/create";
+
 import { BetterSQLite3DriverConfig } from "../../../adapters/generic-sql/driver-config";
 import { sqliteStoragePrisma } from "../../../adapters/generic-sql/sqlite-storage";
+import type { AnyColumn } from "../../../schema/create";
+import { SQLiteSerializer } from "./sqlite-serializer";
 
 describe("SQLiteSerializer", () => {
   const mockDriverConfig = new BetterSQLite3DriverConfig();
@@ -219,6 +220,11 @@ describe("SQLiteSerializer", () => {
       const date = prismaSerializer["deserializeDate"]("2024-03-10 12:34:56.789", timestampColumn);
       expect(date.toISOString()).toBe("2024-03-10T12:34:56.789Z");
     });
+
+    it("should parse numeric timestamp strings with decimals", () => {
+      const date = serializer["deserializeDate"]("1772709276409.0", timestampColumn);
+      expect(date.getTime()).toBe(1772709276409);
+    });
   });
 
   describe("deserializeInteger", () => {
@@ -297,5 +303,36 @@ describe("SQLiteSerializer", () => {
         /exceeds Number\.MAX_SAFE_INTEGER/,
       );
     });
+
+    it("should deserialize bigint from ArrayBuffer blob values", () => {
+      const expected = BigInt("9007199254740993");
+      const buffer = Buffer.alloc(8);
+      buffer.writeBigInt64BE(expected);
+      const arrayBuffer = buffer.buffer.slice(
+        buffer.byteOffset,
+        buffer.byteOffset + buffer.byteLength,
+      );
+
+      expect(serializer["deserializeBigInt"](arrayBuffer)).toBe(expected);
+    });
+
+    it("should deserialize bigint from Uint8Array blob values", () => {
+      const expected = BigInt("123456789012345678");
+      const buffer = Buffer.alloc(8);
+      buffer.writeBigInt64BE(expected);
+      const value = new Uint8Array(buffer);
+
+      expect(serializer["deserializeBigInt"](value)).toBe(expected);
+    });
+
+    it.each([
+      ["Buffer", Buffer.alloc(9)],
+      ["ArrayBuffer", new ArrayBuffer(9)],
+      ["Uint8Array", new Uint8Array(9)],
+    ])("should reject %s blob values when byte length is not exactly 8", (_, value) => {
+      expect(() => serializer["deserializeBigInt"](value)).toThrow(
+        /Cannot deserialize bigint from 9 bytes; expected 8\./,
+      );
+    });
   });
 });

package/src/query/serialize/dialect/sqlite-serializer.ts

@@ -1,8 +1,8 @@
-import type { AnyColumn } from "../../../schema/create";
-import { SQLSerializer } from "../sql-serializer";
 import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
 import type { SQLiteStorageMode } from "../../../adapters/generic-sql/sqlite-storage";
 import { sqliteStorageDefault } from "../../../adapters/generic-sql/sqlite-storage";
+import type { AnyColumn } from "../../../schema/create";
+import { SQLSerializer } from "../sql-serializer";
 
 const SQLITE_UTC_TIMESTAMP_REGEX =
   /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?$/;
@@ -28,6 +28,19 @@ function parseSQLiteUtcTimestamp(value: string): Date | null {
   );
 }
 
+function readBigInt64BEFromBytes(value: ArrayBuffer | ArrayBufferView): bigint {
+  if (value.byteLength !== 8) {
+    throw new Error(`Cannot deserialize bigint from ${value.byteLength} bytes; expected 8.`);
+  }
+
+  const view =
+    value instanceof ArrayBuffer
+      ? new DataView(value)
+      : new DataView(value.buffer, value.byteOffset, value.byteLength);
+
+  return view.getBigInt64(0, false);
+}
+
 /**
  * SQLite-specific serializer.
  *
@@ -89,7 +102,7 @@ export class SQLiteSerializer extends SQLSerializer {
       return value;
     }
     if (typeof value === "string") {
-      if (/^\d+$/.test(value)) {
+      if (/^\d+(?:\.\d+)?$/.test(value)) {
         const numericDate = new Date(Number(value));
         if (Number.isNaN(numericDate.getTime())) {
           throw new Error(`Cannot deserialize date from value: ${value}`);
@@ -139,8 +152,8 @@ export class SQLiteSerializer extends SQLSerializer {
     if (typeof value === "bigint") {
       return value;
     }
-    if (value instanceof Buffer) {
-      return value.readBigInt64BE(0);
+    if (value instanceof Buffer || value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+      return readBigInt64BEFromBytes(value);
     }
     if (typeof value === "string") {
       return BigInt(value);

package/src/query/simple-query-interface.ts

@@ -1,5 +1,7 @@
 import type { IdColumn, AnySchema, AnyTable, Relation, FragnoId } from "../schema/create";
+import type { Prettify } from "../util/types";
 import type { Condition, ConditionBuilder } from "./condition-builder";
+import type { CursorResult } from "./cursor";
 import type {
   TypedUnitOfWork,
   FindBuilder,
@@ -7,12 +9,11 @@ import type {
   DeleteBuilder,
   UpdateManyBuilder,
 } from "./unit-of-work/unit-of-work";
-import type { Prettify } from "../util/types";
-import type { CursorResult } from "./cursor";
+import type { IUnitOfWork } from "./unit-of-work/unit-of-work";
 
 export type AnySelectClause = SelectClause<AnyTable>;
 
-export type SelectClause<T extends AnyTable> = true | (keyof T["columns"])[];
+export type SelectClause<T extends AnyTable> = true | readonly (keyof T["columns"])[];
 
 export type RawColumnValues<T extends AnyTable> = {
   [K in keyof T["columns"] as string extends K ? never : K]: T["columns"][K]["$out"];
@@ -44,7 +45,7 @@ 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"])[]
+  : S extends readonly (keyof T["columns"])[]
     ? Prettify<{
         [K in S[number] as string extends K ? never : K]: K extends keyof T["columns"]
           ? T["columns"][K]["$out"]
@@ -264,4 +265,9 @@ export interface SimpleQueryInterface<TSchema extends AnySchema, TUOWConfig = vo
    * Create a Unit of Work bound to this query engine
    */
   createUnitOfWork: (name?: string, config?: TUOWConfig) => TypedUnitOfWork<TSchema, [], unknown>;
+
+  /**
+   * Create a base Unit of Work for cross-schema operations.
+   */
+  createBaseUnitOfWork: (name?: string, config?: TUOWConfig) => IUnitOfWork;
 }