@sedrino/db-schema 0.1.1

package/src/project.ts

@@ -0,0 +1,79 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { DatabaseSchemaDocument } from "./types";
+import type { MigrationDefinition } from "./migration";
+import { compileSchemaToDrizzle } from "./drizzle";
+import { materializeSchema } from "./planner";
+
+const MIGRATION_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
+
+export type DbProjectLayout = {
+  dbDir: string;
+  migrationsDir: string;
+  schemaDir: string;
+  snapshotPath: string;
+  drizzlePath: string;
+};
+
+export function resolveDbProjectLayout(dbDir = "db"): DbProjectLayout {
+  const absoluteDbDir = path.resolve(dbDir);
+  return {
+    dbDir: absoluteDbDir,
+    migrationsDir: path.join(absoluteDbDir, "migrations"),
+    schemaDir: path.join(absoluteDbDir, "schema"),
+    snapshotPath: path.join(absoluteDbDir, "schema", "schema.snapshot.json"),
+    drizzlePath: path.join(absoluteDbDir, "schema", "schema.generated.ts"),
+  };
+}
+
+export async function loadMigrationDefinitionsFromDirectory(
+  migrationsDir: string,
+): Promise<MigrationDefinition[]> {
+  const files = await readdir(migrationsDir, { withFileTypes: true });
+  const migrationFiles = files
+    .filter((entry) => entry.isFile())
+    .map((entry) => path.join(migrationsDir, entry.name))
+    .filter((filePath) => MIGRATION_EXTENSIONS.has(path.extname(filePath)))
+    .sort((left, right) => path.basename(left).localeCompare(path.basename(right)));
+
+  const migrations: MigrationDefinition[] = [];
+
+  for (const filePath of migrationFiles) {
+    const imported = await import(pathToFileURL(filePath).href);
+    const definition = imported.default as Partial<MigrationDefinition> | undefined;
+
+    if (
+      !definition ||
+      !definition.meta ||
+      typeof definition.meta.id !== "string" ||
+      typeof definition.meta.name !== "string" ||
+      typeof definition.buildOperations !== "function"
+    ) {
+      throw new Error(`Migration file ${filePath} does not export a valid default migration`);
+    }
+
+    migrations.push(definition as MigrationDefinition);
+  }
+
+  return migrations;
+}
+
+export async function materializeProjectMigrations(layout: DbProjectLayout) {
+  const migrations = await loadMigrationDefinitionsFromDirectory(layout.migrationsDir);
+  const materialized = materializeSchema({ migrations });
+  return {
+    ...materialized,
+    migrations,
+  };
+}
+
+export async function writeSchemaSnapshot(schema: DatabaseSchemaDocument, snapshotPath: string) {
+  await mkdir(path.dirname(snapshotPath), { recursive: true });
+  await writeFile(snapshotPath, `${JSON.stringify(schema, null, 2)}\n`, "utf8");
+}
+
+export async function writeDrizzleSchema(schema: DatabaseSchemaDocument, drizzlePath: string) {
+  await mkdir(path.dirname(drizzlePath), { recursive: true });
+  await writeFile(drizzlePath, compileSchemaToDrizzle(schema), "utf8");
+}

package/src/schema.ts

