@fragno-dev/db 0.3.0 → 0.4.1

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

@@ -1,5 +1,10 @@
 import { describe, it, expect } from "vitest";
+
+import { BetterSQLite3DriverConfig } from "../../adapters/generic-sql/driver-config";
+import { GenericSQLUOWOperationCompiler } from "../../adapters/generic-sql/query/generic-sql-uow-operation-compiler";
+import { createUOWCompilerFromOperationCompiler } from "../../adapters/shared/uow-operation-compiler";
 import { schema, idColumn, type FragnoId, referenceColumn } from "../../schema/create";
+import type { CompiledQuery } from "../../sql-driver/sql-driver";
 import {
   type UOWCompiler,
   type UOWDecoder,
@@ -7,10 +12,6 @@ import {
   type CompiledMutation,
   type UOWExecutor,
 } from "./unit-of-work";
-import { GenericSQLUOWOperationCompiler } from "../../adapters/generic-sql/query/generic-sql-uow-operation-compiler";
-import { BetterSQLite3DriverConfig } from "../../adapters/generic-sql/driver-config";
-import { createUOWCompilerFromOperationCompiler } from "../../adapters/shared/uow-operation-compiler";
-import type { CompiledQuery } from "../../sql-driver/sql-driver";
 
 // Create compiler using actual implementation
 function createCompiler(): UOWCompiler<CompiledQuery> {

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

@@ -1,7 +1,8 @@
 import { describe, expectTypeOf, it } from "vitest";
+
 import { column, idColumn, referenceColumn, schema } from "../../schema/create";
-import { JoinFindBuilder, UnitOfWork } from "./unit-of-work";
 import type { FragnoId, FragnoReference } from "../../schema/create";
+import { JoinFindBuilder, UnitOfWork } from "./unit-of-work";
 
 type Prettify<T> = {
   [K in keyof T]: T[K];
@@ -138,7 +139,6 @@ describe("UnitOfWork type tests", () => {
     const [_userResult] = await uow1.executeRetrieve();
     type UserResult = RecursivePrettify<(typeof _userResult)[number]>;
 
-    // @ts-expect-error assert type
     expectTypeOf<UserResult>().toEqualTypeOf<{
       id: FragnoId;
       name: string;
@@ -174,13 +174,8 @@ describe("UnitOfWork type tests", () => {
     type _JoinOutInviter = Prettify<_JoinOut["inviter"]>;
     //     ^?
 
-    // FIXME: There should not be a `{}` in the type
     expectTypeOf<_JoinOutInviter>().toEqualTypeOf<{
-      id: FragnoId;
       name: string;
-      email: string;
-      age: number | null;
-      invitedBy: FragnoReference | null;
     } | null>();
   });
 
@@ -194,14 +189,49 @@ describe("UnitOfWork type tests", () => {
     type _JoinOutPosts = Prettify<_JoinOut["posts"]>;
     //     ^?
 
-    // FIXME: There should not be a `{}` in the array
     expectTypeOf<_JoinOutPosts>().toEqualTypeOf<
       {
-        id: FragnoId;
         title: string;
-        content: string;
-        userId: FragnoReference;
       }[]
     >();
   });
+
+  it("preserves nested select narrowing in join builder", () => {
+    const builder = new JoinFindBuilder("users", testSchema.tables.users);
+
+    const _builderOut = builder.join((jb) =>
+      jb.posts((pb) => pb.select(["title"]).join((jb2) => jb2.author((ab) => ab.select(["name"])))),
+    );
+
+    type JoinOut = InferJoinOutPrettify<typeof _builderOut>;
+    type Post = Prettify<JoinOut["posts"][number]>;
+    type PostTitle = Post["title"];
+    type Author = Prettify<NonNullable<Post["author"]>>;
+
+    expectTypeOf<PostTitle>().toEqualTypeOf<string>();
+    expectTypeOf<Author>().toEqualTypeOf<{ name: string }>();
+  });
+
+  it("preserves nested select narrowing via UOW find", async () => {
+    const uow = createTestUOW();
+
+    const uow1 = uow.find("users", (b) =>
+      b
+        .whereIndex("primary")
+        .join((jb) =>
+          jb.posts((pb) =>
+            pb.select(["title"]).join((jb2) => jb2.author((ab) => ab.select(["name"]))),
+          ),
+        ),
+    );
+
+    const [_userResult] = await uow1.executeRetrieve();
+    type User = RecursivePrettify<(typeof _userResult)[number]>;
+    type Post = Prettify<User["posts"][number]>;
+    type PostTitle = Post["title"];
+    type Author = Prettify<NonNullable<Post["author"]>>;
+
+    expectTypeOf<PostTitle>().toEqualTypeOf<string>();
+    expectTypeOf<Author>().toEqualTypeOf<{ name: string }>();
+  });
 });

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

@@ -1,5 +1,8 @@
 import { describe, it, expect, assert, expectTypeOf } from "vitest";
+
 import { column, schema, idColumn, FragnoId } from "../../schema/create";
+import { createIndexedBuilder } from "../condition-builder";
+import type { SimpleQueryInterface } from "../simple-query-interface";
 import {
   type UOWCompiler,
   type UOWDecoder,
@@ -8,8 +11,6 @@ import {
   type InferIdColumnName,
   type IndexColumns,
 } from "./unit-of-work";
-import { createIndexedBuilder } from "../condition-builder";
-import type { SimpleQueryInterface } from "../simple-query-interface";
 
 // Mock compiler and executor for testing
 function createMockCompiler(): UOWCompiler<unknown> {
@@ -1909,3 +1910,28 @@ describe("findFirst convenience method", () => {
     expect(ops[0]?.indexName).toBe("_primary");
   });
 });
+
+describe("triggerHook namespace resolution", () => {
+  it("should fall back to schema name when namespace is null", () => {
+    const hooksSchema = schema("hooks_test", (s) =>
+      s.addTable("events", (t) => t.addColumn("id", idColumn())),
+    );
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+    uow.registerSchema(hooksSchema, null);
+
+    const hooks = {
+      onTest: (_payload: { value: string }) => {},
+    };
+
+    const typedUow = uow.forSchema(hooksSchema, hooks);
+    typedUow.triggerHook("onTest", { value: "ok" });
+
+    const triggeredHooks = uow.getTriggeredHooks();
+    expect(triggeredHooks).toHaveLength(1);
+    expect(triggeredHooks[0]).toMatchObject({
+      namespace: hooksSchema.name,
+      hookName: "onTest",
+      payload: { value: "ok" },
+    });
+  });
+});

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

@@ -1,3 +1,4 @@
+import type { TriggeredHook, TriggerHookOptions, HooksMap, HookPayload } from "../../hooks/hooks";
 import type {
   AnySchema,
   AnyTable,
@@ -8,7 +9,13 @@ import type {
 } from "../../schema/create";
 import { FragnoId } from "../../schema/create";
 import { generateId } from "../../schema/generate-id";
+import type { Prettify } from "../../util/types";
 import type { Condition, ConditionBuilder } from "../condition-builder";
+import { buildCondition } from "../condition-builder";
+import type { CursorResult } from "../cursor";
+import { Cursor } from "../cursor";
+import { dbInterval, dbNow, type DbInterval, type DbIntervalInput, type DbNow } from "../db-now";
+import type { CompiledJoin } from "../orm/orm";
 import type {
   SelectClause,
   TableToInsertValues,
@@ -17,12 +24,6 @@ import type {
   ExtractSelect,
   ExtractJoinOut,
 } from "../simple-query-interface";
-import { buildCondition } from "../condition-builder";
-import type { CompiledJoin } from "../orm/orm";
-import type { CursorResult } from "../cursor";
-import { Cursor } from "../cursor";
-import type { Prettify } from "../../util/types";
-import type { TriggeredHook, TriggerHookOptions, HooksMap, HookPayload } from "../../hooks/hooks";
 
 /**
  * Builder for updateMany operations that supports both whereIndex and set chaining
@@ -33,6 +34,8 @@ export interface UpdateManyBuilder<TTable extends AnyTable> {
     condition?: (eb: IndexSpecificConditionBuilder<TTable, TIndexName>) => Condition | boolean,
   ): this;
   set(values: TableToUpdateValues<TTable>): this;
+  now(): DbNow;
+  interval(input: DbIntervalInput): DbInterval;
 }
 
 /**
@@ -42,6 +45,12 @@ export type IndexColumns<TIndex extends Index> = TIndex["columnNames"][number];
 
 type RemoveEmptyObject<T> = T extends object ? (keyof T extends never ? never : T) : never;
 
+type ExtractJoinBuilderSelect<T> =
+  T extends JoinFindBuilder<infer _Table, infer TSelect, infer _JoinOut> ? TSelect : true;
+
+type ExtractJoinBuilderOut<T> =
+  T extends JoinFindBuilder<infer _Table, infer _Select, infer TJoinOut> ? TJoinOut : {};
+
 /**
  * Extract all indexed column names from a table's indexes
  */
@@ -167,6 +176,7 @@ export type RetrievalOperation<
       options: FindOptions<TTable, SelectClause<TTable>>;
       withCursor?: boolean;
       withSingleResult?: boolean;
+      readTracking?: boolean;
     }
   | {
       type: "count";
@@ -366,6 +376,7 @@ export class FindBuilder<
           `Use either select() or selectCount(), not both.`,
       );
     }
+    // prettier-ignore
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (this as any).#selectClause = columns;
     return this as unknown as FindBuilder<TTable, TNewSelect, TJoinOut>;
@@ -575,6 +586,17 @@ export class UpdateBuilder<TTable extends AnyTable> {
     return this;
   }
 
+  /**
+   * Database timestamp helper for mutation values.
+   */
+  now(): DbNow {
+    return dbNow();
+  }
+
+  interval(input: DbIntervalInput): DbInterval {
+    return dbInterval(input);
+  }
+
   /**
    * Enable version checking for optimistic concurrency control
    * @throws Error if the ID is just a string (no version available)
@@ -711,6 +733,7 @@ export class JoinFindBuilder<
   select<const TNewSelect extends SelectClause<TTable>>(
     columns: TNewSelect,
   ): JoinFindBuilder<TTable, TNewSelect, TJoinOut> {
+    // prettier-ignore
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (this as any).#selectClause = columns;
     return this as unknown as JoinFindBuilder<TTable, TNewSelect, TJoinOut>;
@@ -809,15 +832,22 @@ export type IndexedJoinBuilder<TTable extends AnyTable, TJoinOut> = {
     infer TRelationType,
     infer TTargetTable
   >
-    ? <TSelect extends SelectClause<TTable["relations"][K]["table"]> = true, TNestedJoinOut = {}>(
-        builderFn?: (
-          builder: JoinFindBuilder<TTable["relations"][K]["table"]>,
-        ) => JoinFindBuilder<TTable["relations"][K]["table"], TSelect, TNestedJoinOut>,
+    ? <
+        TBuilderFn extends (builder: JoinFindBuilder<TTable["relations"][K]["table"]>) => unknown =
+          (
+            builder: JoinFindBuilder<TTable["relations"][K]["table"]>,
+          ) => JoinFindBuilder<TTable["relations"][K]["table"]>,
+      >(
+        builderFn?: TBuilderFn,
       ) => IndexedJoinBuilder<
         TTable,
         TJoinOut & {
           [P in K]: MapRelationType<
-            SelectResult<TTargetTable, TNestedJoinOut, TSelect>
+            SelectResult<
+              TTargetTable,
+              ExtractJoinBuilderOut<ReturnType<TBuilderFn>>,
+              ExtractJoinBuilderSelect<ReturnType<TBuilderFn>>
+            >
           >[TRelationType];
         }
       >
@@ -943,8 +973,14 @@ export interface IUnitOfWork {
   // Schema registration (for cross-fragment operations like hooks)
   registerSchema(schema: AnySchema, namespace: string | null): void;
 
-  // Hook triggering (schema-agnostic, string-based hook names)
-  triggerHook(hookName: string, payload: unknown, options?: TriggerHookOptions): void;
+  // Hook triggering (schema-agnostic, string-based hook names).
+  // Namespace identifies which fragment/dispatcher owns this hook.
+  triggerHook(
+    namespace: string,
+    hookName: string,
+    payload: unknown,
+    options?: TriggerHookOptions,
+  ): void;
 
   getTriggeredHooks(): readonly TriggeredHook[];
 }
@@ -956,8 +992,10 @@ export interface IUnitOfWork {
  *
  * Note: This is just a marker interface. Restriction is enforced by the UnitOfWork class itself.
  */
-export interface IUnitOfWorkRestricted
-  extends Omit<IUnitOfWork, "executeRetrieve" | "executeMutations"> {}
+export interface IUnitOfWorkRestricted extends Omit<
+  IUnitOfWork,
+  "executeRetrieve" | "executeMutations"
+> {}
 
 export type UOWInstrumentationPhase =
   | "beforeRetrieve"
@@ -1268,6 +1306,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
 
   #retrievalResults?: unknown[];
   #createdInternalIds: (bigint | null)[] = [];
+  #readTrackingEnabled = false;
 
   // Phase coordination promises
   #retrievalPhaseDeferred = new DeferredPromise<unknown[]>();
@@ -1411,6 +1450,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     child.#mutationOps = this.#mutationOps;
     child.#retrievalResults = this.#retrievalResults;
     child.#createdInternalIds = this.#createdInternalIds;
+    child.#readTrackingEnabled = this.#readTrackingEnabled;
     child.#retrievalPhaseDeferred = this.#retrievalPhaseDeferred;
     child.#mutationPhaseDeferred = this.#mutationPhaseDeferred;
     child.#retrievalError = this.#retrievalError;
@@ -1460,6 +1500,7 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     this.#mutationOps = [];
     this.#retrievalResults = undefined;
     this.#createdInternalIds = [];
+    this.#readTrackingEnabled = false;
 
     // Reset state
     this.#state = "building-retrieval";
@@ -1480,8 +1521,14 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
   /**
    * Trigger a hook to be executed after the transaction commits.
    */
-  triggerHook(hookName: string, payload: unknown, options?: TriggerHookOptions): void {
+  triggerHook(
+    namespace: string,
+    hookName: string,
+    payload: unknown,
+    options?: TriggerHookOptions,
+  ): void {
     this.#triggeredHooks.push({
+      namespace,
       hookName,
       payload,
       options,
@@ -1499,6 +1546,14 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     return this.#coordinator.parent?.state ?? this.#state;
   }
 
+  enableReadTracking(): void {
+    this.#readTrackingEnabled = true;
+  }
+
+  get readTrackingEnabled(): boolean {
+    return this.#readTrackingEnabled;
+  }
+
   get name(): string | undefined {
     return this.#name;
   }
@@ -1830,8 +1885,7 @@ export class TypedUnitOfWork<
   const TRetrievalResults extends unknown[] = [],
   const TRawInput = unknown,
   const THooks extends HooksMap = {},
-> implements IUnitOfWork
-{
+> {
   #schema: TSchema;
   #namespace?: string | null;
   #uow: UnitOfWork<TRawInput>;
@@ -1844,6 +1898,9 @@ export class TypedUnitOfWork<
     this.#uow = uow;
   }
 
+  /**
+   * Type-only access to retrieval results for this typed UOW.
+   */
   get $results(): Prettify<TRetrievalResults> {
     throw new Error("type only");
   }
@@ -1931,6 +1988,20 @@ export class TypedUnitOfWork<
     return this.#uow.forSchema<TOtherSchema, TOtherHooks>(schema, hooks);
   }
 
+  /**
+   * Database timestamp helper for inserts.
+   */
+  now(): DbNow {
+    return dbNow();
+  }
+
+  /**
+   * Build a database interval for use with now().plus(...).
+   */
+  interval(input: DbIntervalInput): DbInterval {
+    return dbInterval(input);
+  }
+
   registerSchema(schema: AnySchema, namespace: string | null): void {
     this.#uow.registerSchema(schema, namespace);
   }
@@ -2008,6 +2079,7 @@ export class TypedUnitOfWork<
       indexName,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       options: options as any,
+      readTracking: this.#uow.readTrackingEnabled,
     });
 
     // Track which operation index belongs to this view
@@ -2086,6 +2158,7 @@ export class TypedUnitOfWork<
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       options: options as any,
       withSingleResult: true,
+      readTracking: this.#uow.readTrackingEnabled,
     });
 
     // Track which operation index belongs to this view
@@ -2134,6 +2207,7 @@ export class TypedUnitOfWork<
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       options: options as any,
       withCursor: true,
+      readTracking: this.#uow.readTrackingEnabled,
     });
 
     // Track which operation index belongs to this view
