@fragno-dev/db 0.0.1

package/src/migration-engine/create.ts

@@ -0,0 +1,199 @@
+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";
+
+type Awaitable<T> = T | Promise<T>;
+
+interface MigrationContext {
+  auto: () => Promise<MigrationOperation[]>;
+}
+
+export type CustomMigrationFn = (context: MigrationContext) => Awaitable<MigrationOperation[]>;
+
+export interface MigrateOptions {
+  /**
+   * Update internal settings, it's true by default.
+   * We don't recommend to disable it other than testing purposes.
+   */
+  updateSettings?: boolean;
+}
+
+export interface MigrationResult {
+  operations: MigrationOperation[];
+  getSQL?: () => string;
+  execute: () => Promise<void>;
+}
+
+export interface Migrator {
+  /**
+   * Get current version (returns 0 if not initialized)
+   */
+  getVersion: () => Promise<number>;
+
+  /**
+   * Migrate to the latest schema version
+   */
+  migrate: (options?: MigrateOptions) => Promise<MigrationResult>;
+
+  /**
+   * Migrate to a specific version (only forward migrations allowed)
+   */
+  migrateTo: (version: number, options?: MigrateOptions) => Promise<MigrationResult>;
+}
+
+export interface MigrationEngineOptions {
+  /**
+   * The target schema to migrate to
+   */
+  schema: AnySchema;
+
+  userConfig: {
+    provider: Provider;
+  };
+
+  executor: (operations: MigrationOperation[]) => Promise<void>;
+
+  generateMigrationFromSchema?: typeof defaultGenerateMigrationFromSchema;
+
+  settings: {
+    /**
+     * Get current version from database (0 if not initialized)
+     */
+    getVersion: () => Promise<number>;
+
+    updateSettingsInMigration: (version: number) => Awaitable<MigrationOperation[]>;
+  };
+
+  sql?: {
+    toSql: (operations: MigrationOperation[]) => string;
+  };
+
+  transformers?: MigrationTransformer[];
+}
+
+export interface MigrationTransformer {
+  /**
+   * Run after auto-generating migration operations
+   */
+  afterAuto?: (
+    operations: MigrationOperation[],
+    context: {
+      options: MigrateOptions;
+      fromVersion: number;
+      toVersion: number;
+      schema: AnySchema;
+    },
+  ) => MigrationOperation[];
+
+  /**
+   * Run on all migration operations
+   */
+  afterAll?: (
+    operations: MigrationOperation[],
+    context: {
+      fromVersion: number;
+      toVersion: number;
+      schema: AnySchema;
+    },
+  ) => MigrationOperation[];
+}
+
+export function createMigrator({
+  settings,
+  generateMigrationFromSchema = defaultGenerateMigrationFromSchema,
+  schema: targetSchema,
+  userConfig,
+  executor,
+  sql: sqlConfig,
+  transformers = [],
+}: MigrationEngineOptions): Migrator {
+  const instance: Migrator = {
+    getVersion() {
+      return settings.getVersion();
+    },
+    async migrate(options = {}) {
+      return this.migrateTo(targetSchema.version, options);
+    },
+    async migrateTo(toVersion, options = {}) {
+      const { updateSettings: updateVersion = true } = options;
+      const fromVersion = await settings.getVersion();
+
+      if (toVersion < 0) {
+        throw new Error(`Cannot migrate to negative version: ${toVersion}`);
+      }
+
+      if (toVersion < fromVersion) {
+        throw new Error(
+          `Cannot migrate backwards: current version is ${fromVersion}, target is ${toVersion}. Only forward migrations are supported.`,
+        );
+      }
+
+      if (toVersion > targetSchema.version) {
+        throw new Error(
+          `Cannot migrate to version ${toVersion}: schema only has version ${targetSchema.version}`,
+        );
+      }
+
+      if (toVersion === fromVersion) {
+        // Already at target version, return empty migration
+        return {
+          operations: [],
+          getSQL: sqlConfig ? () => sqlConfig.toSql([]) : undefined,
+          execute: async () => {},
+        };
+      }
+
+      const context: MigrationContext = {
+        async auto() {
+          let generated = generateMigrationFromSchema(
+            targetSchema,
+            fromVersion,
+            toVersion,
+            userConfig,
+          );
+
+          for (const transformer of transformers) {
+            if (!transformer.afterAuto) {
+              continue;
+            }
+
+            generated = transformer.afterAuto(generated, {
+              fromVersion,
+              toVersion,
+              schema: targetSchema,
+              options,
+            });
+          }
+
+          return generated;
+        },
+      };
+
+      let operations = await context.auto();
+
+      if (updateVersion) {
+        operations.push(...(await settings.updateSettingsInMigration(toVersion)));
+      }
+
+      for (const transformer of transformers) {
+        if (!transformer.afterAll) {
+          continue;
+        }
+        operations = transformer.afterAll(operations, {
+          fromVersion,
+          toVersion,
+          schema: targetSchema,
+        });
+      }
+
+      return {
+        operations,
+        getSQL: sqlConfig ? () => sqlConfig.toSql(operations) : undefined,
+        execute: () => executor(operations),
+      };
+    },
+  };
+
+  return instance;
+}

