@fragno-dev/db 0.0.1 → 0.1.0

package/src/fragment.test.ts

@@ -0,0 +1,287 @@
+import { test, expect, describe, expectTypeOf } from "vitest";
+import { defineFragmentWithDatabase, type FragnoPublicConfigWithDatabase } from "./fragment";
+import { createFragment } from "@fragno-dev/core";
+import { schema, idColumn, column } from "./schema/create";
+import type { AbstractQuery } from "./query/query";
+import type { DatabaseAdapter } from "./mod";
+
+type Empty = Record<never, never>;
+
+const mockDatabaseAdapter: DatabaseAdapter = {
+  createQueryEngine: () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return {} as any;
+  },
+  getSchemaVersion: () => Promise.resolve("0"),
+  createMigrationEngine: () => {
+    throw new Error("Not implemented");
+  },
+  createSchemaGenerator: () => {
+    throw new Error("Not implemented");
+  },
+};
+
+describe("DatabaseFragmentBuilder", () => {
+  describe("Type inference", () => {
+    test("defineFragmentWithDatabase infers schema type from withDatabase", () => {
+      const _testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const _fragment = defineFragmentWithDatabase("test").withDatabase(_testSchema);
+
+      // Type check that withDatabase returns a builder with the schema
+      expectTypeOf(_fragment.definition.name).toEqualTypeOf<string>();
+    });
+
+    test("withDatabase correctly transforms schema type", () => {
+      const _testSchema1 = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const _testSchema2 = schema((s) =>
+        s.addTable("posts", (t) =>
+          t.addColumn("id", idColumn()).addColumn("title", column("string")),
+        ),
+      );
+
+      const fragment1 = defineFragmentWithDatabase("test").withDatabase(_testSchema1);
+      const fragment2 = fragment1.withDatabase(_testSchema2);
+
+      // Type check that we can chain withDatabase
+      expectTypeOf(fragment1.definition.name).toEqualTypeOf<string>();
+      expectTypeOf(fragment2.definition.name).toEqualTypeOf<string>();
+    });
+
+    test("withDependencies has access to config, fragnoConfig, and orm", () => {
+      const _testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const _fragment = defineFragmentWithDatabase("test")
+        .withDatabase(_testSchema)
+        .withDependencies(({ fragnoConfig, orm }) => {
+          expectTypeOf(fragnoConfig).toEqualTypeOf<{ mountRoute?: string }>();
+          expectTypeOf(orm).toEqualTypeOf<AbstractQuery<typeof _testSchema>>();
+
+          return {
+            userService: {
+              getUser: async (id: string) => ({ id, name: "Test" }),
+            },
+          };
+        });
+
+      // Type check that the fragment has the expected structure
+      expectTypeOf(_fragment.definition.name).toEqualTypeOf<string>();
+    });
+
+    test("withServices has access to config, fragnoConfig, deps, and orm", () => {
+      const _testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const _fragment = defineFragmentWithDatabase("test")
+        .withDatabase(_testSchema)
+        .withDependencies(({ orm }) => ({
+          userRepo: {
+            create: (name: string) => orm.create("users", { name }),
+          },
+        }))
+        .withServices(({ fragnoConfig, deps, orm }) => {
+          expectTypeOf(fragnoConfig).toEqualTypeOf<{ mountRoute?: string }>();
+          expectTypeOf(deps).toEqualTypeOf<{
+            userRepo: {
+              create: (name: string) => ReturnType<AbstractQuery<typeof _testSchema>["create"]>;
+            };
+          }>();
+          expectTypeOf(orm).toEqualTypeOf<AbstractQuery<typeof _testSchema>>();
+
+          return {
+            cacheService: {
+              get: (_key: string) => "cached",
+            },
+          };
+        });
+
+      // Type check that the fragment has the expected structure
+      expectTypeOf(_fragment.definition.name).toEqualTypeOf<string>();
+    });
+  });
+
+  describe("Builder pattern", () => {
+    test("Builder methods return new instances", () => {
+      const _testSchema1 = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const _testSchema2 = schema((s) =>
+        s.addTable("posts", (t) =>
+          t.addColumn("id", idColumn()).addColumn("title", column("string")),
+        ),
+      );
+
+      const builder1 = defineFragmentWithDatabase("test");
+      const builder2 = builder1.withDatabase(_testSchema1);
+      const builder3 = builder2.withDatabase(_testSchema2);
+      const builder4 = builder3.withDependencies(() => ({ dep1: "value1" }));
+      const builder5 = builder4.withServices(() => ({ service1: "value1" }));
+
+      expect(builder1).not.toBe(builder2);
+      expect(builder2).not.toBe(builder3);
+      expect(builder3).not.toBe(builder4);
+      expect(builder4).not.toBe(builder5);
+    });
+
+    test("Each builder step preserves previous configuration", () => {
+      const _testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const fragment = defineFragmentWithDatabase("my-db-lib")
+        .withDatabase(_testSchema)
+        .withDependencies(({ orm }) => ({
+          client: "test client",
+          orm,
+        }))
+        .withServices(({ deps }) => ({
+          service: `Service using ${deps.client}`,
+        }));
+
+      expect(fragment.definition.name).toBe("my-db-lib");
+      expect(fragment.definition.dependencies).toBeDefined();
+      expect(fragment.definition.services).toBeDefined();
+    });
+  });
+
+  describe("Fragment instantiation", () => {
+    test("createFragment works with database adapter", async () => {
+      const testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const fragmentDef = defineFragmentWithDatabase("test-db")
+        .withDatabase(testSchema)
+        .withDependencies(({ orm }) => ({
+          userService: {
+            createUser: (name: string) => orm.create("users", { name }),
+          },
+        }))
+        .withServices(() => ({
+          logger: { log: (s: string) => console.log(s) },
+        }));
+
+      const options: FragnoPublicConfigWithDatabase = {
+        databaseAdapter: mockDatabaseAdapter,
+      };
+
+      const fragment = createFragment(fragmentDef, {}, [], options);
+
+      expect(fragment.config.name).toBe("test-db");
+      expect(fragment.deps).toHaveProperty("userService");
+      expect(fragment.services).toHaveProperty("logger");
+    });
+
+    test("throws error when database adapter is missing from dependencies", () => {
+      const testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const fragmentDef = defineFragmentWithDatabase("test-db")
+        .withDatabase(testSchema)
+        .withDependencies(() => ({
+          service: "test",
+        }));
+
+      expect(() => {
+        // @ts-expect-error - Test case
+        createFragment(fragmentDef, {}, [], {});
+      }).toThrow(/requires a database adapter/);
+    });
+
+    test("throws error when database adapter is missing from services", () => {
+      const testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      const fragmentDef = defineFragmentWithDatabase("test-db")
+        .withDatabase(testSchema)
+        .withDependencies(() => ({
+          service: "test",
+        }))
+        .withServices(() => ({
+          serviceValue: "test",
+        }));
+
+      const options: FragnoPublicConfigWithDatabase = {
+        databaseAdapter: mockDatabaseAdapter,
+      };
+
+      // Services are called after dependencies, so this should work
+      const fragment = createFragment(fragmentDef, {}, [], options);
+      expect(fragment.services).toHaveProperty("serviceValue");
+    });
+
+    test("throws error when schema is not provided via withDatabase", () => {
+      const fragmentDef = defineFragmentWithDatabase<Empty>("test-db").withDependencies(() => ({
+        service: "test",
+      }));
+
+      const options: FragnoPublicConfigWithDatabase = {
+        databaseAdapter: mockDatabaseAdapter,
+      };
+
+      expect(() => {
+        createFragment(fragmentDef, {}, [], options);
+      }).toThrow(/requires a schema/);
+    });
+
+    test("orm is accessible in both dependencies and services", async () => {
+      const testSchema = schema((s) =>
+        s.addTable("users", (t) =>
+          t.addColumn("id", idColumn()).addColumn("name", column("string")),
+        ),
+      );
+
+      let depsOrm: AbstractQuery<typeof testSchema> | undefined;
+      let servicesOrm: AbstractQuery<typeof testSchema> | undefined;
+
+      const fragmentDef = defineFragmentWithDatabase("test-db")
+        .withDatabase(testSchema)
+        .withDependencies(({ orm }) => {
+          depsOrm = orm;
+          return { dep: "value" };
+        })
+        .withServices(({ orm }) => {
+          servicesOrm = orm;
+          return { service: "value" };
+        });
+
+      const options: FragnoPublicConfigWithDatabase = {
+        databaseAdapter: mockDatabaseAdapter,
+      };
+
+      createFragment(fragmentDef, {}, [], options);
+
+      expect(depsOrm).toBeDefined();
+      expect(servicesOrm).toBeDefined();
+    });
+  });
+});