@@ -0,0 +1,53 @@
+import {
+  type DatabaseSchemaDocument,
+  type FieldSpec,
+  type SchemaValidationIssue,
+  schemaDocumentSchema,
+} from "./types";
+import { createSchemaHash, validateSchemaDocumentCompatibility } from "./utils";
+
+export function createEmptySchema(schemaId = "schema") {
+  return schemaDocumentSchema.parse({
+    version: 1,
+    dialect: "sqlite",
+    schemaId,
+    tables: [],
+  });
+}
+
+export function parseSchemaDocument(input: unknown): DatabaseSchemaDocument {
+  return schemaDocumentSchema.parse(input);
+}
+
+export function validateSchemaDocument(input: unknown): {
+  schema: DatabaseSchemaDocument;
+  issues: SchemaValidationIssue[];
+} {
+  const schema = parseSchemaDocument(input);
+  return {
+    schema,
+    issues: validateSchemaDocumentCompatibility(schema),
+  };
+}
+
+export function assertValidSchemaDocument(input: unknown): DatabaseSchemaDocument {
+  const { schema, issues } = validateSchemaDocument(input);
+  if (issues.length > 0) {
+    throw new Error(
+      `Schema validation failed:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`,
+    );
+  }
+  return schema;
+}
+
+export function schemaHash(input: DatabaseSchemaDocument) {
+  return createSchemaHash(input);
+}
+
+export function findTable(schema: DatabaseSchemaDocument, tableName: string) {
+  return schema.tables.find((table) => table.name === tableName) ?? null;
+}
+
+export function findField(table: { fields: FieldSpec[] }, fieldName: string) {
+  return table.fields.find((field) => field.name === fieldName) ?? null;
+}

package/src/sqlite.ts

