@sedrino/db-schema 0.1.1

package/src/migration.ts

@@ -0,0 +1,456 @@
+import type {
+  DefaultSpec,
+  FieldReferenceSpec,
+  FieldSpec,
+  IndexSpec,
+  LogicalTypeSpec,
+  StorageSpec,
+  TableSpec,
+  UniqueSpec,
+} from "./types";
+import {
+  defaultStorageForLogical,
+  fieldAutoId,
+  tableAutoId,
+  toSnakeCase,
+  validateDefaultCompatibility,
+  validateLogicalAndStorageCompatibility,
+} from "./utils";
+
+export type MigrationMeta = {
+  id: string;
+  name: string;
+  description?: string;
+};
+
+export type MigrationOperation =
+  | { kind: "createTable"; table: TableSpec }
+  | { kind: "dropTable"; tableName: string }
+  | { kind: "renameTable"; from: string; to: string }
+  | { kind: "addField"; tableName: string; field: FieldSpec }
+  | { kind: "dropField"; tableName: string; fieldName: string }
+  | { kind: "renameField"; tableName: string; from: string; to: string }
+  | { kind: "addIndex"; tableName: string; index: IndexSpec }
+  | { kind: "dropIndex"; tableName: string; indexName: string }
+  | { kind: "addUnique"; tableName: string; unique: UniqueSpec }
+  | { kind: "dropUnique"; tableName: string; uniqueName: string };
+
+export type MigrationDefinition = {
+  meta: MigrationMeta;
+  buildOperations(): MigrationOperation[];
+};
+
+type FieldOptions = {
+  column?: string;
+  description?: string;
+  storage?: StorageSpec;
+  references?: FieldReferenceSpec;
+};
+
+class MutableFieldBuilder {
+  constructor(private field: FieldSpec) {}
+
+  required() {
+    this.field.nullable = false;
+    return this;
+  }
+
+  nullable() {
+    this.field.nullable = true;
+    return this;
+  }
+
+  unique() {
+    this.field.unique = true;
+    return this;
+  }
+
+  default(value: string | number | boolean | null) {
+    const nextDefault: DefaultSpec = {
+      kind: "literal",
+      value,
+    };
+    const issue = validateDefaultCompatibility(this.field, nextDefault);
+    if (issue) throw new Error(issue);
+    this.field.default = nextDefault;
+    return this;
+  }
+
+  defaultNow() {
+    const nextDefault: DefaultSpec = {
+      kind: "now",
+    };
+    const issue = validateDefaultCompatibility(this.field, nextDefault);
+    if (issue) throw new Error(issue);
+    this.field.default = nextDefault;
+    return this;
+  }
+
+  references(reference: FieldReferenceSpec) {
+    this.field.references = reference;
+    return this;
+  }
+
+  description(description: string) {
+    this.field.description = description;
+    return this;
+  }
+
+  column(column: string) {
+    this.field.storage = {
+      ...this.field.storage,
+      column,
+    };
+    return this;
+  }
+
+  build() {
+    return this.field;
+  }
+}
+
+function createFieldSpec(
+  tableName: string,
+  fieldName: string,
+  logical: LogicalTypeSpec,
+  options: FieldOptions = {},
+): FieldSpec {
+  const column = options.column ?? toSnakeCase(fieldName);
+  const storage = options.storage ?? defaultStorageForLogical(logical, column);
+  const storageIssue = validateLogicalAndStorageCompatibility(logical, storage);
+  if (storageIssue) throw new Error(storageIssue);
+
+  const field: FieldSpec = {
+    id: fieldAutoId(tableName, fieldName),
+    name: fieldName,
+    logical,
+    storage,
+    nullable: true,
+    primaryKey: false,
+    unique: false,
+    description: options.description,
+    references: options.references,
+  };
+
+  if (logical.kind === "id") {
+    field.primaryKey = true;
+    field.nullable = false;
+    field.default = {
+      kind: "generatedId",
+      prefix: logical.prefix,
+    };
+  }
+
+  return field;
+}
+
+class TableCreateBuilder {
+  private readonly fields: FieldSpec[] = [];
+  private readonly indexes: IndexSpec[] = [];
+  private readonly uniques: UniqueSpec[] = [];
+  private descriptionText?: string;
+
+  constructor(private readonly tableName: string) {}
+
+  description(text: string) {
+    this.descriptionText = text;
+    return this;
+  }
+
+  private addField(field: FieldSpec) {
+    this.fields.push(field);
+    return new MutableFieldBuilder(field);
+  }
+
+  id(fieldName: string, options: Omit<FieldOptions, "storage"> & { prefix: string }) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "id", prefix: options.prefix }, options),
+    );
+  }
+
+  string(fieldName: string, options: FieldOptions & { format?: "email" | "url" | "slug" } = {}) {
+    return this.addField(
+      createFieldSpec(
+        this.tableName,
+        fieldName,
+        { kind: "string", format: options.format },
+        options,
+      ),
+    );
+  }
+
+  text(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "text" }, options));
+  }
+
+  boolean(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "boolean" }, options));
+  }
+
+  integer(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "integer" }, options));
+  }
+
+  number(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "number" }, options));
+  }
+
+  enum(fieldName: string, values: string[], options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "enum", values }, options),
+    );
+  }
+
+  json(fieldName: string, tsType: string, options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "json", tsType }, options),
+    );
+  }
+
+  temporalInstant(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "temporal.instant" }, options),
+    );
+  }
+
+  temporalPlainDate(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "temporal.plainDate" }, options),
+    );
+  }
+
+  reference(
+    fieldName: string,
+    options: Omit<FieldOptions, "references"> & { references: FieldReferenceSpec },
+  ) {
+    return this.addField(
+      createFieldSpec(
+        this.tableName,
+        fieldName,
+        { kind: "string" },
+        { ...options, references: options.references },
+      ),
+    );
+  }
+
+  index(fields: string[], options: { name?: string } = {}) {
+    this.indexes.push({
+      fields,
+      name: options.name,
+    });
+    return this;
+  }
+
+  unique(fields: string[], options: { name?: string } = {}) {
+    this.uniques.push({
+      fields,
+      name: options.name,
+    });
+    return this;
+  }
+
+  build(): TableSpec {
+    return {
+      id: tableAutoId(this.tableName),
+      name: this.tableName,
+      description: this.descriptionText,
+      fields: this.fields,
+      indexes: this.indexes,
+      uniques: this.uniques,
+    };
+  }
+}
+
+class TableAlterBuilder {
+  readonly operations: MigrationOperation[] = [];
+
+  constructor(private readonly tableName: string) {}
+
+  private addField(field: FieldSpec) {
+    const operation: MigrationOperation = {
+      kind: "addField",
+      tableName: this.tableName,
+      field,
+    };
+    this.operations.push(operation);
+    return new MutableFieldBuilder(field);
+  }
+
+  string(fieldName: string, options: FieldOptions & { format?: "email" | "url" | "slug" } = {}) {
+    return this.addField(
+      createFieldSpec(
+        this.tableName,
+        fieldName,
+        { kind: "string", format: options.format },
+        options,
+      ),
+    );
+  }
+
+  text(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "text" }, options));
+  }
+
+  boolean(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "boolean" }, options));
+  }
+
+  integer(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "integer" }, options));
+  }
+
+  number(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(createFieldSpec(this.tableName, fieldName, { kind: "number" }, options));
+  }
+
+  enum(fieldName: string, values: string[], options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "enum", values }, options),
+    );
+  }
+
+  json(fieldName: string, tsType: string, options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "json", tsType }, options),
+    );
+  }
+
+  temporalInstant(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "temporal.instant" }, options),
+    );
+  }
+
+  temporalPlainDate(fieldName: string, options: FieldOptions = {}) {
+    return this.addField(
+      createFieldSpec(this.tableName, fieldName, { kind: "temporal.plainDate" }, options),
+    );
+  }
+
+  reference(
+    fieldName: string,
+    options: Omit<FieldOptions, "references"> & { references: FieldReferenceSpec },
+  ) {
+    return this.addField(
+      createFieldSpec(
+        this.tableName,
+        fieldName,
+        { kind: "string" },
+        { ...options, references: options.references },
+      ),
+    );
+  }
+
+  dropField(fieldName: string) {
+    this.operations.push({
+      kind: "dropField",
+      tableName: this.tableName,
+      fieldName,
+    });
+    return this;
+  }
+
+  renameField(from: string, to: string) {
+    this.operations.push({
+      kind: "renameField",
+      tableName: this.tableName,
+      from,
+      to,
+    });
+    return this;
+  }
+
+  addIndex(fields: string[], options: { name?: string } = {}) {
+    this.operations.push({
+      kind: "addIndex",
+      tableName: this.tableName,
+      index: {
+        fields,
+        name: options.name,
+      },
+    });
+    return this;
+  }
+
+  dropIndex(indexName: string) {
+    this.operations.push({
+      kind: "dropIndex",
+      tableName: this.tableName,
+      indexName,
+    });
+    return this;
+  }
+
+  addUnique(fields: string[], options: { name?: string } = {}) {
+    this.operations.push({
+      kind: "addUnique",
+      tableName: this.tableName,
+      unique: {
+        fields,
+        name: options.name,
+      },
+    });
+    return this;
+  }
+
+  dropUnique(uniqueName: string) {
+    this.operations.push({
+      kind: "dropUnique",
+      tableName: this.tableName,
+      uniqueName,
+    });
+    return this;
+  }
+}
+
+class MigrationBuilderImpl {
+  readonly operations: MigrationOperation[] = [];
+
+  createTable(name: string, callback: (table: TableCreateBuilder) => void) {
+    const table = new TableCreateBuilder(name);
+    callback(table);
+    this.operations.push({
+      kind: "createTable",
+      table: table.build(),
+    });
+    return this;
+  }
+
+  dropTable(tableName: string) {
+    this.operations.push({
+      kind: "dropTable",
+      tableName,
+    });
+    return this;
+  }
+
+  renameTable(from: string, to: string) {
+    this.operations.push({
+      kind: "renameTable",
+      from,
+      to,
+    });
+    return this;
+  }
+
+  alterTable(tableName: string, callback: (table: TableAlterBuilder) => void) {
+    const table = new TableAlterBuilder(tableName);
+    callback(table);
+    this.operations.push(...table.operations);
+    return this;
+  }
+}
+
+export function createMigration(
+  meta: MigrationMeta,
+  callback: (migration: MigrationBuilderImpl) => void,
+): MigrationDefinition {
+  return {
+    meta,
+    buildOperations() {
+      const builder = new MigrationBuilderImpl();
+      callback(builder);
+      return builder.operations;
+    },
+  };
+}