package/src/migration-engine/shared.ts

@@ -0,0 +1,102 @@
+import type { AnyColumn, AnyTable } from "../schema/create";
+
+export interface ForeignKeyInfo {
+  name: string;
+  columns: string[];
+  referencedTable: string;
+  referencedColumns: string[];
+}
+
+export type MigrationOperation =
+  | TableOperation
+  | {
+      // warning: not supported by SQLite
+      type: "add-foreign-key";
+      table: string;
+      value: ForeignKeyInfo;
+    }
+  | {
+      // warning: not supported by SQLite
+      type: "drop-foreign-key";
+      table: string;
+      name: string;
+    }
+  | {
+      type: "drop-index";
+      table: string;
+      name: string;
+    }
+  | {
+      type: "add-index";
+      table: string;
+      columns: string[];
+      name: string;
+      unique: boolean;
+    }
+  | CustomOperation;
+
+export type CustomOperation = {
+  type: "custom";
+} & Record<string, unknown>;
+
+export type TableOperation =
+  | {
+      type: "create-table";
+      value: AnyTable;
+    }
+  | {
+      type: "drop-table";
+      name: string;
+    }
+  | {
+      type: "update-table";
+      name: string;
+      value: ColumnOperation[];
+    }
+  | {
+      type: "rename-table";
+      from: string;
+      to: string;
+    };
+
+export type ColumnOperation =
+  | {
+      type: "rename-column";
+      from: string;
+      to: string;
+    }
+  | {
+      type: "drop-column";
+      name: string;
+    }
+  | {
+      /**
+       * Note: unique constraints are not created, please use dedicated operations like `add-index` instead
+       */
+      type: "create-column";
+      value: AnyColumn;
+    }
+  | {
+      /**
+       * warning: Not supported by SQLite
+       */
+      type: "update-column";
+      name: string;
+      /**
+       * For databases like MySQL, it requires the full definition for any modify column statement.
+       * Hence, you need to specify the full information of your column here.
+       *
+       * Then, opt-in for in-detail modification for other databases that supports changing data type/nullable/default separately, such as PostgreSQL.
+       *
+       * Note: unique constraints are not updated, please use dedicated operations like `add-index` instead
+       */
+      value: AnyColumn;
+
+      updateNullable: boolean;
+      updateDefault: boolean;
+      updateDataType: boolean;
+    };
+
+export function isUpdated(op: Extract<ColumnOperation, { type: "update-column" }>): boolean {
+  return op.updateDataType || op.updateDefault || op.updateNullable;
+}

package/src/mod.ts

@@ -0,0 +1 @@
+export const hello = "world";

package/src/schema/create.test.ts