package/src/fragment.ts

@@ -0,0 +1,198 @@
+import type { AnySchema } from "./schema/create";
+import type { AbstractQuery } from "./query/query";
+import type { DatabaseAdapter } from "./adapters/adapters";
+import type { FragnoPublicConfig, FragmentDefinition } from "@fragno-dev/core";
+
+/**
+ * Extended FragnoPublicConfig that includes a database adapter.
+ * Use this type when creating fragments with database support.
+ */
+export type FragnoPublicConfigWithDatabase = FragnoPublicConfig & {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  databaseAdapter: DatabaseAdapter<any>;
+};
+
+/**
+ * Additional context provided to database fragments containing the database adapter and ORM instance.
+ */
+export type DatabaseFragmentContext<TSchema extends AnySchema> = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  databaseAdapter: DatabaseAdapter<any>;
+  orm: AbstractQuery<TSchema>;
+};
+
+export class DatabaseFragmentBuilder<
+  const TSchema extends AnySchema,
+  const TConfig,
+  const TDeps = {},
+  const TServices extends Record<string, unknown> = {},
+> {
+  #name: string;
+  #schema?: TSchema;
+  #namespace?: string;
+  #dependencies?: (
+    context: {
+      config: TConfig;
+      fragnoConfig: FragnoPublicConfig;
+    } & DatabaseFragmentContext<TSchema>,
+  ) => TDeps;
+  #services?: (
+    context: {
+      config: TConfig;
+      fragnoConfig: FragnoPublicConfig;
+      deps: TDeps;
+    } & DatabaseFragmentContext<TSchema>,
+  ) => TServices;
+
+  constructor(options: {
+    name: string;
+    schema?: TSchema;
+    namespace?: string;
+    dependencies?: (
+      context: {
+        config: TConfig;
+        fragnoConfig: FragnoPublicConfig;
+      } & DatabaseFragmentContext<TSchema>,
+    ) => TDeps;
+    services?: (
+      context: {
+        config: TConfig;
+        fragnoConfig: FragnoPublicConfig;
+        deps: TDeps;
+      } & DatabaseFragmentContext<TSchema>,
+    ) => TServices;
+  }) {
+    this.#name = options.name;
+    this.#schema = options.schema;
+    this.#namespace = options.namespace;
+    this.#dependencies = options.dependencies;
+    this.#services = options.services;
+  }
+
+  get $requiredOptions(): FragnoPublicConfigWithDatabase {
+    throw new Error("Type only method. Do not call.");
+  }
+
+  get definition(): FragmentDefinition<TConfig, TDeps, TServices> {
+    const schema = this.#schema;
+    const namespace = this.#namespace ?? "";
+    const name = this.#name;
+    const dependencies = this.#dependencies;
+    const services = this.#services;
+
+    return {
+      name,
+      dependencies: (config: TConfig, options: FragnoPublicConfig) => {
+        const dbContext = this.#createDatabaseContext(options, schema, namespace, name);
+        return dependencies?.({ config, fragnoConfig: options, ...dbContext }) ?? ({} as TDeps);
+      },
+      services: (config: TConfig, options: FragnoPublicConfig, deps: TDeps) => {
+        const dbContext = this.#createDatabaseContext(options, schema, namespace, name);
+        return (
+          services?.({ config, fragnoConfig: options, deps, ...dbContext }) ?? ({} as TServices)
+        );
+      },
+      additionalContext: {
+        databaseSchema: schema,
+        databaseNamespace: namespace,
+      },
+    };
+  }
+
+  #createDatabaseContext(
+    options: FragnoPublicConfig,
+    schema: TSchema | undefined,
+    namespace: string,
+    name: string,
+  ): DatabaseFragmentContext<TSchema> {
+    // Safe cast: FragnoPublicConfig is extended with databaseAdapter by the user
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const databaseAdapter = (options as any).databaseAdapter as DatabaseAdapter<any> | undefined;
+
+    if (!databaseAdapter) {
+      throw new Error(`Fragment '${name}' requires a database adapter in options.databaseAdapter`);
+    }
+    if (!schema) {
+      throw new Error(`Fragment '${name}' requires a schema. Use withDatabase() to provide one.`);
+    }
+
+    // Safe cast: we create a query engine for TSchema and know it will be AbstractQuery<TSchema>
+    const orm = databaseAdapter.createQueryEngine(
+      schema,
+      namespace,
+    ) as unknown as AbstractQuery<TSchema>;
+
+    return { databaseAdapter, orm };
+  }
+
+  withDatabase<TNewSchema extends AnySchema>(
+    schema: TNewSchema,
+    namespace?: string,
+  ): DatabaseFragmentBuilder<TNewSchema, TConfig, TDeps, TServices> {
+    return new DatabaseFragmentBuilder<TNewSchema, TConfig, TDeps, TServices>({
+      name: this.#name,
+      schema,
+      namespace: namespace ?? this.#name + "-db",
+      dependencies: this.#dependencies as
+        | ((
+            context: {
+              config: TConfig;
+              fragnoConfig: FragnoPublicConfig;
+            } & DatabaseFragmentContext<TNewSchema>,
+          ) => TDeps)
+        | undefined,
+      services: this.#services as
+        | ((
+            context: {
+              config: TConfig;
+              fragnoConfig: FragnoPublicConfig;
+              deps: TDeps;
+            } & DatabaseFragmentContext<TNewSchema>,
+          ) => TServices)
+        | undefined,
+    });
+  }
+
+  withDependencies<TNewDeps>(
+    fn: (
+      context: {
+        config: TConfig;
+        fragnoConfig: FragnoPublicConfig;
+      } & DatabaseFragmentContext<TSchema>,
+    ) => TNewDeps,
+  ): DatabaseFragmentBuilder<TSchema, TConfig, TNewDeps, {}> {
+    return new DatabaseFragmentBuilder<TSchema, TConfig, TNewDeps, {}>({
+      name: this.#name,
+      schema: this.#schema,
+      namespace: this.#namespace,
+      dependencies: fn,
+      services: undefined,
+    });
+  }
+
+  withServices<TNewServices extends Record<string, unknown>>(
+    fn: (
+      context: {
+        config: TConfig;
+        fragnoConfig: FragnoPublicConfig;
+        deps: TDeps;
+      } & DatabaseFragmentContext<TSchema>,
+    ) => TNewServices,
+  ): DatabaseFragmentBuilder<TSchema, TConfig, TDeps, TNewServices> {
+    return new DatabaseFragmentBuilder<TSchema, TConfig, TDeps, TNewServices>({
+      name: this.#name,
+      schema: this.#schema,
+      namespace: this.#namespace,
+      dependencies: this.#dependencies,
+      services: fn,
+    });
+  }
+}
+
+export function defineFragmentWithDatabase<TConfig = {}>(
+  name: string,
+): DatabaseFragmentBuilder<never, TConfig, {}, {}> {
+  return new DatabaseFragmentBuilder<never, TConfig, {}, {}>({
+    name,
+  });
+}