@fragno-dev/db 0.0.1 → 0.1.0

package/src/migration-engine/create.test.ts

@@ -23,20 +23,17 @@ describe("createMigrator", () => {
 
     const options: MigrationEngineOptions = {
       schema: testSchema,
-      userConfig: {
-        provider: "postgresql",
-      },
       executor: async (operations) => {
         executedOperations.push(operations);
       },
       settings: {
         getVersion: async () => version,
-        updateSettingsInMigration: async (newVersion) => {
-          version = newVersion;
+        updateSettingsInMigration: async (_fromVersion, toVersion) => {
+          version = toVersion;
           return [
             {
               type: "custom",
-              sql: `UPDATE _settings SET version = ${newVersion}`,
+              sql: `UPDATE _settings SET version = ${toVersion}`,
             },
           ];
         },
@@ -52,7 +49,7 @@ describe("createMigrator", () => {
     it("should migrate from version 0 to latest schema version", async () => {
       const { migrator, getVersion } = createTestMigrator(0);
 
-      const result = await migrator.migrate();
+      const result = await migrator.prepareMigration();
 
       expect(result.operations.length).toBeGreaterThan(0);
       expect(getVersion()).toBe(testSchema.version);
@@ -61,7 +58,7 @@ describe("createMigrator", () => {
     it("should migrate from intermediate version to latest", async () => {
       const { migrator, getVersion } = createTestMigrator(1);
 
-      const result = await migrator.migrate();
+      const result = await migrator.prepareMigration();
 
       expect(result.operations.length).toBeGreaterThan(0);
       expect(getVersion()).toBe(testSchema.version);
@@ -70,7 +67,7 @@ describe("createMigrator", () => {
     it("should return empty operations when already at latest version", async () => {
       const { migrator, getVersion } = createTestMigrator(testSchema.version);
 
-      const result = await migrator.migrate();
+      const result = await migrator.prepareMigration();
 
       expect(result.operations).toEqual([]);
       expect(getVersion()).toBe(testSchema.version);
@@ -79,7 +76,7 @@ describe("createMigrator", () => {
     it("should generate correct operations when jumping multiple versions", async () => {
       const { migrator } = createTestMigrator(0);
 
-      const result = await migrator.migrate();
+      const result = await migrator.prepareMigration();
 
       // Should create all 3 tables plus settings update
       const createTableOps = result.operations.filter((op) => op.type === "create-table");
@@ -91,7 +88,7 @@ describe("createMigrator", () => {
     it("should migrate forward from version 0 to version 2", async () => {
       const { migrator, getVersion } = createTestMigrator(0);
 
-      const result = await migrator.migrateTo(2);
+      const result = await migrator.prepareMigrationTo(2);
 
       expect(result.operations.length).toBeGreaterThan(0);
       expect(getVersion()).toBe(2);
@@ -100,7 +97,7 @@ describe("createMigrator", () => {
     it("should migrate forward by jumping multiple versions", async () => {
       const { migrator, getVersion } = createTestMigrator(0);
 
-      const result = await migrator.migrateTo(testSchema.version);
+      const result = await migrator.prepareMigrationTo(testSchema.version);
 
       expect(getVersion()).toBe(testSchema.version);
       const createTableOps = result.operations.filter((op) => op.type === "create-table");
@@ -110,20 +107,20 @@ describe("createMigrator", () => {
     it("should migrate forward one version at a time", async () => {
       const { migrator, getVersion } = createTestMigrator(0);
 
-      await migrator.migrateTo(1);
+      await migrator.prepareMigrationTo(1);
       expect(getVersion()).toBe(1);
 
-      await migrator.migrateTo(2);
+      await migrator.prepareMigrationTo(2);
       expect(getVersion()).toBe(2);
 
-      await migrator.migrateTo(3);
+      await migrator.prepareMigrationTo(3);
       expect(getVersion()).toBe(3);
     });
 
     it("should return empty operations when already at target version", async () => {
       const { migrator, getVersion } = createTestMigrator(2);
 
-      const result = await migrator.migrateTo(2);
+      const result = await migrator.prepareMigrationTo(2);
 
       expect(result.operations).toEqual([]);
       expect(getVersion()).toBe(2);
@@ -132,7 +129,7 @@ describe("createMigrator", () => {
     it("should throw error when trying to migrate backwards", async () => {
       const { migrator } = createTestMigrator(3);
 
-      await expect(migrator.migrateTo(1)).rejects.toThrow(
+      await expect(migrator.prepareMigrationTo(1)).rejects.toThrow(
         "Cannot migrate backwards: current version is 3, target is 1. Only forward migrations are supported.",
       );
     });
@@ -140,7 +137,7 @@ describe("createMigrator", () => {
     it("should throw error when migrating to negative version", async () => {
       const { migrator } = createTestMigrator(0);
 
-      await expect(migrator.migrateTo(-1)).rejects.toThrow(
+      await expect(migrator.prepareMigrationTo(-1)).rejects.toThrow(
         "Cannot migrate to negative version: -1",
       );
     });
@@ -148,7 +145,7 @@ describe("createMigrator", () => {
     it("should throw error when migrating beyond schema version", async () => {
       const { migrator } = createTestMigrator(0);
 
-      await expect(migrator.migrateTo(999)).rejects.toThrow(
+      await expect(migrator.prepareMigrationTo(999)).rejects.toThrow(
         `Cannot migrate to version 999: schema only has version ${testSchema.version}`,
       );
     });
@@ -166,7 +163,7 @@ describe("createMigrator", () => {
     it("should return updated version after migration", async () => {
       const { migrator } = createTestMigrator(0);
 
-      await migrator.migrateTo(2);
+      await migrator.prepareMigrationTo(2);
       const version = await migrator.getVersion();
 
       expect(version).toBe(2);
@@ -177,7 +174,7 @@ describe("createMigrator", () => {
     it("should execute migration operations", async () => {
       const { migrator, executedOperations } = createTestMigrator(0);
 
-      const result = await migrator.migrateTo(1);
+      const result = await migrator.prepareMigrationTo(1);
       await result.execute();
 
       expect(executedOperations).toHaveLength(1);
@@ -187,7 +184,7 @@ describe("createMigrator", () => {
     it("should not execute operations until execute() is called", async () => {
       const { migrator, executedOperations } = createTestMigrator(0);
 
-      await migrator.migrateTo(1);
+      await migrator.prepareMigrationTo(1);
 
       expect(executedOperations).toHaveLength(0);
     });
@@ -210,16 +207,13 @@ describe("createMigrator", () => {
 
       const options: MigrationEngineOptions = {
         schema: testSchema,
-        userConfig: {
-          provider: "postgresql",
-        },
         executor: async (operations) => {
           executedOperations.push(operations);
         },
         settings: {
           getVersion: async () => version,
-          updateSettingsInMigration: async (newVersion) => {
-            version = newVersion;
+          updateSettingsInMigration: async (_fromVersion, toVersion) => {
+            version = toVersion;
             return [];
           },
         },
@@ -231,7 +225,7 @@ describe("createMigrator", () => {
       };
 
       const migrator = createMigrator(options);
-      const result = await migrator.migrateTo(1);
+      const result = await migrator.prepareMigrationTo(1);
 
       expect(afterAutoSpy).toHaveBeenCalledOnce();
       expect(result.operations.some((op) => op.type === "custom")).toBe(true);
@@ -253,16 +247,13 @@ describe("createMigrator", () => {
 
       const options: MigrationEngineOptions = {
         schema: testSchema,
-        userConfig: {
-          provider: "postgresql",
-        },
         executor: async (operations) => {
           executedOperations.push(operations);
         },
         settings: {
           getVersion: async () => version,
-          updateSettingsInMigration: async (newVersion) => {
-            version = newVersion;
+          updateSettingsInMigration: async (_fromVersion, toVersion) => {
+            version = toVersion;
             return [];
           },
         },
@@ -274,7 +265,7 @@ describe("createMigrator", () => {
       };
 
       const migrator = createMigrator(options);
-      const result = await migrator.migrateTo(1);
+      const result = await migrator.prepareMigrationTo(1);
 
       expect(afterAllSpy).toHaveBeenCalledOnce();
       expect(result.operations.some((op) => op.type === "custom")).toBe(true);
@@ -285,7 +276,7 @@ describe("createMigrator", () => {
     it("should update settings by default", async () => {
       const { migrator } = createTestMigrator(0);
 
-      const result = await migrator.migrateTo(1);
+      const result = await migrator.prepareMigrationTo(1);
 
       const settingsOp = result.operations.find((op) => op.type === "custom");
       expect(settingsOp).toBeDefined();
@@ -294,7 +285,7 @@ describe("createMigrator", () => {
     it("should skip settings update when updateSettings is false", async () => {
       const { migrator } = createTestMigrator(0);
 
-      const result = await migrator.migrateTo(1, { updateSettings: false });
+      const result = await migrator.prepareMigrationTo(1, { updateSettings: false });
 
       // When updateSettings is false, we shouldn't have the settings update operation
       // Check that we only have create-table operations
@@ -313,31 +304,28 @@ describe("createMigrator", () => {
           .addTable("posts", (t) => {
             return t.addColumn("id", idColumn()).addColumn("authorId", referenceColumn());
           })
-          .addReference("posts", "author", {
-            columns: ["authorId"],
-            targetTable: "users",
-            targetColumns: ["id"],
+          .addReference("author", {
+            type: "one",
+            from: { table: "posts", column: "authorId" },
+            to: { table: "users", column: "id" },
           });
       });
 
       let version = 0;
       const options: MigrationEngineOptions = {
         schema: fkSchema,
-        userConfig: {
-          provider: "postgresql",
-        },
         executor: async () => {},
         settings: {
           getVersion: async () => version,
-          updateSettingsInMigration: async (newVersion) => {
-            version = newVersion;
+          updateSettingsInMigration: async (_fromVersion, toVersion) => {
+            version = toVersion;
             return [];
           },
         },
       };
 
       const migrator = createMigrator(options);
-      const result = await migrator.migrate();
+      const result = await migrator.prepareMigration();
 
       const createTableOps = result.operations.filter((op) => op.type === "create-table");
       const fkOps = result.operations.filter((op) => op.type === "add-foreign-key");

package/src/migration-engine/create.ts

@@ -1,5 +1,4 @@
 import { type MigrationOperation } from "./shared";
-import type { Provider } from "../shared/providers";
 import type { AnySchema } from "../schema/create";
 import { generateMigrationFromSchema as defaultGenerateMigrationFromSchema } from "./auto-from-schema";
 
@@ -19,7 +18,7 @@ export interface MigrateOptions {
   updateSettings?: boolean;
 }
 
-export interface MigrationResult {
+export interface PreparedMigration {
   operations: MigrationOperation[];
   getSQL?: () => string;
   execute: () => Promise<void>;
@@ -34,12 +33,22 @@ export interface Migrator {
   /**
    * Migrate to the latest schema version
    */
-  migrate: (options?: MigrateOptions) => Promise<MigrationResult>;
+  prepareMigration: (options?: MigrateOptions) => Promise<PreparedMigration>;
 
   /**
    * Migrate to a specific version (only forward migrations allowed)
+   * @param toVersion - Target version to migrate to
+   * @param options - Migration options including optional fromVersion
    */
-  migrateTo: (version: number, options?: MigrateOptions) => Promise<MigrationResult>;
+  prepareMigrationTo: (
+    toVersion: number,
+    options?: MigrateOptions & { fromVersion?: number },
+  ) => Promise<PreparedMigration>;
+
+  /**
+   * Get default file name for migration SQL
+   */
+  getDefaultFileName?: (namespace: string, fromVersion: number, toVersion: number) => string;
 }
 
 export interface MigrationEngineOptions {
@@ -48,10 +57,6 @@ export interface MigrationEngineOptions {
    */
   schema: AnySchema;
 
-  userConfig: {
-    provider: Provider;
-  };
-
   executor: (operations: MigrationOperation[]) => Promise<void>;
 
   generateMigrationFromSchema?: typeof defaultGenerateMigrationFromSchema;
@@ -62,7 +67,10 @@ export interface MigrationEngineOptions {
      */
     getVersion: () => Promise<number>;
 
-    updateSettingsInMigration: (version: number) => Awaitable<MigrationOperation[]>;
+    updateSettingsInMigration: (
+      fromVersion: number,
+      toVersion: number,
+    ) => Awaitable<MigrationOperation[]>;
   };
 
   sql?: {
@@ -103,7 +111,6 @@ export function createMigrator({
   settings,
   generateMigrationFromSchema = defaultGenerateMigrationFromSchema,
   schema: targetSchema,
-  userConfig,
   executor,
   sql: sqlConfig,
   transformers = [],
@@ -112,17 +119,23 @@ export function createMigrator({
     getVersion() {
       return settings.getVersion();
     },
-    async migrate(options = {}) {
-      return this.migrateTo(targetSchema.version, options);
+    async prepareMigration(options = {}) {
+      return this.prepareMigrationTo(targetSchema.version, options);
     },
-    async migrateTo(toVersion, options = {}) {
-      const { updateSettings: updateVersion = true } = options;
-      const fromVersion = await settings.getVersion();
+    async prepareMigrationTo(toVersion, options = {}) {
+      const { updateSettings: updateVersion = true, fromVersion: providedFromVersion } = options;
+
+      // Use provided fromVersion if available, otherwise query the database
+      const fromVersion = providedFromVersion ?? (await settings.getVersion());
 
       if (toVersion < 0) {
         throw new Error(`Cannot migrate to negative version: ${toVersion}`);
       }
 
+      if (fromVersion < 0) {
+        throw new Error(`Cannot migrate from negative version: ${fromVersion}`);
+      }
+
       if (toVersion < fromVersion) {
         throw new Error(
           `Cannot migrate backwards: current version is ${fromVersion}, target is ${toVersion}. Only forward migrations are supported.`,
@@ -135,6 +148,12 @@ export function createMigrator({
         );
       }
 
+      if (fromVersion > targetSchema.version) {
+        throw new Error(
+          `Cannot migrate from version ${fromVersion}: schema only has version ${targetSchema.version}`,
+        );
+      }
+
       if (toVersion === fromVersion) {
         // Already at target version, return empty migration
         return {
@@ -146,12 +165,7 @@ export function createMigrator({
 
       const context: MigrationContext = {
         async auto() {
-          let generated = generateMigrationFromSchema(
-            targetSchema,
-            fromVersion,
-            toVersion,
-            userConfig,
-          );
+          let generated = generateMigrationFromSchema(targetSchema, fromVersion, toVersion);
 
           for (const transformer of transformers) {
             if (!transformer.afterAuto) {
@@ -170,11 +184,12 @@ export function createMigrator({
         },
       };
 
-      let operations = await context.auto();
-
-      if (updateVersion) {
-        operations.push(...(await settings.updateSettingsInMigration(toVersion)));
-      }
+      let operations = updateVersion
+        ? [
+            ...(await settings.updateSettingsInMigration(fromVersion, toVersion)),
+            ...(await context.auto()),
+          ]
+        : await context.auto();
 
       for (const transformer of transformers) {
         if (!transformer.afterAll) {

package/src/migration-engine/shared.ts

@@ -1,5 +1,3 @@
-import type { AnyColumn, AnyTable } from "../schema/create";
-
 export interface ForeignKeyInfo {
   name: string;
   columns: string[];
@@ -7,6 +5,27 @@ export interface ForeignKeyInfo {
   referencedColumns: string[];
 }
 
+export interface ColumnInfo {
+  name: string;
+  type:
+    | "string"
+    | "integer"
+    | "bigint"
+    | "decimal"
+    | "bool"
+    | "date"
+    | "timestamp"
+    | "json"
+    | "binary"
+    | `varchar(${number})`;
+  isNullable: boolean;
+  role: "external-id" | "internal-id" | "version" | "reference" | "regular";
+  default?: {
+    value?: unknown;
+    runtime?: "now" | "auto";
+  };
+}
+
 export type MigrationOperation =
   | TableOperation
   | {
@@ -42,14 +61,15 @@ export type CustomOperation = {
 export type TableOperation =
   | {
       type: "create-table";
-      value: AnyTable;
+      name: string;
+      columns: ColumnInfo[];
     }
   | {
       type: "drop-table";
       name: string;
     }
   | {
-      type: "update-table";
+      type: "alter-table";
       name: string;
       value: ColumnOperation[];
     }
@@ -74,7 +94,7 @@ export type ColumnOperation =
        * Note: unique constraints are not created, please use dedicated operations like `add-index` instead
        */
       type: "create-column";
-      value: AnyColumn;
+      value: ColumnInfo;
     }
   | {
       /**
@@ -90,7 +110,7 @@ export type ColumnOperation =
        *
        * Note: unique constraints are not updated, please use dedicated operations like `add-index` instead
        */
-      value: AnyColumn;
+      value: ColumnInfo;
 
       updateNullable: boolean;
       updateDefault: boolean;

package/src/mod.ts

@@ -1 +1,197 @@
-export const hello = "world";
+import type { DatabaseAdapter } from "./adapters/adapters";
+import type { AnySchema } from "./schema/create";
+import type { AbstractQuery } from "./query/query";
+
+export type { DatabaseAdapter };
+
+export const fragnoDatabaseFakeSymbol = "$fragno-database" as const;
+export const fragnoDatabaseLibraryVersion = "0.1" as const;
+
+export interface CreateFragnoDatabaseDefinitionOptions<T extends AnySchema> {
+  namespace: string;
+  schema: T;
+}
+
+export function isFragnoDatabase(value: unknown): value is FragnoDatabase<AnySchema> {
+  if (value instanceof FragnoDatabase) {
+    return true;
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  return (
+    fragnoDatabaseFakeSymbol in value &&
+    value[fragnoDatabaseFakeSymbol] === fragnoDatabaseFakeSymbol
+  );
+}
+
+/**
+ * Definition of a Fragno database schema and namespace.
+ * Created by library authors using defineFragnoDatabase().
+ * Apps instantiate it by calling .create(adapter).
+ */
+export class FragnoDatabaseDefinition<const T extends AnySchema> {
+  #namespace: string;
+  #schema: T;
+
+  constructor(options: CreateFragnoDatabaseDefinitionOptions<T>) {
+    this.#namespace = options.namespace;
+    this.#schema = options.schema;
+  }
+
+  get namespace() {
+    return this.#namespace;
+  }
+
+  get schema() {
+    return this.#schema;
+  }
+
+  /**
+   * Creates a FragnoDatabase instance by binding an adapter to this definition.
+   */
+  create(adapter: DatabaseAdapter): FragnoDatabase<T> {
+    return new FragnoDatabase({
+      namespace: this.#namespace,
+      schema: this.#schema,
+      adapter,
+    });
+  }
+}
+
+/**
+ * A Fragno database instance with a bound adapter.
+ * Created from a FragnoDatabaseDefinition by calling .create(adapter).
+ */
+export class FragnoDatabase<const T extends AnySchema> {
+  #namespace: string;
+  #schema: T;
+  #adapter: DatabaseAdapter;
+
+  constructor(options: { namespace: string; schema: T; adapter: DatabaseAdapter }) {
+    this.#namespace = options.namespace;
+    this.#schema = options.schema;
+    this.#adapter = options.adapter;
+  }
+
+  get [fragnoDatabaseFakeSymbol](): typeof fragnoDatabaseFakeSymbol {
+    return fragnoDatabaseFakeSymbol;
+  }
+
+  async createClient(): Promise<AbstractQuery<T>> {
+    const dbVersion = await this.#adapter.getSchemaVersion(this.#namespace);
+    if (dbVersion !== this.#schema.version.toString()) {
+      throw new Error(
+        `Database is not at expected version. Did you forget to run migrations?` +
+          ` Current version: ${dbVersion}, Expected version: ${this.#schema.version}`,
+      );
+    }
+
+    return this.#adapter.createQueryEngine(this.#schema, this.#namespace);
+  }
+
+  async runMigrations(): Promise<boolean> {
+    if (!this.#adapter.createMigrationEngine) {
+      throw new Error("Migration engine not supported for this adapter.");
+    }
+
+    const migrator = this.#adapter.createMigrationEngine(this.#schema, this.#namespace);
+    const preparedMigration = await migrator.prepareMigration();
+    await preparedMigration.execute();
+
+    return preparedMigration.operations.length > 0;
+  }
+
+  get namespace() {
+    return this.#namespace;
+  }
+
+  get schema() {
+    return this.#schema;
+  }
+
+  get adapter() {
+    return this.#adapter;
+  }
+
+  async generateSchema(options?: {
+    path?: string;
+    toVersion?: number;
+    fromVersion?: number;
+  }): Promise<{ schema: string; path: string }> {
+    const adapter = this.#adapter;
+
+    if (adapter.createSchemaGenerator) {
+      if (options?.toVersion !== undefined || options?.fromVersion !== undefined) {
+        console.warn("⚠️ toVersion and fromVersion are not supported for schema generation.");
+      }
+
+      const generator = adapter.createSchemaGenerator(this.#schema, this.#namespace);
+      const defaultPath = options?.path ?? "schema.ts";
+      return generator.generateSchema({
+        path: defaultPath,
+        toVersion: options?.toVersion,
+        fromVersion: options?.fromVersion,
+      });
+    }
+
+    if (adapter.createMigrationEngine) {
+      const migrator = adapter.createMigrationEngine(this.#schema, this.#namespace);
+      const targetVersion = options?.toVersion ?? this.#schema.version;
+      const sourceVersion = options?.fromVersion;
+
+      // Get current version for file naming if not provided
+      const currentVersion = sourceVersion ?? (await migrator.getVersion());
+
+      // Determine the default path using the migrator's getDefaultFileName if available
+      const defaultPath =
+        options?.path ??
+        (migrator.getDefaultFileName
+          ? migrator.getDefaultFileName(this.#namespace, currentVersion, targetVersion)
+          : "schema.sql");
+
+      // Generate migration from source to target version
+      const preparedMigration = await migrator.prepareMigrationTo(targetVersion, {
+        updateSettings: true,
+        fromVersion: sourceVersion,
+      });
+
+      if (!preparedMigration.getSQL) {
+        throw new Error(
+          "Migration engine does not support SQL generation. Ensure your adapter's migration engine provides getSQL().",
+        );
+      }
+
+      const sql = preparedMigration.getSQL();
+
+      // If no migrations needed, return informative message
+      if (!sql.trim()) {
+        throw new Error("No migrations needed. Database is already at the target version.");
+      }
+
+      return {
+        schema: sql,
+        path: defaultPath,
+      };
+    }
+
+    throw new Error(
+      "Adapter does not support schema generation. Ensure your adapter implements either createSchemaGenerator or createMigrationEngine.",
+    );
+  }
+}
+
+export function defineFragnoDatabase<const TSchema extends AnySchema>(
+  options: CreateFragnoDatabaseDefinitionOptions<TSchema>,
+): FragnoDatabaseDefinition<TSchema> {
+  return new FragnoDatabaseDefinition(options);
+}
+
+export {
+  defineFragmentWithDatabase,
+  DatabaseFragmentBuilder,
+  type FragnoPublicConfigWithDatabase,
+  type DatabaseFragmentContext,
+} from "./fragment";