@fragno-dev/db 0.1.13 → 0.1.15

package/src/db-fragment-integration.test.ts

@@ -0,0 +1,408 @@
+import { Kysely } from "kysely";
+import { SQLocalKysely } from "sqlocal/kysely";
+import { assert, beforeAll, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { KyselyAdapter } from "./adapters/kysely/kysely-adapter";
+import { column, idColumn, referenceColumn, schema, type FragnoId } from "./schema/create";
+import { defineFragment, instantiate } from "@fragno-dev/core";
+import { defineRoutes } from "@fragno-dev/core/route";
+import { withDatabase } from "./with-database";
+import type { FragnoPublicConfigWithDatabase } from "./db-fragment-definition-builder";
+
+describe.sequential("Database Fragment Integration", () => {
+  // Schema 1: Users fragment
+  const usersSchema = schema((s) => {
+    return s
+      .addTable("users", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("name", column("string"))
+          .addColumn("email", column("string"))
+          .createIndex("email_idx", ["email"], { unique: true });
+      })
+      .addTable("profiles", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("user_id", referenceColumn())
+          .addColumn("bio", column("string"))
+          .createIndex("profile_user_idx", ["user_id"]);
+      })
+      .addReference("user", {
+        type: "one",
+        from: { table: "profiles", column: "user_id" },
+        to: { table: "users", column: "id" },
+      });
+  });
+
+  // Schema 2: Orders fragment
+  const ordersSchema = schema((s) => {
+    return s.addTable("orders", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("user_external_id", column("string")) // Store external user ID from users fragment
+        .addColumn("product_name", column("string"))
+        .addColumn("quantity", column("integer"))
+        .addColumn("total", column("integer"))
+        .createIndex("orders_user_idx", ["user_external_id"]);
+    });
+  });
+
+  // Define Users Fragment
+  const usersFragmentDef = defineFragment("users-fragment")
+    .extend(withDatabase(usersSchema, "users"))
+    .providesService("userService", ({ defineService }) => {
+      return defineService({
+        createUser(name: string, email: string): FragnoId {
+          const uow = this.uow(usersSchema);
+          return uow.create("users", { name, email });
+        },
+        async getUserById(userId: FragnoId | string) {
+          const uow = this.uow(usersSchema).find("users", (b) =>
+            b.whereIndex("primary", (eb) => eb("id", "=", userId)),
+          );
+          // Note: executeRetrieve() should be called by the caller before awaiting retrievalPhase
+          const [users] = await uow.retrievalPhase;
+          return users?.[0] ?? null;
+        },
+        createProfile(userId: FragnoId | string, bio: string): FragnoId {
+          const uow = this.uow(usersSchema);
+          return uow.create("profiles", {
+            user_id: userId,
+            bio,
+          });
+        },
+      });
+    })
+    .build();
+
+  // Define routes for Users Fragment
+  const usersRoutes = defineRoutes(usersFragmentDef).create(({ services, defineRoute }) => [
+    defineRoute({
+      method: "POST",
+      path: "/users",
+      outputSchema: z.object({ userId: z.string(), profileId: z.string() }),
+      handler: async function (_input, { json }) {
+        const { userId, profileId } = await this.uow(async ({ executeMutate }) => {
+          const userId = services.userService.createUser("John Doe", "john@example.com");
+          const profileId = services.userService.createProfile(userId, "Software engineer");
+          await executeMutate();
+          return { userId, profileId };
+        });
+
+        return json(
+          { userId: userId.externalId, profileId: profileId.externalId },
+          { status: 201 },
+        );
+      },
+    }),
+  ]);
+
+  // Define Orders Fragment with cross-fragment service dependency
+  const ordersFragmentDef = defineFragment("orders-fragment")
+    .extend(withDatabase(ordersSchema, "orders"))
+    .usesService<
+      "userService",
+      {
+        getUserById: (
+          userId: FragnoId | string,
+        ) => Promise<{ id: FragnoId; name: string; email: string } | null>;
+      }
+    >("userService")
+    .providesService("orderService", ({ defineService, serviceDeps }) => {
+      return defineService({
+        async createOrder(
+          userExternalId: string,
+          productName: string,
+          quantity: number,
+          total: number,
+        ) {
+          // Verify user exists by calling the userService from the other fragment
+          const user = await serviceDeps.userService.getUserById(userExternalId);
+
+          if (!user) {
+            throw new Error("User not found");
+          }
+
+          const uow = this.uow(ordersSchema);
+          const orderId = uow.create("orders", {
+            user_external_id: userExternalId,
+            product_name: productName,
+            quantity,
+            total,
+          });
+
+          await uow.mutationPhase;
+          return orderId;
+        },
+        async getOrdersByUser(userExternalId: string) {
+          const uow = this.uow(ordersSchema).find("orders", (b) =>
+            b.whereIndex("orders_user_idx", (eb) => eb("user_external_id", "=", userExternalId)),
+          );
+          // Note: executeRetrieve() should be called by the caller before awaiting retrievalPhase
+          const [orders] = await uow.retrievalPhase;
+          return orders;
+        },
+      });
+    })
+    .build();
+
+  // Define routes for Orders Fragment
+  const ordersRoutes = defineRoutes(ordersFragmentDef).create(({ services, defineRoute }) => [
+    defineRoute({
+      method: "POST",
+      path: "/orders",
+      inputSchema: z.object({
+        userId: z.string(),
+        productName: z.string(),
+        quantity: z.number(),
+        total: z.number(),
+      }),
+      outputSchema: z.object({ orderId: z.string() }),
+      handler: async function ({ input }, { json }) {
+        const body = await input.valid();
+
+        const { orderId } = await this.uow(async ({ executeMutate }) => {
+          const orderIdPromise = services.orderService.createOrder(
+            body.userId,
+            body.productName,
+            body.quantity,
+            body.total,
+          );
+
+          await executeMutate();
+
+          return { orderId: await orderIdPromise };
+        });
+
+        return json({ orderId: orderId.externalId }, { status: 201 });
+      },
+    }),
+  ]);
+
+  let adapter: KyselyAdapter;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let kysely: Kysely<any>;
+  let usersFragment: ReturnType<typeof instantiateUsersFragment>;
+  let ordersFragment: ReturnType<typeof instantiateOrdersFragment>;
+
+  // Shared state between tests
+  let userId: string;
+  let orderId: string;
+
+  function instantiateUsersFragment(options: FragnoPublicConfigWithDatabase) {
+    return instantiate(usersFragmentDef)
+      .withConfig({})
+      .withRoutes([usersRoutes])
+      .withOptions(options)
+      .build();
+  }
+
+  function instantiateOrdersFragment(options: FragnoPublicConfigWithDatabase) {
+    return instantiate(ordersFragmentDef)
+      .withConfig({})
+      .withRoutes([ordersRoutes])
+      .withOptions(options)
+      .withServices({
+        userService: usersFragment.services.userService,
+      })
+      .build();
+  }
+
+  beforeAll(async () => {
+    // Create in-memory SQLite database with Kysely
+    const { dialect } = new SQLocalKysely(":memory:");
+    kysely = new Kysely({
+      dialect,
+    });
+
+    adapter = new KyselyAdapter({
+      db: kysely,
+      provider: "sqlite",
+    });
+
+    // Run migrations for both schemas
+    const usersMigrator = adapter.createMigrationEngine(usersSchema, "users");
+    const usersPrep = await usersMigrator.prepareMigration({ updateSettings: false });
+    await usersPrep.execute();
+
+    const ordersMigrator = adapter.createMigrationEngine(ordersSchema, "orders");
+    const ordersPrep = await ordersMigrator.prepareMigration({ updateSettings: false });
+    await ordersPrep.execute();
+
+    // Instantiate fragments with shared database adapter
+    const options: FragnoPublicConfigWithDatabase = {
+      databaseAdapter: adapter,
+    };
+
+    usersFragment = instantiateUsersFragment(options);
+    ordersFragment = instantiateOrdersFragment(options);
+  }, 12000);
+
+  it("should create a user via API route", async () => {
+    const createUserResponse = await usersFragment.callRoute("POST", "/users");
+    assert(createUserResponse.type === "json");
+    expect(createUserResponse.data).toHaveProperty("userId");
+    userId = createUserResponse.data.userId;
+  });
+
+  it("should verify user was created with profile", async () => {
+    const user = await usersFragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const userPromise = usersFragment.services.userService.getUserById(userId);
+        await executeRetrieve();
+        return await userPromise;
+      });
+    });
+
+    expect(user).toMatchObject({
+      id: expect.objectContaining({
+        externalId: userId,
+      }),
+      name: "John Doe",
+      email: "john@example.com",
+    });
+  });
+
+  it("should create an order via API route with cross-fragment service call", async () => {
+    const createOrderResponse = await ordersFragment.callRoute("POST", "/orders", {
+      body: {
+        userId: userId,
+        productName: "TypeScript Book",
+        quantity: 2,
+        total: 4999,
+      },
+    });
+    assert(
+      createOrderResponse.type === "json",
+      `createOrderResponse.type !== json: ${createOrderResponse.type}`,
+    );
+    orderId = createOrderResponse.data.orderId;
+  });
+
+  it("should verify order was created with correct user reference", async () => {
+    const orders = await ordersFragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const ordersPromise = ordersFragment.services.orderService.getOrdersByUser(userId);
+        await executeRetrieve();
+        return await ordersPromise;
+      });
+    });
+    expect(orders).toHaveLength(1);
+    expect(orders[0]).toMatchObject({
+      id: expect.objectContaining({
+        externalId: orderId,
+      }),
+      user_external_id: userId,
+      product_name: "TypeScript Book",
+      quantity: 2,
+      total: 4999,
+    });
+  });
+
+  it("should verify cross-fragment service integration works bidirectionally", async () => {
+    // Orders service should be able to query users via the shared userService
+    const ordersByUser = await ordersFragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const ordersPromise = ordersFragment.services.orderService.getOrdersByUser(userId);
+        await executeRetrieve();
+        return await ordersPromise;
+      });
+    });
+    const userFromOrdersContext = await usersFragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const userPromise = usersFragment.services.userService.getUserById(
+          ordersByUser[0].user_external_id,
+        );
+        await executeRetrieve();
+        return await userPromise;
+      });
+    });
+
+    expect(userFromOrdersContext).toMatchObject({
+      id: expect.objectContaining({
+        externalId: userId,
+      }),
+      name: "John Doe",
+      email: "john@example.com",
+    });
+  });
+
+  it("should reject order creation for non-existent user", async () => {
+    const invalidOrderResponse = await ordersFragment.callRoute("POST", "/orders", {
+      body: {
+        userId: "non-existent-user-id",
+        productName: "Invalid Order",
+        quantity: 1,
+        total: 100,
+      },
+    });
+
+    // Should return error because user doesn't exist
+    expect(invalidOrderResponse.type).toBe("error");
+  });
+
+  it("should be able to use inContext to call a service", async () => {
+    const [user, order] = await usersFragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const user = usersFragment.services.userService.getUserById(userId);
+        const orders = ordersFragment.services.orderService.getOrdersByUser(userId);
+        await executeRetrieve();
+        return [user, orders];
+      });
+    });
+    expect(user).toMatchObject({
+      id: expect.objectContaining({
+        externalId: userId,
+      }),
+    });
+
+    expect(order).toHaveLength(1);
+    expect(order[0]).toMatchObject({
+      id: expect.objectContaining({
+        externalId: orderId,
+      }),
+      user_external_id: userId,
+    });
+  });
+
+  it("should provide nonce and currentAttempt in the UOW context", async () => {
+    let firstNonce: string;
+
+    const result = await usersFragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve, nonce, currentAttempt }) => {
+        const user = usersFragment.services.userService.getUserById(userId);
+        await executeRetrieve();
+
+        if (currentAttempt === 0) {
+          firstNonce = nonce;
+          throw new Error("Test error");
+        }
+
+        expect(nonce).toBe(firstNonce);
+
+        // Return context data along with user data
+        return {
+          user,
+          nonce,
+          currentAttempt,
+        };
+      });
+    });
+
+    // Verify nonce is a string UUID
+    expect(result.nonce).toBeDefined();
+    expect(typeof result.nonce).toBe("string");
+    expect(result.nonce).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+
+    expect(result.currentAttempt).toBe(1);
+
+    // Verify user data is still correct
+    expect(result.user).toMatchObject({
+      id: expect.objectContaining({
+        externalId: userId,
+      }),
+      name: "John Doe",
+      email: "john@example.com",
+    });
+  });
+});