@@ -0,0 +1,172 @@
+import type {
+  DatabaseSchemaDocument,
+  DefaultSpec,
+  FieldSpec,
+  IndexSpec,
+  StorageSpec,
+  TableSpec,
+  UniqueSpec,
+} from "./types";
+import type { MigrationOperation } from "./migration";
+import { quoteIdentifier, sqliteEpochMsNowSql, toSnakeCase } from "./utils";
+
+export function compileSchemaToSqlite(schema: DatabaseSchemaDocument) {
+  const statements: string[] = [];
+
+  for (const table of schema.tables) {
+    statements.push(renderCreateTableStatement(table));
+    statements.push(...renderCreateIndexStatements(table));
+  }
+
+  return `${statements.join("\n\n")}\n`;
+}
+
+export function renderSqliteMigration(operations: MigrationOperation[]) {
+  const statements: string[] = [];
+  const warnings: string[] = [];
+
+  for (const operation of operations) {
+    switch (operation.kind) {
+      case "createTable":
+        statements.push(renderCreateTableStatement(operation.table));
+        statements.push(...renderCreateIndexStatements(operation.table));
+        break;
+      case "dropTable":
+        statements.push(`DROP TABLE ${quoteIdentifier(operation.tableName)};`);
+        break;
+      case "renameTable":
+        statements.push(
+          `ALTER TABLE ${quoteIdentifier(operation.from)} RENAME TO ${quoteIdentifier(operation.to)};`,
+        );
+        break;
+      case "addField":
+        statements.push(
+          `ALTER TABLE ${quoteIdentifier(operation.tableName)} ADD COLUMN ${renderColumnDefinition(operation.field)};`,
+        );
+        break;
+      case "renameField":
+        statements.push(
+          `ALTER TABLE ${quoteIdentifier(operation.tableName)} RENAME COLUMN ${quoteIdentifier(toSnakeCase(operation.from))} TO ${quoteIdentifier(toSnakeCase(operation.to))};`,
+        );
+        break;
+      case "addIndex":
+        statements.push(renderCreateIndexStatement(operation.tableName, operation.index));
+        break;
+      case "dropIndex":
+        statements.push(`DROP INDEX ${quoteIdentifier(operation.indexName)};`);
+        break;
+      case "addUnique":
+        statements.push(renderCreateUniqueStatement(operation.tableName, operation.unique));
+        break;
+      case "dropUnique":
+        statements.push(`DROP INDEX ${quoteIdentifier(operation.uniqueName)};`);
+        break;
+      case "dropField":
+        warnings.push(
+          `dropField ${operation.tableName}.${operation.fieldName} requires a table rebuild and is not emitted in v1`,
+        );
+        break;
+    }
+  }
+
+  return {
+    statements,
+    warnings,
+  };
+}
+
+export function renderCreateTableStatement(table: TableSpec) {
+  const columnLines = table.fields.map((field) => `  ${renderColumnDefinition(field)}`);
+  return `CREATE TABLE ${quoteIdentifier(table.name)} (\n${columnLines.join(",\n")}\n);`;
+}
+
+export function renderCreateIndexStatements(table: TableSpec) {
+  const statements = table.indexes.map((index) =>
+    renderCreateIndexStatement(table.name, index, table),
+  );
+  statements.push(
+    ...table.uniques.map((unique) => renderCreateUniqueStatement(table.name, unique, table)),
+  );
+  return statements;
+}
+
+function renderCreateIndexStatement(tableName: string, index: IndexSpec, table?: TableSpec) {
+  const name = index.name ?? `${tableName}_${index.fields.join("_")}_idx`;
+  return `CREATE INDEX ${quoteIdentifier(name)} ON ${quoteIdentifier(tableName)} (${index.fields
+    .map((field) => quoteIdentifier(resolveColumnName(table, field)))
+    .join(", ")});`;
+}
+
+function renderCreateUniqueStatement(tableName: string, unique: UniqueSpec, table?: TableSpec) {
+  const name = unique.name ?? `${tableName}_${unique.fields.join("_")}_unique`;
+  return `CREATE UNIQUE INDEX ${quoteIdentifier(name)} ON ${quoteIdentifier(tableName)} (${unique.fields
+    .map((field) => quoteIdentifier(resolveColumnName(table, field)))
+    .join(", ")});`;
+}
+
+function renderColumnDefinition(field: FieldSpec) {
+  const parts = [quoteIdentifier(field.storage.column), renderSqlType(field.storage)];
+
+  if (field.primaryKey) parts.push("PRIMARY KEY");
+  if (!field.nullable) parts.push("NOT NULL");
+  if (field.unique && !field.primaryKey) parts.push("UNIQUE");
+
+  const defaultSql = renderSqlDefault(field.default, field);
+  if (defaultSql) parts.push(`DEFAULT ${defaultSql}`);
+
+  if (field.references) {
+    parts.push(
+      `REFERENCES ${quoteIdentifier(field.references.table)}(${quoteIdentifier(toSnakeCase(field.references.field))})`,
+    );
+    if (field.references.onDelete)
+      parts.push(`ON DELETE ${field.references.onDelete.toUpperCase()}`);
+    if (field.references.onUpdate)
+      parts.push(`ON UPDATE ${field.references.onUpdate.toUpperCase()}`);
+  }
+
+  return parts.join(" ");
+}
+
+function renderSqlType(storage: StorageSpec) {
+  switch (storage.strategy) {
+    case "sqlite.text":
+    case "sqlite.temporalPlainDateText":
+      return "TEXT";
+    case "sqlite.integer":
+    case "sqlite.temporalInstantEpochMs":
+      return "INTEGER";
+    case "sqlite.real":
+      return "REAL";
+  }
+}
+
+function renderSqlDefault(defaultValue: DefaultSpec | undefined, field: FieldSpec) {
+  if (!defaultValue) return null;
+
+  switch (defaultValue.kind) {
+    case "generatedId":
+      return null;
+    case "now":
+      return `(${sqliteEpochMsNowSql()})`;
+    case "literal":
+      if (defaultValue.value === null) return "NULL";
+      if (typeof defaultValue.value === "string") {
+        return `'${defaultValue.value.replace(/'/g, "''")}'`;
+      }
+      if (typeof defaultValue.value === "boolean") {
+        return field.storage.strategy === "sqlite.integer"
+          ? defaultValue.value
+            ? "1"
+            : "0"
+          : defaultValue.value
+            ? "TRUE"
+            : "FALSE";
+      }
+      return `${defaultValue.value}`;
+  }
+}
+
+function resolveColumnName(table: TableSpec | undefined, fieldName: string) {
+  const field = table?.fields.find((candidate) => candidate.name === fieldName);
+  return field?.storage.column ?? toSnakeCase(fieldName);
+}