@@ -0,0 +1,287 @@
+import { describe, expect, it } from "vitest";
+import { column, compileForeignKey, idColumn, referenceColumn, schema, table } from "./create";
+
+describe("create", () => {
+  it("should create a table with columns using callback pattern", () => {
+    const userTable = table("users", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("name", column("string"))
+        .addColumn("email", column("string"))
+        .createIndex("unique_email", ["email"], { unique: true })
+        .addColumn("age", column("integer").nullable());
+    });
+
+    expect(userTable.columns.id).toBeDefined();
+    expect(userTable.columns.name).toBeDefined();
+    expect(userTable.columns.email).toBeDefined();
+    expect(userTable.columns.age).toBeDefined();
+    expect(userTable.columns.age.isNullable).toBe(true);
+    expect(userTable.indexes).toEqual([
+      {
+        name: "unique_email",
+        columns: [userTable.columns.email],
+        unique: true,
+      },
+    ]);
+  });
+
+  it("should create a schema with multiple tables using callback pattern", () => {
+    const userSchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("posts", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("title", column("string"))
+            .addColumn("content", column("string"));
+        });
+    });
+
+    expect(userSchema.version).toBe(2); // Two addTable calls
+    expect(userSchema.tables.users).toBeDefined();
+    expect(userSchema.tables.posts).toBeDefined();
+    expect(userSchema.tables.users.ormName).toBe("users");
+    expect(userSchema.tables.posts.ormName).toBe("posts");
+  });
+
+  it("should generate default values for columns", () => {
+    const testTable = table("test", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("createdAt", column("timestamp").defaultTo$("now"))
+        .addColumn("status", column("string").defaultTo("active"));
+    });
+
+    const idValue = testTable.columns.id.generateDefaultValue();
+    expect(typeof idValue).toBe("string");
+    expect(idValue?.length).toBeGreaterThan(0);
+
+    const createdAtValue = testTable.columns.createdAt.generateDefaultValue();
+    expect(createdAtValue).toBeInstanceOf(Date);
+
+    const statusValue = testTable.columns.status.generateDefaultValue();
+    expect(statusValue).toBe("active");
+  });
+
+  it("should increment version on each builder operation", () => {
+    const userSchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("name", column("string"))
+            .addColumn("age", column("integer"));
+        })
+        .addTable("posts", (t) => {
+          return t.addColumn("id", idColumn());
+        });
+    });
+
+    expect(userSchema.version).toBe(2); // Two addTable calls
+  });
+
+  it("should support unique constraints on tables via unique method", () => {
+    const userTable = table("users", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("email", column("string"))
+        .addColumn("username", column("string"))
+        .createIndex("unique_email_username", ["email", "username"], { unique: true });
+    });
+
+    const uniqueIndexes = userTable.indexes.filter((idx) => idx.unique);
+    expect(uniqueIndexes).toHaveLength(1);
+    expect(uniqueIndexes[0].name).toBe("unique_email_username");
+    expect(uniqueIndexes[0].columns).toHaveLength(2);
+  });
+
+  it("should support creating indexes on tables", () => {
+    const userTable = table("users", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("email", column("string"))
+        .addColumn("username", column("string"))
+        .createIndex("idx_email", ["email"])
+        .createIndex("idx_username_unique", ["username"], { unique: true });
+    });
+
+    expect(userTable.indexes).toHaveLength(2);
+    expect(userTable.indexes[0]).toEqual({
+      name: "idx_email",
+      columns: [userTable.columns.email],
+      unique: false,
+    });
+    expect(userTable.indexes[1]).toEqual({
+      name: "idx_username_unique",
+      columns: [userTable.columns.username],
+      unique: true,
+    });
+  });
+
+  it("should demonstrate manual many-to-many relation setup", () => {
+    // For many-to-many, create a junction table manually
+    const userSchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("tags", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("user_tags", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("userId", referenceColumn())
+            .addColumn("tagId", referenceColumn());
+        })
+        .addReference("user_tags", "user", {
+          columns: ["userId"],
+          targetTable: "users",
+          targetColumns: ["id"],
+        })
+        .addReference("user_tags", "tag", {
+          columns: ["tagId"],
+          targetTable: "tags",
+          targetColumns: ["id"],
+        });
+    });
+
+    const junctionTable = userSchema.tables.user_tags;
+
+    // Verify the junction table has both relations
+    expect(junctionTable.relations["user"]).toBeDefined();
+    expect(junctionTable.relations["tag"]).toBeDefined();
+
+    // Verify both foreign keys were created
+    expect(junctionTable.foreignKeys).toHaveLength(2);
+    expect(junctionTable.foreignKeys[0].referencedTable).toBe(userSchema.tables.users);
+    expect(junctionTable.foreignKeys[1].referencedTable).toBe(userSchema.tables.tags);
+  });
+
+  it("should create a foreign key reference using addReference", () => {
+    const userSchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("posts", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("title", column("string"))
+            .addColumn("authorId", referenceColumn());
+        })
+        .addReference("posts", "author", {
+          columns: ["authorId"],
+          targetTable: "users",
+          targetColumns: ["id"],
+        });
+    });
+
+    const postsTable = userSchema.tables.posts;
+
+    // Verify the authorId column is marked as a reference
+    expect(postsTable.columns.authorId.isReference).toBe(true);
+
+    // Verify the relation exists
+    const authorRelation = postsTable.relations["author"];
+    expect(authorRelation).toBeDefined();
+    expect(authorRelation.type).toBe("one");
+    expect(authorRelation.table).toBe(userSchema.tables.users);
+    expect(authorRelation.on).toEqual([["authorId", "id"]]);
+
+    // Verify the foreign key was created
+    expect(postsTable.foreignKeys).toHaveLength(1);
+    const fk = postsTable.foreignKeys[0];
+    expect(fk.table).toBe(postsTable);
+    expect(fk.referencedTable).toBe(userSchema.tables.users);
+    expect(fk.columns).toEqual([postsTable.columns.authorId]);
+    expect(fk.referencedColumns).toEqual([userSchema.tables.users.columns.id]);
+
+    // Verify the compiled foreign key format
+    const compiledFk = compileForeignKey(fk);
+    expect(compiledFk).toEqual({
+      name: "posts_users_author_fk",
+      table: "posts",
+      referencedTable: "users",
+      columns: ["authorId"],
+      referencedColumns: ["id"],
+    });
+  });
+
+  it("should support multiple references by calling addReference multiple times", () => {
+    const userSchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("categories", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .addTable("posts", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("title", column("string"))
+            .addColumn("authorId", referenceColumn())
+            .addColumn("categoryId", referenceColumn());
+        })
+        .addReference("posts", "author", {
+          columns: ["authorId"],
+          targetTable: "users",
+          targetColumns: ["id"],
+        })
+        .addReference("posts", "category", {
+          columns: ["categoryId"],
+          targetTable: "categories",
+          targetColumns: ["id"],
+        });
+    });
+
+    const postsTable = userSchema.tables.posts;
+
+    // Verify both relations exist
+    expect(postsTable.relations["author"]).toBeDefined();
+    expect(postsTable.relations["category"]).toBeDefined();
+
+    // Verify both foreign keys were created
+    expect(postsTable.foreignKeys).toHaveLength(2);
+    expect(postsTable.foreignKeys[0].referencedTable).toBe(userSchema.tables.users);
+    expect(postsTable.foreignKeys[1].referencedTable).toBe(userSchema.tables.categories);
+  });
+
+  it("should support self-referencing foreign keys", () => {
+    const userSchema = schema((s) => {
+      return s
+        .addTable("users", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("name", column("string"))
+            .addColumn("invitedBy", referenceColumn().nullable());
+        })
+        .addReference("users", "inviter", {
+          columns: ["invitedBy"],
+          targetTable: "users",
+          targetColumns: ["id"],
+        });
+    });
+
+    const usersTable = userSchema.tables.users;
+
+    // Verify the self-referencing relation exists
+    const inviterRelation = usersTable.relations["inviter"];
+    expect(inviterRelation).toBeDefined();
+    expect(inviterRelation.type).toBe("one");
+    expect(inviterRelation.table).toBe(usersTable);
+    expect(inviterRelation.on).toEqual([["invitedBy", "id"]]);
+
+    // Verify the foreign key was created
+    expect(usersTable.foreignKeys).toHaveLength(1);
+    const fk = usersTable.foreignKeys[0];
+    expect(fk.table).toBe(usersTable);
+    expect(fk.referencedTable).toBe(usersTable);
+    expect(fk.columns).toEqual([usersTable.columns.invitedBy]);
+    expect(fk.referencedColumns).toEqual([usersTable.columns.id]);
+  });
+});