package/src/fragments/internal-fragment.test.ts

@@ -0,0 +1,160 @@
+import { drizzle } from "drizzle-orm/libsql";
+import { beforeAll, describe, expect, it } from "vitest";
+import { instantiate } from "@fragno-dev/core";
+import { internalFragmentDef, settingsSchema } from "./internal-fragment";
+import type { FragnoPublicConfigWithDatabase } from "../db-fragment-definition-builder";
+import { DrizzleAdapter } from "../adapters/drizzle/drizzle-adapter";
+import type { DBType } from "../adapters/drizzle/shared";
+import { writeAndLoadSchema } from "../adapters/drizzle/test-utils";
+import { createClient } from "@libsql/client";
+import { createRequire } from "node:module";
+
+// Import drizzle-kit for migrations
+const require = createRequire(import.meta.url);
+const { generateSQLiteDrizzleJson, generateSQLiteMigration } =
+  require("drizzle-kit/api") as typeof import("drizzle-kit/api");
+
+describe("Internal Fragment", () => {
+  let adapter: DrizzleAdapter;
+  let db: DBType;
+  let fragment: ReturnType<typeof instantiateFragment>;
+
+  function instantiateFragment(options: FragnoPublicConfigWithDatabase) {
+    return instantiate(internalFragmentDef).withConfig({}).withOptions(options).build();
+  }
+
+  beforeAll(async () => {
+    const { schemaModule, cleanup } = await writeAndLoadSchema(
+      "internal-fragment",
+      settingsSchema,
+      "sqlite",
+      "",
+    );
+
+    const client = createClient({
+      url: "file::memory:?cache=shared",
+    });
+
+    db = drizzle(client, {
+      schema: schemaModule,
+    }) as unknown as DBType;
+
+    // Generate and run migrations for both schemas
+    const emptyJson = await generateSQLiteDrizzleJson({});
+    const targetJson = await generateSQLiteDrizzleJson(schemaModule);
+
+    const migrationStatements = await generateSQLiteMigration(emptyJson, targetJson);
+
+    for (const statement of migrationStatements) {
+      await client.execute(statement);
+    }
+
+    adapter = new DrizzleAdapter({
+      db,
+      provider: "sqlite",
+    });
+
+    // Instantiate fragment with shared database adapter
+    const options: FragnoPublicConfigWithDatabase = {
+      databaseAdapter: adapter,
+    };
+
+    fragment = instantiateFragment(options);
+
+    return async () => {
+      client.close();
+      await cleanup();
+    };
+  }, 12000);
+
+  it("should get undefined for non-existent key", async () => {
+    const result = await fragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const valuePromise = fragment.services.settingsService.get("test-key");
+        await executeRetrieve();
+        return await valuePromise;
+      });
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should set and get a value", async () => {
+    await fragment.inContext(async function () {
+      return await this.uow(async ({ executeMutate }) => {
+        const setPromise = fragment.services.settingsService.set("test-key", "test-value");
+        await executeMutate();
+        await setPromise;
+      });
+    });
+
+    const result = await fragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const valuePromise = fragment.services.settingsService.get("test-key");
+        await executeRetrieve();
+        return await valuePromise;
+      });
+    });
+
+    expect(result).toMatchObject({
+      key: "fragno-db-settings.test-key",
+      value: "test-value",
+    });
+  });
+
+  it("should update an existing value", async () => {
+    await fragment.inContext(async function () {
+      return await this.uow(async ({ executeMutate }) => {
+        const setPromise = fragment.services.settingsService.set("test-key", "updated-value");
+        await executeMutate();
+        await setPromise;
+      });
+    });
+
+    const result = await fragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const valuePromise = fragment.services.settingsService.get("test-key");
+        await executeRetrieve();
+        return await valuePromise;
+      });
+    });
+
+    expect(result).toMatchObject({
+      key: "fragno-db-settings.test-key",
+      value: "updated-value",
+    });
+  });
+
+  it("should delete a value", async () => {
+    // First get the ID
+    const setting = await fragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const valuePromise = fragment.services.settingsService.get("test-key");
+        await executeRetrieve();
+        return await valuePromise;
+      });
+    });
+
+    expect(setting).toBeDefined();
+
+    // Delete it
+    await fragment.inContext(async function () {
+      return await this.uow(async ({ executeMutate }) => {
+        const deletePromise = fragment.services.settingsService.delete(setting!.id);
+        await executeMutate();
+        await deletePromise;
+      });
+    });
+
+    // Verify it's gone
+    const result = await fragment.inContext(async function () {
+      return await this.uow(async ({ executeRetrieve }) => {
+        const valuePromise = fragment.services.settingsService.get("test-key");
+        await executeRetrieve();
+        return await valuePromise;
+      });
+    });
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/fragments/internal-fragment.ts