@@ -2290,15 +2364,27 @@ export class TypedUnitOfWork<
     throw new Error("type only");
   }
 
+  get namespace(): string | null | undefined {
+    return this.#namespace;
+  }
+
   /**
    * Trigger a hook to be executed after the transaction commits.
+   * The namespace is automatically injected from this typed view's schema registration.
    */
   triggerHook<K extends keyof THooks & string>(
     hookName: K,
     payload: HookPayload<THooks[K]>,
     options?: TriggerHookOptions,
   ): void {
-    this.#uow.triggerHook(hookName, payload, options);
+    if (this.#namespace === undefined) {
+      throw new Error(
+        "Cannot trigger hook: schema has no registered namespace. " +
+          "Ensure the schema is registered with a namespace via registerSchema().",
+      );
+    }
+    const hookNamespace = this.#namespace ?? this.#schema.name;
+    this.#uow.triggerHook(hookNamespace, hookName, payload, options);
   }
 
   getTriggeredHooks(): ReadonlyArray<TriggeredHook> {

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

@@ -1,12 +1,13 @@
 import { assert, describe, expect, it } from "vitest";
-import { column, idColumn, referenceColumn, schema, FragnoId } from "../schema/create";
-import { decodeResult } from "./value-decoding";
+
 import {
   SQLocalDriverConfig,
   NodePostgresDriverConfig,
   PGLiteDriverConfig,
   MySQL2DriverConfig,
 } from "../adapters/generic-sql/driver-config";
+import { column, idColumn, referenceColumn, schema, FragnoId } from "../schema/create";
+import { decodeResult } from "./value-decoding";
 
 describe("decodeResult", () => {
   const testSchema = schema("test", (s) => {
@@ -33,6 +34,11 @@ describe("decodeResult", () => {
         type: "one",
         from: { table: "posts", column: "userId" },
         to: { table: "users", column: "id" },
+      })
+      .addReference("posts", {
+        type: "many",
+        from: { table: "users", column: "id" },
+        to: { table: "posts", column: "userId" },
       });
   });
 
@@ -300,6 +306,48 @@ describe("decodeResult", () => {
       expect(author["id"].internalId).toBe(BigInt(200));
       expect(author["name"]).toBe("Alice");
     });
+
+    it("should return null for missing one relations when internal id is null", () => {
+      const result = decodeResult(
+        {
+          id: "post1",
+          title: "My Post",
+          "author:id": null,
+          "author:_internalId": null,
+          "author:_version": null,
+          "author:name": null,
+        },
+        postsTable,
+        sqliteConfig,
+      );
+
+      expect(result).toEqual({
+        id: "post1",
+        title: "My Post",
+        author: null,
+      });
+    });
+
+    it("should return empty array for missing many relations when internal id is null", () => {
+      const result = decodeResult(
+        {
+          id: "user1",
+          name: "Alice",
+          "posts:id": null,
+          "posts:_internalId": null,
+          "posts:_version": null,
+          "posts:title": null,
+        },
+        usersTable,
+        sqliteConfig,
+      );
+
+      expect(result).toEqual({
+        id: "user1",
+        name: "Alice",
+        posts: [],
+      });
+    });
   });
 
   describe("complete record decoding", () => {

package/src/query/value-decoding.ts

@@ -1,9 +1,12 @@
-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";
+import type { AnyTable } from "../schema/create";
+import { FragnoId, FragnoReference } from "../schema/create";
+import { createSQLSerializer } from "./serialize/create-sql-serializer";
+
+const isNullish = (value: unknown): value is null | undefined =>
+  value === null || value === undefined;
 
 /**
  * Decodes a database result record to application format.
@@ -84,9 +87,19 @@ export function decodeResult(
       continue;
     }
 
+    const relationRow = relationData[relationName];
+    const internalIdKey = relation.table.getInternalIdColumn().name;
+    if (
+      Object.prototype.hasOwnProperty.call(relationRow, internalIdKey) &&
+      isNullish(relationRow[internalIdKey])
+    ) {
+      output[relationName] = relation.type === "many" ? [] : null;
+      continue;
+    }
+
     // Recursively decode the relation data
     output[relationName] = decodeResult(
-      relationData[relationName],
+      relationRow,
       relation.table,
       driverConfig,
       sqliteStorageMode,

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

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+
 import {
   column,
   FragnoId,

package/src/query/value-encoding.ts

@@ -1,3 +1,4 @@
+import type { NamingResolver } from "../naming/sql-naming";
 import type { AnyTable, AnyColumn } from "../schema/create";
 import { FragnoId, FragnoReference } from "../schema/create";
 import {
@@ -5,7 +6,6 @@ import {
   generateRuntimeDefault,
   type RuntimeDefaultContext,
 } from "./column-defaults";
-import type { NamingResolver } from "../naming/sql-naming";
 
 /**
  * Marker class for reference column values that need subquery resolution.