@fragno-dev/db 0.2.1 → 0.2.2

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

@@ -722,51 +722,51 @@ describe("UOW Coordinator - Parent-Child Execution", () => {
     // If we got here without Node.js throwing an unhandled rejection, the test passes
   });
 
-  it("should inherit nonce from parent to children for idempotent operations", () => {
+  it("should inherit idempotencyKey from parent to children for idempotent operations", () => {
     const executor = createMockExecutor();
     const parentUow = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
-    // Parent UOW should have a nonce
-    const parentNonce = parentUow.nonce;
-    expect(parentNonce).toBeDefined();
-    expect(typeof parentNonce).toBe("string");
-    expect(parentNonce.length).toBeGreaterThan(0);
+    // Parent UOW should have an idempotencyKey
+    const parentIdempotencyKey = parentUow.idempotencyKey;
+    expect(parentIdempotencyKey).toBeDefined();
+    expect(typeof parentIdempotencyKey).toBe("string");
+    expect(parentIdempotencyKey.length).toBeGreaterThan(0);
 
     // Create first child
     const child1 = parentUow.restrict();
-    expect(child1.nonce).toBe(parentNonce);
+    expect(child1.idempotencyKey).toBe(parentIdempotencyKey);
 
     // Create second child (sibling to child1)
     const child2 = parentUow.restrict();
-    expect(child2.nonce).toBe(parentNonce);
+    expect(child2.idempotencyKey).toBe(parentIdempotencyKey);
 
     // Create nested child (child of child1)
     const grandchild = child1.restrict();
-    expect(grandchild.nonce).toBe(parentNonce);
+    expect(grandchild.idempotencyKey).toBe(parentIdempotencyKey);
 
-    // All UOWs in the hierarchy should share the same nonce
-    expect(parentUow.nonce).toBe(child1.nonce);
-    expect(child1.nonce).toBe(child2.nonce);
-    expect(child2.nonce).toBe(grandchild.nonce);
+    // All UOWs in the hierarchy should share the same idempotencyKey
+    expect(parentUow.idempotencyKey).toBe(child1.idempotencyKey);
+    expect(child1.idempotencyKey).toBe(child2.idempotencyKey);
+    expect(child2.idempotencyKey).toBe(grandchild.idempotencyKey);
   });
 
-  it("should generate different nonces for separate UOW hierarchies", () => {
+  it("should generate different idempotencyKeys for separate UOW hierarchies", () => {
     const executor = createMockExecutor();
 
     // Create two separate parent UOWs
     const parentUow1 = createUnitOfWork(createCompiler(), executor, createMockDecoder());
     const parentUow2 = createUnitOfWork(createCompiler(), executor, createMockDecoder());
 
-    // They should have different nonces
-    expect(parentUow1.nonce).not.toBe(parentUow2.nonce);
+    // They should have different idempotencyKeys
+    expect(parentUow1.idempotencyKey).not.toBe(parentUow2.idempotencyKey);
 
-    // But children within each hierarchy should inherit their parent's nonce
+    // But children within each hierarchy should inherit their parent's idempotencyKey
     const child1 = parentUow1.restrict();
     const child2 = parentUow2.restrict();
 
-    expect(child1.nonce).toBe(parentUow1.nonce);
-    expect(child2.nonce).toBe(parentUow2.nonce);
-    expect(child1.nonce).not.toBe(child2.nonce);
+    expect(child1.idempotencyKey).toBe(parentUow1.idempotencyKey);
+    expect(child2.idempotencyKey).toBe(parentUow2.idempotencyKey);
+    expect(child1.idempotencyKey).not.toBe(child2.idempotencyKey);
   });
 
   it("should not cause unhandled rejection when service method awaits retrievalPhase and executeRetrieve fails", async () => {

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

@@ -838,6 +838,70 @@ describe("DeleteBuilder with string ID", () => {
   });
 });
 
+describe("generateId", () => {
+  const testSchema = schema((s) =>
+    s.addTable("users", (t) =>
+      t.addColumn("id", idColumn()).addColumn("email", "string").addColumn("name", "string"),
+    ),
+  );
+
+  it("should generate a new FragnoId without creating a record", () => {
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    const id = uow.forSchema(testSchema).generateId("users");
+
+    expect(id).toBeInstanceOf(FragnoId);
+    expect(id.externalId).toBeDefined();
+    expect(typeof id.externalId).toBe("string");
+    expect(id.externalId.length).toBeGreaterThan(0);
+    expect(id.version).toBe(0);
+
+    // No mutation operations should be added
+    expect(uow.getMutationOperations()).toHaveLength(0);
+  });
+
+  it("should generate unique IDs on each call", () => {
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+    const typedUow = uow.forSchema(testSchema);
+
+    const id1 = typedUow.generateId("users");
+    const id2 = typedUow.generateId("users");
+
+    expect(id1.externalId).not.toBe(id2.externalId);
+  });
+
+  it("should allow using generated ID in create", async () => {
+    const executor = {
+      executeRetrievalPhase: async () => [],
+      executeMutationPhase: async () => ({
+        success: true,
+        createdInternalIds: [1n],
+      }),
+    };
+
+    const uow = createUnitOfWork(createMockCompiler(), executor, createMockDecoder());
+    const typedUow = uow.forSchema(testSchema);
+
+    const id = typedUow.generateId("users");
+    typedUow.create("users", { id, email: "test@example.com", name: "Test" });
+
+    await uow.executeMutations();
+    const createdIds = uow.getCreatedIds();
+
+    expect(createdIds).toHaveLength(1);
+    expect(createdIds[0].externalId).toBe(id.externalId);
+  });
+
+  it("should throw for non-existent table", () => {
+    const uow = createUnitOfWork(createMockCompiler(), createMockExecutor(), createMockDecoder());
+
+    expect(() => {
+      // @ts-expect-error - testing runtime error for non-existent table
+      uow.forSchema(testSchema).generateId("nonexistent");
+    }).toThrow("Table nonexistent not found in schema");
+  });
+});
+
 describe("getCreatedIds", () => {
   const testSchema = schema((s) =>
     s.addTable("users", (t) =>

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,
@@ -262,13 +263,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)
    */
@@ -903,7 +900,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>;
 
@@ -967,7 +964,7 @@ export function createUnitOfWork(
 export interface UnitOfWorkConfig {
   dryRun?: boolean;
   onQuery?: (query: unknown) => void;
-  nonce?: string;
+  idempotencyKey?: string;
 }
 
 /**
@@ -1199,7 +1196,7 @@ class UOWChildCoordinator<TRawInput> {
 export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
   #name?: string;
   #config?: UnitOfWorkConfig;
-  #nonce: string;
+  #idempotencyKey: string;
 
   #state: UOWState = "building-retrieval";
 
@@ -1243,7 +1240,7 @@ 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();
   }
 
   /**
@@ -1293,7 +1290,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 +1391,8 @@ export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
     return this.#name;
   }
 
-  get nonce(): string {
-    return this.#nonce;
+  get idempotencyKey(): string {
+    return this.#idempotencyKey;
   }
 
   /**
@@ -1674,8 +1671,8 @@ export class TypedUnitOfWork<
     return this.#uow.name;
   }
 
-  get nonce(): string {
-    return this.#uow.nonce;
+  get idempotencyKey(): string {
+    return this.#uow.idempotencyKey;
   }
 
   get state() {
@@ -1962,6 +1959,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]>,

package/src/schema/create.ts

@@ -1,5 +1,7 @@
 import { createId } from "../id";
 
+export { generateId } from "./generate-id";
+
 export type AnySchema = Schema<Record<string, AnyTable>>;
 
 export type AnyRelation = Relation;

package/src/schema/generate-id.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { schema, idColumn, FragnoId } from "./create";
+import { generateId } from "./generate-id";
+
+describe("generateId", () => {
+  const testSchema = schema((s) =>
+    s.addTable("users", (t) =>
+      t.addColumn("id", idColumn()).addColumn("email", "string").addColumn("name", "string"),
+    ),
+  );
+
+  it("should generate a new FragnoId", () => {
+    const id = generateId(testSchema, "users");
+
+    expect(id).toBeInstanceOf(FragnoId);
+    expect(id.externalId).toBeDefined();
+    expect(typeof id.externalId).toBe("string");
+    expect(id.externalId.length).toBeGreaterThan(0);
+    expect(id.version).toBe(0);
+  });
+
+  it("should generate unique IDs on each call", () => {
+    const id1 = generateId(testSchema, "users");
+    const id2 = generateId(testSchema, "users");
+
+    expect(id1.externalId).not.toBe(id2.externalId);
+  });
+
+  it("should throw for non-existent table", () => {
+    expect(() => {
+      // @ts-expect-error - testing runtime error for non-existent table
+      generateId(testSchema, "nonexistent");
+    }).toThrow("Table nonexistent not found in schema");
+  });
+
+  it("should work with multiple tables", () => {
+    const multiTableSchema = schema((s) =>
+      s
+        .addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("email", "string").addColumn("name", "string"),
+        )
+        .addTable("posts", (t) =>
+          t
+            .addColumn("id", idColumn())
+            .addColumn("title", "string")
+            .addColumn("authorId", "string"),
+        ),
+    );
+
+    const userId = generateId(multiTableSchema, "users");
+    const postId = generateId(multiTableSchema, "posts");
+
+    expect(userId).toBeInstanceOf(FragnoId);
+    expect(postId).toBeInstanceOf(FragnoId);
+    expect(userId.externalId).not.toBe(postId.externalId);
+  });
+});

package/src/schema/generate-id.ts

@@ -0,0 +1,38 @@
+import type { AnySchema } from "./create";
+import { FragnoId } from "./create";
+
+/**
+ * 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 = generateId(mySchema, "users");
+ * // Use userId in related records or pass to external services
+ * uow.create("users", { id: userId, name: "John" });
+ * ```
+ */
+export function generateId<
+  TSchema extends AnySchema,
+  TableName extends keyof TSchema["tables"] & string,
+>(schema: TSchema, tableName: TableName): FragnoId {
+  const tableSchema = schema.tables[tableName];
+  if (!tableSchema) {
+    throw new Error(`Table ${tableName} not found in schema`);
+  }
+
+  const idColumn = tableSchema.getIdColumn();
+  const generated = idColumn.generateDefaultValue();
+  if (generated === undefined) {
+    throw new Error(`ID column ${idColumn.ormName} on table ${tableName} has no default generator`);
+  }
+
+  if (typeof generated !== "string") {
+    throw new Error(
+      `ID column ${idColumn.ormName} on table ${tableName} has no default generator that generates a string.`,
+    );
+  }
+
+  return FragnoId.fromExternal(generated, 0);
+}

package/src/shared/config.ts

@@ -1,10 +0,0 @@
-import type { AnySchema } from "../schema/create";
-
-export interface LibraryConfig<TSchemas extends AnySchema[] = AnySchema[]> {
-  namespace: string;
-
-  /**
-   * different versions of schemas (sorted in ascending order)
-   */
-  schemas: TSchemas;
-}

package/src/shared/connection-pool.ts

@@ -1,24 +0,0 @@
-/**
- * Represents an active database connection that can be released back to the pool.
- */
-export interface Connection<TDatabase> {
-  db: TDatabase;
-  release(): Promise<void>;
-}
-
-/**
- * Connection pool interface for managing database connections.
- * Adapter-specific implementations should be used (e.g., createKyselyConnectionPool, createDrizzleConnectionPool).
- */
-export interface ConnectionPool<TDatabase> {
-  /** Acquire a connection from the pool */
-  connect(): Promise<Connection<TDatabase>>;
-  /**
-   * Get the database instance synchronously. Only works if the pool has already been initialized
-   * via connect().
-   * @throws an error if called before the pool is initialized.
-   */
-  getDatabaseSync(): TDatabase;
-  /** Close the pool and cleanup resources */
-  close(): Promise<void>;
-}

package/src/shared/prisma.ts

@@ -1,45 +0,0 @@
-export type PrismaClient = Record<
-  string,
-  {
-    count: (options: {
-      select: Record<string, unknown>;
-      where?: object;
-    }) => Promise<Record<string, number>>;
-    upsert: (options: {
-      where: object;
-      update: Record<string, unknown>;
-      create: Record<string, unknown>;
-    }) => Promise<void>;
-
-    create: (options: { data: Record<string, unknown> }) => Promise<Record<string, unknown>>;
-
-    createMany: (options: { data: Record<string, unknown>[] }) => Promise<void>;
-
-    delete: (options: { where: object }) => Promise<Record<string, unknown>>;
-
-    deleteMany: (options: { where?: object }) => Promise<void>;
-
-    findFirst: (options: {
-      where: object;
-      select?: Record<string, unknown>;
-      orderBy?: OrderBy | OrderBy[];
-      skip?: number;
-    }) => Promise<Record<string, unknown> | null>;
-
-    findMany: (options: {
-      where?: object;
-      select?: Record<string, unknown>;
-      orderBy?: OrderBy | OrderBy[];
-      skip?: number;
-      take?: number;
-    }) => Promise<Record<string, unknown>[]>;
-
-    updateMany: (options: { where?: object; data: Record<string, unknown> }) => Promise<void>;
-  }
-> & {
-  $transaction: <T>(v: (tx: PrismaClient) => T | Promise<T>) => Promise<T>;
-};
-
-export type OrderBy = {
-  [k: string]: "asc" | "desc" | OrderBy;
-};