@@ -0,0 +1,85 @@
+import { FragmentDefinitionBuilder } from "@fragno-dev/core";
+import {
+  DatabaseFragmentDefinitionBuilder,
+  type DatabaseHandlerContext,
+  type DatabaseRequestStorage,
+  type DatabaseServiceContext,
+  type FragnoPublicConfigWithDatabase,
+  type ImplicitDatabaseDependencies,
+} from "../db-fragment-definition-builder";
+import type { FragnoId } from "../schema/create";
+import { schema, idColumn, column } from "../schema/create";
+
+// Constants for Fragno's internal settings table
+export const SETTINGS_TABLE_NAME = "fragno_db_settings" as const;
+export const SETTINGS_NAMESPACE = "fragno-db-settings" as const;
+
+// Settings schema for storing Fragno's internal key-value settings
+export const settingsSchema = schema((s) => {
+  return s.addTable(SETTINGS_TABLE_NAME, (t) => {
+    return t
+      .addColumn("id", idColumn())
+      .addColumn("key", column("string"))
+      .addColumn("value", column("string"))
+      .createIndex("unique_key", ["key"], { unique: true });
+  });
+});
+
+// This uses DatabaseFragmentDefinitionBuilder directly
+// to avoid circular dependency (it doesn't need to link to itself)
+export const internalFragmentDef = new DatabaseFragmentDefinitionBuilder(
+  new FragmentDefinitionBuilder<
+    {},
+    FragnoPublicConfigWithDatabase,
+    ImplicitDatabaseDependencies<typeof settingsSchema>,
+    {},
+    {},
+    {},
+    {},
+    DatabaseServiceContext,
+    DatabaseHandlerContext,
+    DatabaseRequestStorage
+  >("$fragno-internal-fragment"),
+  settingsSchema,
+  "", // intentionally blank namespace so there is no prefix
+)
+  .providesService("settingsService", ({ defineService }) => {
+    return defineService({
+      async get(key: string): Promise<{ id: FragnoId; key: string; value: string } | undefined> {
+        const uow = this.uow(settingsSchema).find(SETTINGS_TABLE_NAME, (b) =>
+          b.whereIndex("unique_key", (eb) => eb("key", "=", `${SETTINGS_NAMESPACE}.${key}`)),
+        );
+        const [results] = await uow.retrievalPhase;
+        return results?.[0];
+      },
+
+      async set(key: string, value: string) {
+        const uow = this.uow(settingsSchema);
+
+        // First, find if the key already exists
+        const findUow = uow.find(SETTINGS_TABLE_NAME, (b) =>
+          b.whereIndex("unique_key", (eb) => eb("key", "=", `${SETTINGS_NAMESPACE}.${key}`)),
+        );
+        const [existing] = await findUow.retrievalPhase;
+
+        if (existing?.[0]) {
+          uow.update(SETTINGS_TABLE_NAME, existing[0].id, (b) => b.set({ value }).check());
+        } else {
+          uow.create(SETTINGS_TABLE_NAME, {
+            key: `${SETTINGS_NAMESPACE}.${key}`,
+            value,
+          });
+        }
+
+        // Await mutation phase - will throw if mutation fails
+        await uow.mutationPhase;
+      },
+
+      async delete(id: FragnoId) {
+        const uow = this.uow(settingsSchema);
+        uow.delete(SETTINGS_TABLE_NAME, id);
+        await uow.mutationPhase;
+      },
+    });
+  })
+  .build();