package/src/planner.ts

@@ -0,0 +1,247 @@
+import type { DatabaseSchemaDocument, IndexSpec, TableSpec, UniqueSpec } from "./types";
+import { type MigrationDefinition, type MigrationOperation } from "./migration";
+import { assertValidSchemaDocument, createEmptySchema, findField, findTable } from "./schema";
+import { renderSqliteMigration } from "./sqlite";
+import { cloneSchema, createSchemaHash, renameStorageColumn } from "./utils";
+
+export type PlannedMigration = {
+  migrationId: string;
+  migrationName: string;
+  fromSchemaHash: string;
+  toSchemaHash: string;
+  operations: MigrationOperation[];
+  nextSchema: DatabaseSchemaDocument;
+  sql: {
+    statements: string[];
+    warnings: string[];
+  };
+};
+
+export function planMigration(args: {
+  currentSchema?: DatabaseSchemaDocument;
+  migration: MigrationDefinition;
+}): PlannedMigration {
+  const currentSchema = args.currentSchema
+    ? assertValidSchemaDocument(args.currentSchema)
+    : createEmptySchema(args.migration.meta.id);
+  const operations = args.migration.buildOperations();
+  const nextSchema = applyOperationsToSchema(currentSchema, operations);
+
+  return {
+    migrationId: args.migration.meta.id,
+    migrationName: args.migration.meta.name,
+    fromSchemaHash: createSchemaHash(currentSchema),
+    toSchemaHash: createSchemaHash(nextSchema),
+    operations,
+    nextSchema,
+    sql: renderSqliteMigration(operations),
+  };
+}
+
+export function materializeSchema(args: {
+  baseSchema?: DatabaseSchemaDocument;
+  migrations: MigrationDefinition[];
+}) {
+  let schema = args.baseSchema ? assertValidSchemaDocument(args.baseSchema) : createEmptySchema();
+  const plans: PlannedMigration[] = [];
+
+  for (const migration of args.migrations) {
+    const plan = planMigration({
+      currentSchema: schema,
+      migration,
+    });
+    plans.push(plan);
+    schema = plan.nextSchema;
+  }
+
+  return {
+    schema,
+    plans,
+  };
+}
+
+export function applyOperationsToSchema(
+  schemaInput: DatabaseSchemaDocument,
+  operations: MigrationOperation[],
+) {
+  const schema = cloneSchema(schemaInput);
+
+  for (const operation of operations) {
+    switch (operation.kind) {
+      case "createTable":
+        if (findTable(schema, operation.table.name)) {
+          throw new Error(`Table ${operation.table.name} already exists`);
+        }
+        schema.tables.push(cloneSchema(operation.table));
+        break;
+      case "dropTable": {
+        const referencedBy = schema.tables.flatMap((table) =>
+          table.fields
+            .filter((field) => field.references?.table === operation.tableName)
+            .map((field) => `${table.name}.${field.name}`),
+        );
+
+        if (referencedBy.length > 0) {
+          throw new Error(
+            `Cannot drop table ${operation.tableName}; still referenced by ${referencedBy.join(", ")}`,
+          );
+        }
+
+        const index = schema.tables.findIndex((table) => table.name === operation.tableName);
+        if (index < 0) throw new Error(`Table ${operation.tableName} does not exist`);
+        schema.tables.splice(index, 1);
+        break;
+      }
+      case "renameTable": {
+        const table = findTable(schema, operation.from);
+        if (!table) throw new Error(`Table ${operation.from} does not exist`);
+        if (findTable(schema, operation.to)) {
+          throw new Error(`Table ${operation.to} already exists`);
+        }
+
+        table.name = operation.to;
+        for (const candidateTable of schema.tables) {
+          for (const field of candidateTable.fields) {
+            if (field.references?.table === operation.from) {
+              field.references = {
+                ...field.references,
+                table: operation.to,
+              };
+            }
+          }
+        }
+        break;
+      }
+      case "addField": {
+        const table = findTable(schema, operation.tableName);
+        if (!table) throw new Error(`Table ${operation.tableName} does not exist`);
+        if (findField(table, operation.field.name)) {
+          throw new Error(`Field ${operation.tableName}.${operation.field.name} already exists`);
+        }
+        table.fields.push(cloneSchema(operation.field));
+        break;
+      }
+      case "dropField": {
+        const table = findTable(schema, operation.tableName);
+        if (!table) throw new Error(`Table ${operation.tableName} does not exist`);
+        const fieldIndex = table.fields.findIndex((field) => field.name === operation.fieldName);
+        if (fieldIndex < 0) {
+          throw new Error(`Field ${operation.tableName}.${operation.fieldName} does not exist`);
+        }
+        const referencedBy = schema.tables.flatMap((candidateTable) =>
+          candidateTable.fields
+            .filter(
+              (field) =>
+                field.references?.table === operation.tableName &&
+                field.references.field === operation.fieldName,
+            )
+            .map((field) => `${candidateTable.name}.${field.name}`),
+        );
+        if (referencedBy.length > 0) {
+          throw new Error(
+            `Cannot drop field ${operation.tableName}.${operation.fieldName}; still referenced by ${referencedBy.join(", ")}`,
+          );
+        }
+        table.fields.splice(fieldIndex, 1);
+        table.indexes = table.indexes.filter(
+          (index) => !index.fields.includes(operation.fieldName),
+        );
+        table.uniques = table.uniques.filter(
+          (unique) => !unique.fields.includes(operation.fieldName),
+        );
+        break;
+      }
+      case "renameField": {
+        const table = findTable(schema, operation.tableName);
+        if (!table) throw new Error(`Table ${operation.tableName} does not exist`);
+        const field = findField(table, operation.from);
+        if (!field)
+          throw new Error(`Field ${operation.tableName}.${operation.from} does not exist`);
+        if (findField(table, operation.to)) {
+          throw new Error(`Field ${operation.tableName}.${operation.to} already exists`);
+        }
+
+        const renamed = renameStorageColumn(field, operation.to);
+        const index = table.fields.findIndex((candidate) => candidate.id === field.id);
+        table.fields[index] = renamed;
+        table.indexes = renameFieldInIndexes(table.indexes, operation.from, operation.to);
+        table.uniques = renameFieldInUniques(table.uniques, operation.from, operation.to);
+
+        for (const candidateTable of schema.tables) {
+          for (const candidateField of candidateTable.fields) {
+            if (
+              candidateField.references?.table === table.name &&
+              candidateField.references.field === operation.from
+            ) {
+              candidateField.references = {
+                ...candidateField.references,
+                field: operation.to,
+              };
+            }
+          }
+        }
+        break;
+      }
+      case "addIndex": {
+        const table = findTable(schema, operation.tableName);
+        if (!table) throw new Error(`Table ${operation.tableName} does not exist`);
+        table.indexes.push(cloneSchema(operation.index));
+        break;
+      }
+      case "dropIndex": {
+        const table = findTable(schema, operation.tableName);
+        if (!table) throw new Error(`Table ${operation.tableName} does not exist`);
+        const nextIndexes = table.indexes.filter(
+          (index) => resolveIndexName(table.name, index) !== operation.indexName,
+        );
+        if (nextIndexes.length === table.indexes.length) {
+          throw new Error(`Index ${operation.indexName} does not exist on ${table.name}`);
+        }
+        table.indexes = nextIndexes;
+        break;
+      }
+      case "addUnique": {
+        const table = findTable(schema, operation.tableName);
+        if (!table) throw new Error(`Table ${operation.tableName} does not exist`);
+        table.uniques.push(cloneSchema(operation.unique));
+        break;
+      }
+      case "dropUnique": {
+        const table = findTable(schema, operation.tableName);
+        if (!table) throw new Error(`Table ${operation.tableName} does not exist`);
+        const nextUniques = table.uniques.filter(
+          (unique) => resolveUniqueName(table.name, unique) !== operation.uniqueName,
+        );
+        if (nextUniques.length === table.uniques.length) {
+          throw new Error(`Unique ${operation.uniqueName} does not exist on ${table.name}`);
+        }
+        table.uniques = nextUniques;
+        break;
+      }
+    }
+  }
+
+  return assertValidSchemaDocument(schema);
+}
+
+function renameFieldInIndexes(indexes: IndexSpec[], from: string, to: string): IndexSpec[] {
+  return indexes.map((index) => ({
+    ...index,
+    fields: index.fields.map((field) => (field === from ? to : field)),
+  }));
+}
+
+function renameFieldInUniques(uniques: UniqueSpec[], from: string, to: string): UniqueSpec[] {
+  return uniques.map((unique) => ({
+    ...unique,
+    fields: unique.fields.map((field) => (field === from ? to : field)),
+  }));
+}
+
+function resolveIndexName(tableName: string, index: IndexSpec) {
+  return index.name ?? `${tableName}_${index.fields.join("_")}_idx`;
+}
+
+function resolveUniqueName(tableName: string, unique: UniqueSpec) {
+  return unique.name ?? `${tableName}_${unique.fields.join("_")}_unique`;
+}