package/src/types.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+
+export const foreignKeyActionSchema = z.enum([
+  "cascade",
+  "restrict",
+  "set null",
+  "set default",
+  "no action",
+]);
+
+export const fieldReferenceSpecSchema = z.object({
+  table: z.string().min(1),
+  field: z.string().min(1),
+  onDelete: foreignKeyActionSchema.optional(),
+  onUpdate: foreignKeyActionSchema.optional(),
+});
+
+export const logicalTypeSpecSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("id"),
+    prefix: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("string"),
+    format: z.enum(["email", "url", "slug"]).optional(),
+  }),
+  z.object({
+    kind: z.literal("text"),
+  }),
+  z.object({
+    kind: z.literal("boolean"),
+  }),
+  z.object({
+    kind: z.literal("integer"),
+  }),
+  z.object({
+    kind: z.literal("number"),
+  }),
+  z.object({
+    kind: z.literal("enum"),
+    values: z.array(z.string()).min(1),
+  }),
+  z.object({
+    kind: z.literal("json"),
+    tsType: z.string().min(1),
+  }),
+  z.object({
+    kind: z.literal("temporal.instant"),
+  }),
+  z.object({
+    kind: z.literal("temporal.plainDate"),
+  }),
+]);
+
+export const storageSpecSchema = z.discriminatedUnion("strategy", [
+  z.object({
+    strategy: z.literal("sqlite.text"),
+    column: z.string().min(1),
+  }),
+  z.object({
+    strategy: z.literal("sqlite.integer"),
+    column: z.string().min(1),
+  }),
+  z.object({
+    strategy: z.literal("sqlite.real"),
+    column: z.string().min(1),
+  }),
+  z.object({
+    strategy: z.literal("sqlite.temporalInstantEpochMs"),
+    column: z.string().min(1),
+  }),
+  z.object({
+    strategy: z.literal("sqlite.temporalPlainDateText"),
+    column: z.string().min(1),
+  }),
+]);
+
+export const defaultSpecSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("literal"),
+    value: z.union([z.string(), z.number(), z.boolean(), z.null()]),
+  }),
+  z.object({
+    kind: z.literal("now"),
+  }),
+  z.object({
+    kind: z.literal("generatedId"),
+    prefix: z.string().min(1),
+  }),
+]);
+
+export const fieldSpecSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  logical: logicalTypeSpecSchema,
+  storage: storageSpecSchema,
+  nullable: z.boolean().default(true),
+  default: defaultSpecSchema.optional(),
+  primaryKey: z.boolean().default(false),
+  unique: z.boolean().default(false),
+  description: z.string().min(1).optional(),
+  references: fieldReferenceSpecSchema.optional(),
+});
+
+export const indexSpecSchema = z.object({
+  name: z.string().min(1).optional(),
+  fields: z.array(z.string().min(1)).min(1),
+});
+
+export const uniqueSpecSchema = z.object({
+  name: z.string().min(1).optional(),
+  fields: z.array(z.string().min(1)).min(1),
+});
+
+export const tableSpecSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().min(1).optional(),
+  fields: z.array(fieldSpecSchema).default([]),
+  indexes: z.array(indexSpecSchema).default([]),
+  uniques: z.array(uniqueSpecSchema).default([]),
+});
+
+export const schemaDocumentSchema = z.object({
+  version: z.literal(1),
+  dialect: z.literal("sqlite"),
+  schemaId: z.string().min(1),
+  tables: z.array(tableSpecSchema).default([]),
+});
+
+export type ForeignKeyAction = z.infer<typeof foreignKeyActionSchema>;
+export type FieldReferenceSpec = z.infer<typeof fieldReferenceSpecSchema>;
+export type LogicalTypeSpec = z.infer<typeof logicalTypeSpecSchema>;
+export type StorageSpec = z.infer<typeof storageSpecSchema>;
+export type DefaultSpec = z.infer<typeof defaultSpecSchema>;
+export type FieldSpec = z.infer<typeof fieldSpecSchema>;
+export type IndexSpec = z.infer<typeof indexSpecSchema>;
+export type UniqueSpec = z.infer<typeof uniqueSpecSchema>;
+export type TableSpec = z.infer<typeof tableSpecSchema>;
+export type DatabaseSchemaDocument = z.infer<typeof schemaDocumentSchema>;
+
+export type SchemaValidationIssue = {
+  path: string;
+  message: string;
+};