@fragno-dev/db 0.2.2 → 0.3.0

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

@@ -161,7 +161,7 @@ export type RetrievalOperation<
   | {
       type: "find";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable;
       indexName: string;
       options: FindOptions<TTable, SelectClause<TTable>>;
@@ -171,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">;
@@ -187,7 +187,7 @@ export type MutationOperation<
   | {
       type: "update";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       id: FragnoId | string;
       checkVersion: boolean;
@@ -196,7 +196,7 @@ export type MutationOperation<
   | {
       type: "create";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       values: TableToInsertValues<TTable>;
       generatedExternalId: string;
@@ -204,7 +204,7 @@ export type MutationOperation<
   | {
       type: "delete";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       id: FragnoId | string;
       checkVersion: boolean;
@@ -212,7 +212,7 @@ export type MutationOperation<
   | {
       type: "check";
       schema: TSchema;
-      namespace?: string;
+      namespace?: string | null;
       table: TTable["name"];
       id: FragnoId;
     };
@@ -222,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).
    */
@@ -832,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);
       }
@@ -933,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;
@@ -951,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);
@@ -965,6 +1012,16 @@ export interface UnitOfWorkConfig {
   dryRun?: boolean;
   onQuery?: (query: unknown) => void;
   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";
 }
 
 /**
@@ -1207,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)[] = [];
@@ -1232,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,12 +1300,67 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     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 };
+  }
+
   /**
    * Register a schema with its namespace for cross-fragment operations.
    * 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);
   }
 
@@ -1426,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;
       }
@@ -1450,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;
       }
@@ -1462,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.
+        }
+      }
     }
   }
 
@@ -1484,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);
         }
@@ -1500,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,
@@ -1516,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();
 
@@ -1524,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.
+        }
+      }
     }
   }
 
@@ -1623,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);
       }
     }
@@ -1648,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;
@@ -1746,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);
   }
 
@@ -1989,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
@@ -2007,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;
@@ -2015,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

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

@@ -7,10 +7,15 @@ import {
   schema,
   referenceColumn,
 } from "../schema/create";
-import { resolveFragnoIdValue, encodeValues, ReferenceSubquery } from "./value-encoding";
+import {
+  resolveFragnoIdValue,
+  encodeValues,
+  encodeValuesWithDbDefaults,
+  ReferenceSubquery,
+} from "./value-encoding";
 
 describe("encodeValues", () => {
-  const testSchema = schema((s) => {
+  const testSchema = schema("test", (s) => {
     return s
       .addTable("users", (t) => {
         return t
@@ -128,6 +133,84 @@ describe("encodeValues", () => {
 
       expect(result["viewCount"]).toBe(100);
     });
+
+    it("should use injected runtime defaults when provided", () => {
+      const testDate = new Date("2024-02-01T00:00:00Z");
+      const testSchemaWithDefaults = schema("testschemawithdefaults", (s) =>
+        s.addTable("entries", (t) =>
+          t.addColumn("id", idColumn()).addColumn(
+            "createdAt",
+            column("timestamp").defaultTo$((b) => b.now()),
+          ),
+        ),
+      );
+      const entriesTable = testSchemaWithDefaults.tables.entries;
+
+      const result = encodeValues({}, entriesTable, true, {
+        createId: () => "entry_1",
+        now: () => testDate,
+      });
+
+      expect(result["id"]).toBe("entry_1");
+      expect(result["createdAt"]).toBe(testDate);
+    });
+  });
+
+  describe("database defaults in memory", () => {
+    it("should apply static and dbSpecial defaults when requested", () => {
+      const testDate = new Date("2024-03-01T00:00:00Z");
+      const testSchemaWithDbDefaults = schema("testschemawithdbdefaults", (s) =>
+        s.addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("title", column("string"))
+            .addColumn("status", column("string").defaultTo("draft"))
+            .addColumn(
+              "createdAt",
+              column("timestamp").defaultTo((b) => b.now()),
+            ),
+        ),
+      );
+      const postsTable = testSchemaWithDbDefaults.tables.posts;
+
+      const result = encodeValuesWithDbDefaults({ title: "Hello" }, postsTable, {
+        createId: () => "post_1",
+        now: () => testDate,
+      });
+
+      expect(result).toEqual({
+        id: "post_1",
+        title: "Hello",
+        _version: 0,
+        status: "draft",
+        createdAt: testDate,
+      });
+    });
+
+    it("should not override explicit values when applying db defaults", () => {
+      const testSchemaWithDbDefaults = schema("testschemawithdbdefaults", (s) =>
+        s.addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("title", column("string"))
+            .addColumn("status", column("string").defaultTo("draft")),
+        ),
+      );
+      const postsTable = testSchemaWithDbDefaults.tables.posts;
+
+      const result = encodeValuesWithDbDefaults(
+        { title: "Hello", status: "published" },
+        postsTable,
+        { createId: () => "post_2" },
+      );
+
+      expect(result).toEqual({
+        id: "post_2",
+        title: "Hello",
+        _version: 0,
+        status: "published",
+      });
+    });
   });
 
   describe("complete record encoding", () => {