@fragno-dev/db 0.2.1 → 0.3.0

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

@@ -7,6 +7,7 @@ import type {
   Relation,
 } from "../../schema/create";
 import { FragnoId } from "../../schema/create";
+import { generateId } from "../../schema/generate-id";
 import type { Condition, ConditionBuilder } from "../condition-builder";
 import type {
   SelectClause,
@@ -160,7 +161,7 @@ export type RetrievalOperation<
   | {
       type: "find";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable;
       indexName: string;
       options: FindOptions<TTable, SelectClause<TTable>>;
@@ -170,7 +171,7 @@ export type RetrievalOperation<
   | {
       type: "count";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable;
       indexName: string;
       options: Pick<FindOptions<TTable>, "where" | "useIndex">;
@@ -186,7 +187,7 @@ export type MutationOperation<
   | {
       type: "update";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       id: FragnoId | string;
       checkVersion: boolean;
@@ -195,7 +196,7 @@ export type MutationOperation<
   | {
       type: "create";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       values: TableToInsertValues<TTable>;
       generatedExternalId: string;
@@ -203,7 +204,7 @@ export type MutationOperation<
   | {
       type: "delete";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       id: FragnoId | string;
       checkVersion: boolean;
@@ -211,7 +212,7 @@ export type MutationOperation<
   | {
       type: "check";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       id: FragnoId;
     };
@@ -221,6 +222,14 @@ export type MutationOperation<
  */
 export interface CompiledMutation<TOutput> {
   query: TOutput;
+  /**
+   * Original mutation operation for execution metadata (e.g., outbox payloads).
+   */
+  operation?: MutationOperation<AnySchema>;
+  /**
+   * Idempotency key for the Unit of Work that produced this mutation.
+   */
+  uowId?: string;
   /**
    * The type of mutation operation (create, update, delete, or check).
    */
@@ -262,13 +271,9 @@ export type MutationResult =
  * Executor interface for Unit of Work operations
  */
 export interface UOWExecutor<TOutput, TRawResult = unknown> {
-  /**
-   * Execute the retrieval phase - all queries run in a single transaction for snapshot isolation
-   */
   executeRetrievalPhase(retrievalBatch: TOutput[]): Promise<TRawResult[]>;
 
   /**
-   * Execute the mutation phase - all queries run in a transaction with version checks
    * Returns success status indicating if mutations completed without conflicts,
    * and internal IDs for create operations (null if database doesn't support RETURNING)
    */
@@ -835,7 +840,7 @@ export function buildJoinIndexed<TTable extends AnyTable, TJoinOut>(
 
     builder[name] = (builderFn?: (b: JoinFindBuilder<AnyTable>) => JoinFindBuilder<AnyTable>) => {
       // Create join builder for this relation's table
-      const joinBuilder = new JoinFindBuilder(relation.table.ormName, relation.table);
+      const joinBuilder = new JoinFindBuilder(relation.table.name, relation.table);
       if (builderFn) {
         builderFn(joinBuilder);
       }
@@ -903,7 +908,7 @@ export interface IUnitOfWork {
   // Getters (schema-agnostic)
   readonly state: UOWState;
   readonly name: string | undefined;
-  readonly nonce: string;
+  readonly idempotencyKey: string;
   readonly retrievalPhase: Promise<unknown[]>;
   readonly mutationPhase: Promise<void>;
 
@@ -936,7 +941,7 @@ export interface IUnitOfWork {
   ): TypedUnitOfWork<TOtherSchema, [], any, TOtherHooks>;
 
   // Schema registration (for cross-fragment operations like hooks)
-  registerSchema(schema: AnySchema, namespace: string): void;
+  registerSchema(schema: AnySchema, namespace: string | null): void;
 
   // Hook triggering (schema-agnostic, string-based hook names)
   triggerHook(hookName: string, payload: unknown, options?: TriggerHookOptions): void;
@@ -954,11 +959,50 @@ export interface IUnitOfWork {
 export interface IUnitOfWorkRestricted
   extends Omit<IUnitOfWork, "executeRetrieve" | "executeMutations"> {}
 
+export type UOWInstrumentationPhase =
+  | "beforeRetrieve"
+  | "afterRetrieve"
+  | "beforeMutate"
+  | "afterMutate";
+
+export type UOWInstrumentationInjection =
+  | { type: "conflict"; reason?: string }
+  | { type: "error"; error: Error };
+
+export type UOWInstrumentationContext = {
+  phase: UOWInstrumentationPhase;
+  uowName?: string;
+  idempotencyKey: string;
+  retrievalOpsCount: number;
+  mutationOpsCount: number;
+  uow: IUnitOfWork;
+};
+
+export type UOWInstrumentation = {
+  beforeRetrieve?: (
+    ctx: UOWInstrumentationContext,
+  ) => void | Promise<void> | UOWInstrumentationInjection;
+  afterRetrieve?: (
+    ctx: UOWInstrumentationContext,
+  ) => void | Promise<void> | UOWInstrumentationInjection;
+  beforeMutate?: (
+    ctx: UOWInstrumentationContext,
+  ) => void | Promise<void> | UOWInstrumentationInjection;
+  afterMutate?: (
+    ctx: UOWInstrumentationContext,
+  ) => void | Promise<void> | UOWInstrumentationInjection;
+};
+
+export type UOWInstrumentationFinalizer = {
+  afterRetrieve?: (ctx: UOWInstrumentationContext) => void | Promise<void>;
+  afterMutate?: (ctx: UOWInstrumentationContext) => void | Promise<void>;
+};
+
 export function createUnitOfWork(
   compiler: UOWCompiler<unknown>,
   executor: UOWExecutor<unknown, unknown>,
   decoder: UOWDecoder<unknown>,
-  schemaNamespaceMap?: WeakMap<AnySchema, string>,
+  schemaNamespaceMap?: WeakMap<AnySchema, string | null>,
   name?: string,
 ): UnitOfWork {
   return new UnitOfWork(compiler, executor, decoder, name, undefined, schemaNamespaceMap);
@@ -967,7 +1011,17 @@ export function createUnitOfWork(
 export interface UnitOfWorkConfig {
   dryRun?: boolean;
   onQuery?: (query: unknown) => void;
-  nonce?: string;
+  idempotencyKey?: string;
+  instrumentation?: UOWInstrumentation;
+  instrumentationFinalizer?: UOWInstrumentationFinalizer;
+}
+
+function isUowInstrumentationInjection(value: unknown): value is UOWInstrumentationInjection {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const injection = value as UOWInstrumentationInjection;
+  return injection.type === "conflict" || injection.type === "error";
 }
 
 /**
@@ -1199,7 +1253,7 @@ class UOWChildCoordinator<TRawInput> {
 export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
   #name?: string;
   #config?: UnitOfWorkConfig;
-  #nonce: string;
+  #idempotencyKey: string;
 
   #state: UOWState = "building-retrieval";
 
@@ -1210,7 +1264,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
   #compiler: UOWCompiler<unknown>;
   #executor: UOWExecutor<unknown, TRawInput>;
   #decoder: UOWDecoder<TRawInput>;
-  #schemaNamespaceMap: WeakMap<AnySchema, string>;
+  #schemaNamespaceMap: WeakMap<AnySchema, string | null>;
 
   #retrievalResults?: unknown[];
   #createdInternalIds: (bigint | null)[] = [];
@@ -1235,7 +1289,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     decoder: UOWDecoder<TRawInput>,
     name?: string,
     config?: UnitOfWorkConfig,
-    schemaNamespaceMap?: WeakMap<AnySchema, string>,
+    schemaNamespaceMap?: WeakMap<AnySchema, string | null>,
   ) {
     this.#compiler = compiler;
     this.#executor = executor;
@@ -1243,7 +1297,62 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     this.#schemaNamespaceMap = schemaNamespaceMap ?? new WeakMap();
     this.#name = name;
     this.#config = config;
-    this.#nonce = config?.nonce ?? crypto.randomUUID();
+    this.#idempotencyKey = config?.idempotencyKey ?? crypto.randomUUID();
+  }
+
+  #createInstrumentationContext(phase: UOWInstrumentationPhase): UOWInstrumentationContext {
+    return {
+      phase,
+      uowName: this.#name,
+      idempotencyKey: this.#idempotencyKey,
+      retrievalOpsCount: this.#retrievalOps.length,
+      mutationOpsCount: this.#mutationOps.length,
+      uow: this,
+    };
+  }
+
+  async #runInstrumentation(
+    phase: UOWInstrumentationPhase,
+  ): Promise<UOWInstrumentationInjection | null> {
+    const hook = this.#config?.instrumentation?.[phase];
+    if (!hook) {
+      return null;
+    }
+
+    const result = await hook(this.#createInstrumentationContext(phase));
+    if (isUowInstrumentationInjection(result)) {
+      return result;
+    }
+
+    return null;
+  }
+
+  async #runInstrumentationFinalizer(phase: "afterRetrieve" | "afterMutate"): Promise<void> {
+    const hook = this.#config?.instrumentationFinalizer?.[phase];
+    if (!hook) {
+      return;
+    }
+
+    await hook(this.#createInstrumentationContext(phase));
+  }
+
+  #handleRetrieveInjection(injection: UOWInstrumentationInjection): never {
+    if (injection.type === "error") {
+      throw injection.error;
+    }
+
+    throw new Error(injection.reason ?? "Injected conflict");
+  }
+
+  #handleMutationInjection(injection: UOWInstrumentationInjection): { success: false } | never {
+    if (injection.type === "error") {
+      throw injection.error;
+    }
+
+    this.#state = "executed";
+    this.#createdInternalIds.length = 0;
+    this.#mutationPhaseDeferred.resolve();
+    return { success: false };
   }
 
   /**
@@ -1251,7 +1360,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
    * This is used for internal fragments like hooks that need to create
    * records in a different schema during the same transaction.
    */
-  registerSchema(schema: AnySchema, namespace: string): void {
+  registerSchema(schema: AnySchema, namespace: string | null): void {
     this.#schemaNamespaceMap.set(schema, namespace);
   }
 
@@ -1293,7 +1402,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
       this.#executor,
       this.#decoder,
       this.#name,
-      { ...this.#config, nonce: this.#nonce },
+      { ...this.#config, idempotencyKey: this.#idempotencyKey },
       this.#schemaNamespaceMap,
     );
     child.#coordinator.setAsRestricted(this, this.#coordinator);
@@ -1394,8 +1503,8 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     return this.#name;
   }
 
-  get nonce(): string {
-    return this.#nonce;
+  get idempotencyKey(): string {
+    return this.#idempotencyKey;
   }
 
   /**
@@ -1429,13 +1538,25 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
       );
     }
 
+    let afterRan = false;
+    let failed = false;
     try {
       // Wait for all children to signal readiness
       await this.#coordinator.retrievalReadinessPromise;
 
+      const beforeInjection = await this.#runInstrumentation("beforeRetrieve");
+      if (beforeInjection) {
+        return this.#handleRetrieveInjection(beforeInjection);
+      }
+
       if (this.#retrievalOps.length === 0) {
         this.#state = "building-mutation";
         const emptyResults: unknown[] = [];
+        afterRan = true;
+        const afterInjection = await this.#runInstrumentation("afterRetrieve");
+        if (afterInjection) {
+          return this.#handleRetrieveInjection(afterInjection);
+        }
         this.#retrievalPhaseDeferred.resolve(emptyResults);
         return emptyResults;
       }
@@ -1453,6 +1574,11 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
       if (this.#config?.dryRun) {
         this.#state = "executed";
         const emptyResults: unknown[] = [];
+        afterRan = true;
+        const afterInjection = await this.#runInstrumentation("afterRetrieve");
+        if (afterInjection) {
+          return this.#handleRetrieveInjection(afterInjection);
+        }
         this.#retrievalPhaseDeferred.resolve(emptyResults);
         return emptyResults;
       }
@@ -1465,12 +1591,33 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
       this.#retrievalResults = results;
       this.#state = "building-mutation";
 
+      afterRan = true;
+      const afterInjection = await this.#runInstrumentation("afterRetrieve");
+      if (afterInjection) {
+        return this.#handleRetrieveInjection(afterInjection);
+      }
+
       this.#retrievalPhaseDeferred.resolve(this.#retrievalResults);
 
       return this.#retrievalResults;
     } catch (error) {
       this.#retrievalError = error instanceof Error ? error : new Error(String(error));
+      failed = true;
       throw error;
+    } finally {
+      try {
+        await this.#runInstrumentationFinalizer("afterRetrieve");
+      } catch {
+        // Ignore finalizer errors when unwinding failures.
+      }
+
+      if (!afterRan && failed) {
+        try {
+          await this.#runInstrumentation("afterRetrieve");
+        } catch {
+          // Ignore after-retrieve hook errors when unwinding failures.
+        }
+      }
     }
   }
 
@@ -1487,15 +1634,23 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
       throw new Error(`Cannot execute mutations from state ${this.#state}.`);
     }
 
+    let afterRan = false;
+    let failed = false;
     try {
       // Wait for all children to signal readiness
       await this.#coordinator.mutationReadinessPromise;
 
+      const beforeInjection = await this.#runInstrumentation("beforeMutate");
+      if (beforeInjection) {
+        return this.#handleMutationInjection(beforeInjection);
+      }
+
       // Compile mutation operations using single compiler
       const mutationBatch: CompiledMutation<unknown>[] = [];
       for (const op of this.#mutationOps) {
         const compiled = this.#compiler.compileMutationOperation(op);
         if (compiled !== null) {
+          compiled.uowId = this.#idempotencyKey;
           this.#config?.onQuery?.(compiled);
           mutationBatch.push(compiled);
         }
@@ -1503,6 +1658,11 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
 
       if (this.#config?.dryRun) {
         this.#state = "executed";
+        afterRan = true;
+        const afterInjection = await this.#runInstrumentation("afterMutate");
+        if (afterInjection) {
+          return this.#handleMutationInjection(afterInjection);
+        }
         this.#mutationPhaseDeferred.resolve();
         return {
           success: true,
@@ -1519,6 +1679,12 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
         this.#createdInternalIds.push(...result.createdInternalIds);
       }
 
+      afterRan = true;
+      const afterInjection = await this.#runInstrumentation("afterMutate");
+      if (afterInjection) {
+        return this.#handleMutationInjection(afterInjection);
+      }
+
       // Resolve the mutation phase promise to unblock waiting service methods
       this.#mutationPhaseDeferred.resolve();
 
@@ -1527,7 +1693,22 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
       };
     } catch (error) {
       this.#mutationError = error instanceof Error ? error : new Error(String(error));
+      failed = true;
       throw error;
+    } finally {
+      try {
+        await this.#runInstrumentationFinalizer("afterMutate");
+      } catch {
+        // Ignore finalizer errors when unwinding failures.
+      }
+
+      if (!afterRan && failed) {
+        try {
+          await this.#runInstrumentation("afterMutate");
+        } catch {
+          // Ignore after-mutate hook errors when unwinding failures.
+        }
+      }
     }
   }
 
@@ -1626,6 +1807,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     for (const op of this.#mutationOps) {
       const compiled = compiler.compileMutationOperation(op);
       if (compiled !== null) {
+        compiled.uowId = this.#idempotencyKey;
         mutationBatch.push(compiled);
       }
     }
@@ -1651,12 +1833,12 @@ export class TypedUnitOfWork<
 > implements IUnitOfWork
 {
   #schema: TSchema;
-  #namespace?: string;
+  #namespace?: string | null;
   #uow: UnitOfWork<TRawInput>;
   #operationIndices: number[] = [];
   #cachedRetrievalPhase?: Promise<TRetrievalResults>;
 
-  constructor(schema: TSchema, namespace: string | undefined, uow: UnitOfWork<TRawInput>) {
+  constructor(schema: TSchema, namespace: string | null | undefined, uow: UnitOfWork<TRawInput>) {
     this.#schema = schema;
     this.#namespace = namespace;
     this.#uow = uow;
@@ -1674,8 +1856,8 @@ export class TypedUnitOfWork<
     return this.#uow.name;
   }
 
-  get nonce(): string {
-    return this.#uow.nonce;
+  get idempotencyKey(): string {
+    return this.#uow.idempotencyKey;
   }
 
   get state() {
@@ -1749,7 +1931,7 @@ export class TypedUnitOfWork<
     return this.#uow.forSchema<TOtherSchema, TOtherHooks>(schema, hooks);
   }
 
-  registerSchema(schema: AnySchema, namespace: string): void {
+  registerSchema(schema: AnySchema, namespace: string | null): void {
     this.#uow.registerSchema(schema, namespace);
   }
 
@@ -1962,6 +2144,22 @@ export class TypedUnitOfWork<
     return this as any;
   }
 
+  /**
+   * Generate a new ID for a table without creating a record.
+   * This is useful when you need to reference an ID before actually creating the record,
+   * or when you need to pass the ID to external services.
+   *
+   * @example
+   * ```ts
+   * const userId = uow.generateId("users");
+   * // Use userId in related records or pass to external services
+   * uow.create("users", { id: userId, name: "John" });
+   * ```
+   */
+  generateId<TableName extends keyof TSchema["tables"] & string>(tableName: TableName): FragnoId {
+    return generateId(this.#schema, tableName);
+  }
+
   create<TableName extends keyof TSchema["tables"] & string>(
     tableName: TableName,
     values: TableToInsertValues<TSchema["tables"][TableName]>,
@@ -1976,7 +2174,7 @@ export class TypedUnitOfWork<
     let updatedValues = values;
 
     // Check if ID value is provided in values
-    const providedIdValue = (values as Record<string, unknown>)[idColumn.ormName];
+    const providedIdValue = (values as Record<string, unknown>)[idColumn.name];
 
     if (providedIdValue !== undefined) {
       // Extract string from FragnoId or use string directly
@@ -1994,7 +2192,7 @@ export class TypedUnitOfWork<
       const generated = idColumn.generateDefaultValue();
       if (generated === undefined) {
         throw new Error(
-          `No ID value provided and ID column ${idColumn.ormName} has no default generator`,
+          `No ID value provided and ID column ${idColumn.name} has no default generator`,
         );
       }
       externalId = generated as string;
@@ -2002,7 +2200,7 @@ export class TypedUnitOfWork<
       // Add the generated ID to values so it's used in the insert
       updatedValues = {
         ...values,
-        [idColumn.ormName]: externalId,
+        [idColumn.name]: externalId,
       } as TableToInsertValues<TSchema["tables"][TableName]>;
     }
 

package/src/query/value-decoding.test.ts

@@ -4,11 +4,12 @@ import { decodeResult } from "./value-decoding";
 import {
   SQLocalDriverConfig,
   NodePostgresDriverConfig,
+  PGLiteDriverConfig,
   MySQL2DriverConfig,
 } from "../adapters/generic-sql/driver-config";
 
 describe("decodeResult", () => {
-  const testSchema = schema((s) => {
+  const testSchema = schema("test", (s) => {
     return s
       .addTable("users", (t) => {
         return t
@@ -40,6 +41,7 @@ describe("decodeResult", () => {
 
   const sqliteConfig = new SQLocalDriverConfig();
   const postgresqlConfig = new NodePostgresDriverConfig();
+  const pgliteConfig = new PGLiteDriverConfig();
   const mysqlConfig = new MySQL2DriverConfig();
 
   describe("basic decoding", () => {
@@ -105,6 +107,15 @@ describe("decodeResult", () => {
 
       expect(result["createdAt"]).toBe(date);
     });
+
+    it("should normalize Date values from pglite timestamp parsing", () => {
+      const localDate = new Date("2024-01-15T10:30:00");
+      const expected = new Date(localDate.getTime() - localDate.getTimezoneOffset() * 60_000);
+      const result = decodeResult({ createdAt: localDate }, usersTable, pgliteConfig);
+
+      assert.instanceOf(result["createdAt"], Date);
+      expect((result["createdAt"] as Date).toISOString()).toBe(expected.toISOString());
+    });
   });
 
   describe("nullable columns", () => {
@@ -206,7 +217,7 @@ describe("decodeResult", () => {
     });
 
     it("should handle multiple relations in same result", () => {
-      const schemaWithMultipleRelations = schema((s) => {
+      const schemaWithMultipleRelations = schema("schemawithmultiplerelations", (s) => {
         return s
           .addTable("users", (t) => {
             return t.addColumn("id", idColumn()).addColumn("name", column("string"));

package/src/query/value-decoding.ts

@@ -2,6 +2,8 @@ import type { AnyTable } from "../schema/create";
 import { createSQLSerializer } from "./serialize/create-sql-serializer";
 import { FragnoId, FragnoReference } from "../schema/create";
 import type { DriverConfig } from "../adapters/generic-sql/driver-config";
+import type { SQLiteStorageMode } from "../adapters/generic-sql/sqlite-storage";
+import type { NamingResolver } from "../naming/sql-naming";
 
 /**
  * Decodes a database result record to application format.
@@ -15,6 +17,7 @@ import type { DriverConfig } from "../adapters/generic-sql/driver-config";
  * @param result - The raw database result record
  * @param table - The table schema definition containing column and relation information
  * @param driverConfig - The driver configuration containing database type information
+ * @param sqliteStorageMode - Optional SQLite storage mode override
  * @returns A record in application format with deserialized values
  *
  * @example
@@ -31,11 +34,14 @@ export function decodeResult(
   result: Record<string, unknown>,
   table: AnyTable,
   driverConfig: DriverConfig,
+  sqliteStorageMode?: SQLiteStorageMode,
+  resolver?: NamingResolver,
 ): Record<string, unknown> {
-  const serializer = createSQLSerializer(driverConfig);
+  const serializer = createSQLSerializer(driverConfig, sqliteStorageMode);
   const output: Record<string, unknown> = {};
   // First pass: collect all column values
   const columnValues: Record<string, unknown> = {};
+  const columnMap = resolver ? resolver.getColumnNameMap(table) : undefined;
 
   // Collect all relation data (including nested) keyed by relation name
   const relationData: Record<string, Record<string, unknown>> = {};
@@ -46,13 +52,14 @@ export function decodeResult(
 
     // Direct column (no colon)
     if (colonIndex === -1) {
-      const col = table.columns[k];
+      const logicalName = columnMap?.[k] ?? k;
+      const col = table.columns[logicalName];
       if (!col) {
         continue;
       }
 
       // Store all column values (including hidden ones for FragnoId creation)
-      columnValues[k] = serializer.deserialize(value, col);
+      columnValues[logicalName] = serializer.deserialize(value, col);
       continue;
     }
 
@@ -78,7 +85,13 @@ export function decodeResult(
     }
 
     // Recursively decode the relation data
-    output[relationName] = decodeResult(relationData[relationName], relation.table, driverConfig);
+    output[relationName] = decodeResult(
+      relationData[relationName],
+      relation.table,
+      driverConfig,
+      sqliteStorageMode,
+      resolver,
+    );
   }
 
   // Second pass: create output with FragnoId objects where appropriate