bazis 0.96.1

package/library/orm/Schema/MigrationRunner.ts

@@ -0,0 +1,146 @@
+import type { DatabaseProvider, DbExecutor, Row, SqlParam } from "../Providers/types";
+
+/** Execution context of a versioned migration. */
+export interface MigrationContext {
+  /** Runs modifying SQL with `{0}` or `$1` parameters. */
+  execute(sql: string, ...params: SqlParam[]): Promise<void>;
+  /** SELECT with parameters. */
+  query<T extends Row = Row>(sql: string, ...params: SqlParam[]): Promise<T[]>;
+}
+
+/** Versioned migration with `up` and an optional `down`. */
+export interface Migration {
+  /** Unique identifier (usually timestamp_name). */
+  readonly id: string;
+  readonly up: (ctx: MigrationContext) => Promise<void>;
+  readonly down?: (ctx: MigrationContext) => Promise<void>;
+}
+
+export interface VersionedMigrationResult {
+  readonly applied: readonly string[];
+  readonly rolledBack: readonly string[];
+}
+
+const HISTORY_TABLE = "__BazisMigrations";
+
+/**
+ * Applies the registered migrations with history in the `__BazisMigrations` table.
+ * Compile-safe: migrations are passed as an explicit array (no dynamic import,
+ * which keeps `bun build --compile` working).
+ */
+export class MigrationRunner {
+  constructor(
+    private readonly provider: DatabaseProvider,
+    private readonly migrations: readonly Migration[],
+  ) {}
+
+  async migrate(): Promise<VersionedMigrationResult> {
+    // A cross-process PostgreSQL advisory lock keeps two starting instances
+    // from racing to apply migrations.
+    return this.withMigrationLock(() => this.migrateCore());
+  }
+
+  private async migrateCore(): Promise<VersionedMigrationResult> {
+    await this.ensureHistory();
+    const appliedSet = await this.loadApplied();
+    const pending = this.migrations.filter((migration) => !appliedSet.has(migration.id));
+    const applied: string[] = [];
+
+    for (const migration of pending) {
+      await this.provider.transaction(async (tx) => {
+        await migration.up(this.context(tx));
+        await tx.execute(
+          `INSERT INTO ${this.quote(HISTORY_TABLE)} (${this.quote("MigrationId")}, ${this.quote("AppliedAt")}) VALUES (${this.param(0)}, ${this.param(1)})`,
+          [migration.id, new Date().toISOString()],
+        );
+      });
+      applied.push(migration.id);
+    }
+    return { applied, rolledBack: [] };
+  }
+
+  /** Rolls back the last `steps` migrations (requires `down`). */
+  async rollback(steps = 1): Promise<VersionedMigrationResult> {
+    if (!Number.isSafeInteger(steps) || steps < 0) {
+      throw new RangeError(`Migration rollback steps must be a non-negative safe integer; received ${String(steps)}.`);
+    }
+    if (steps === 0) {
+      return { applied: [], rolledBack: [] };
+    }
+    return this.withMigrationLock(() => this.rollbackCore(steps));
+  }
+
+  private async rollbackCore(steps: number): Promise<VersionedMigrationResult> {
+    await this.ensureHistory();
+    const applied = await this.loadAppliedOrdered();
+    const toRollback = applied.slice(-steps).reverse();
+    const rolledBack: string[] = [];
+
+    for (const id of toRollback) {
+      const migration = this.migrations.find((m) => m.id === id);
+      if (!migration?.down) {
+        throw new Error(`Migration "${id}" has no down() method.`);
+      }
+      await this.provider.transaction(async (tx) => {
+        await migration.down!(this.context(tx));
+        await tx.execute(`DELETE FROM ${this.quote(HISTORY_TABLE)} WHERE ${this.quote("MigrationId")} = ${this.param(0)}`, [
+          id,
+        ]);
+      });
+      rolledBack.push(id);
+    }
+    return { applied: [], rolledBack };
+  }
+
+  private withMigrationLock<T>(work: () => Promise<T>): Promise<T> {
+    return this.provider.withMigrationLock ? this.provider.withMigrationLock(work) : work();
+  }
+
+  private context(tx: DbExecutor): MigrationContext {
+    return {
+      execute: async (sql, ...params) => {
+        await tx.execute(this.rewrite(sql, params.length), params);
+      },
+      query: async <T extends Row = Row>(sql: string, ...params: SqlParam[]) =>
+        tx.query(this.rewrite(sql, params.length), params) as Promise<T[]>,
+    };
+  }
+
+  private async ensureHistory(): Promise<void> {
+    await this.provider.execute(
+      `CREATE TABLE IF NOT EXISTS ${this.quote(HISTORY_TABLE)} (${this.quote("MigrationId")} TEXT PRIMARY KEY, ${this.quote("AppliedAt")} TEXT NOT NULL)`,
+      [],
+    );
+  }
+
+  private async loadApplied(): Promise<Set<string>> {
+    const rows = await this.provider.query(`SELECT ${this.quote("MigrationId")} AS id FROM ${this.quote(HISTORY_TABLE)}`, []);
+    return new Set(rows.map((row) => String(row.id)));
+  }
+
+  private async loadAppliedOrdered(): Promise<string[]> {
+    const rows = await this.provider.query(
+      `SELECT ${this.quote("MigrationId")} AS id FROM ${this.quote(HISTORY_TABLE)} ORDER BY ${this.quote("AppliedAt")} ASC`,
+      [],
+    );
+    return rows.map((row) => String(row.id));
+  }
+
+  private quote(name: string): string {
+    return this.provider.dialect.quoteId(name);
+  }
+
+  private param(index: number): string {
+    return this.provider.dialect.parameter(index);
+  }
+
+  private rewrite(sql: string, count: number): string {
+    return sql.replace(/\{(\d+)\}/g, (_match, raw: string) => {
+      const index = Number(raw);
+      if (index >= count) {
+        throw new RangeError(`Migration SQL references {${index}} but only ${count} parameter(s) provided.`);
+      }
+      return this.param(index);
+    });
+  }
+}

package/library/orm/Schema/Migrator.ts

@@ -0,0 +1,73 @@
+import type { EntityModel } from "../Metadata/types";
+import type { DatabaseProvider, ForeignKeyConstraint } from "../Providers/types";
+import type { AdditiveSchemaOperation } from "./SchemaDiffer";
+import { physicalTableIdentity } from "./tableKey";
+
+/** Schema migration outcome. */
+export interface MigrationResult {
+  /** Number of applied operations. */
+  readonly applied: number;
+  /** Human-readable description of the applied operations. */
+  readonly operations: readonly string[];
+  /** Destructive differences left untouched. */
+  readonly warnings: readonly string[];
+}
+
+/**
+ * Applies additive schema change operations in one transaction.
+ * FK constraints for `createTable` are computed by the given resolver
+ * (column/table names already resolved).
+ */
+export class Migrator {
+  constructor(
+    private readonly provider: DatabaseProvider,
+    private readonly foreignKeysFor: (model: EntityModel) => readonly ForeignKeyConstraint[],
+  ) {}
+
+  async apply(operations: readonly AdditiveSchemaOperation[]): Promise<string[]> {
+    if (operations.length === 0) {
+      return [];
+    }
+    const log: string[] = [];
+
+    await this.provider.transaction(async (tx) => {
+      for (const operation of operations) {
+        const schema = physicalTableIdentity(operation.model).schema;
+        if (operation.kind === "createTable" && schema !== undefined && this.provider.dialect.name === "postgres") {
+          await tx.execute(
+            `CREATE SCHEMA IF NOT EXISTS ${this.provider.dialect.quoteId(schema)}`,
+            [],
+          );
+        }
+        const sql = this.render(operation);
+        await tx.execute(sql, []);
+        log.push(this.describe(operation));
+      }
+    });
+    return log;
+  }
+
+  private render(operation: AdditiveSchemaOperation): string {
+    const dialect = this.provider.dialect;
+    switch (operation.kind) {
+      case "createTable":
+        return dialect.createTableSql(operation.model, this.foreignKeysFor(operation.model));
+      case "addColumn":
+        return dialect.addColumnSql(operation.model, operation.property,
+          this.foreignKeysFor(operation.model).find((fk) => (fk.columns ?? [fk.column]).includes(operation.property.columnName)));
+      case "createIndex":
+        return dialect.createIndexSqlOne(operation.model, operation.index);
+    }
+  }
+
+  private describe(operation: AdditiveSchemaOperation): string {
+    switch (operation.kind) {
+      case "createTable":
+        return `create table ${operation.model.tableName}`;
+      case "addColumn":
+        return `add column ${operation.model.tableName}.${operation.property.columnName}`;
+      case "createIndex":
+        return `create index ${operation.index.name}`;
+    }
+  }
+}

package/library/orm/Schema/OrmOwnedStore.ts

@@ -0,0 +1,123 @@
+import { types } from "node:util";
+import { OrmOwnedStoreAdmissionError } from "../errors";
+
+export interface OrmCatalogScopeV1 {
+  readonly schema: string;
+  readonly tablePrefix: string;
+}
+
+export interface OrmOwnedStoreDefinitionV1 {
+  readonly contract: "bazis.orm-owned-store/v1";
+  readonly storeKey: string;
+  readonly formatVersion: number;
+  readonly ownedScope: OrmCatalogScopeV1;
+  readonly rejectIfPresent?: readonly OrmCatalogScopeV1[];
+}
+
+const IDENTITY_MISMATCH = "ORM_OWNED_STORE_IDENTITY_MISMATCH";
+const OWNERSHIP_CONFLICT = "ORM_OWNED_STORE_OWNERSHIP_CONFLICT";
+const CONTRACT = "bazis.orm-owned-store/v1" as const;
+const maxRejectScopes = 64;
+const canonicalDefinitions = new WeakSet<object>();
+
+/**
+ * Takes a hostile-input-safe snapshot of an owned-store descriptor.  This is
+ * deliberately a nominal boundary only; its private identity is installed by
+ * later lifecycle work, never on the caller's object.
+ */
+export function defineOrmOwnedStoreV1(definition: OrmOwnedStoreDefinitionV1): Readonly<OrmOwnedStoreDefinitionV1> {
+  try {
+    rejectProxy(definition);
+    const root = closedRecord(definition, ["contract", "storeKey", "formatVersion", "ownedScope", "rejectIfPresent"], ["contract", "storeKey", "formatVersion", "ownedScope"]);
+    const contract = root.contract;
+    const storeKey = root.storeKey;
+    const formatVersion = root.formatVersion;
+    if (contract !== CONTRACT || !validString(storeKey, 128) || typeof formatVersion !== "number" || !Number.isSafeInteger(formatVersion) || formatVersion <= 0) throw identity();
+    const ownedScope = readScope(root.ownedScope);
+    const rejectIfPresent = root.rejectIfPresent === undefined ? [] : readScopes(root.rejectIfPresent);
+    if (rejectIfPresent.some((scope) => sameScope(scope, ownedScope))) throw ownership();
+    const canonicalRejects = uniqueSortedScopes(rejectIfPresent);
+    const result: OrmOwnedStoreDefinitionV1 = canonicalRejects.length === 0
+      ? { contract: CONTRACT, storeKey, formatVersion, ownedScope }
+      : { contract: CONTRACT, storeKey, formatVersion, ownedScope, rejectIfPresent: canonicalRejects };
+    const frozen = deepFreeze(result);
+    canonicalDefinitions.add(frozen);
+    return frozen;
+  } catch (error) {
+    if (error instanceof OrmOwnedStoreAdmissionError) throw error;
+    throw identity();
+  }
+}
+
+/** Private nominal check for the later core lifecycle; intentionally not barrel-exported. */
+export function isDefinedOrmOwnedStoreV1(value: unknown): value is Readonly<OrmOwnedStoreDefinitionV1> {
+  return value !== null && typeof value === "object" && canonicalDefinitions.has(value);
+}
+
+function readScopes(value: unknown): readonly OrmCatalogScopeV1[] {
+  rejectProxy(value);
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) throw identity();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Object.getOwnPropertySymbols(value).length !== 0) throw identity();
+  if (value.length > maxRejectScopes) throw identity();
+  const expected = new Set(["length", ...Array.from({ length: value.length }, (_, index) => String(index))]);
+  if (Object.keys(descriptors).some((key) => !expected.has(key))) throw identity();
+  const scopes: OrmCatalogScopeV1[] = [];
+  for (let index = 0; index < value.length; index++) {
+    const descriptor = descriptors[String(index)];
+    if (!descriptor || !("value" in descriptor)) throw identity();
+    scopes.push(readScope(descriptor.value));
+  }
+  return scopes;
+}
+
+function readScope(value: unknown): OrmCatalogScopeV1 {
+  const record = closedRecord(value, ["schema", "tablePrefix"], ["schema", "tablePrefix"]);
+  if (!validString(record.schema, 63) || !validString(record.tablePrefix, 63)) throw identity();
+  return { schema: record.schema, tablePrefix: record.tablePrefix };
+}
+
+function closedRecord(value: unknown, allowed: readonly string[], required: readonly string[]): Record<string, unknown> {
+  rejectProxy(value);
+  if (value === null || typeof value !== "object") throw identity();
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw identity();
+  if (Object.getOwnPropertySymbols(value).length !== 0) throw identity();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Object.keys(descriptors)) {
+    if (!allowed.includes(key)) throw identity();
+    const descriptor = descriptors[key]!;
+    if (!("value" in descriptor) || descriptor.value === undefined) throw identity();
+  }
+  for (const key of required) if (!Object.hasOwn(descriptors, key)) throw identity();
+  return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, (descriptor as PropertyDescriptor & { value: unknown }).value]));
+}
+
+function validString(value: unknown, maxBytes: number): value is string {
+  if (typeof value !== "string") return false;
+  if (Buffer.byteLength(value, "utf8") < 1 || Buffer.byteLength(value, "utf8") > maxBytes) return false;
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!Number.isInteger(next) || next < 0xdc00 || next > 0xdfff) return false;
+      index++;
+      continue;
+    }
+    if ((unit >= 0xdc00 && unit <= 0xdfff) || unit <= 0x1f || (unit >= 0x7f && unit <= 0x9f)) return false;
+  }
+  return true;
+}
+
+function uniqueSortedScopes(scopes: readonly OrmCatalogScopeV1[]): readonly OrmCatalogScopeV1[] {
+  const result = [...scopes].sort(compareScope);
+  return result.filter((scope, index) => index === 0 || !sameScope(scope, result[index - 1]!)).map((scope) => ({ ...scope }));
+}
+function compareScope(left: OrmCatalogScopeV1, right: OrmCatalogScopeV1): number {
+  return Buffer.compare(Buffer.from(left.schema, "utf8"), Buffer.from(right.schema, "utf8")) || Buffer.compare(Buffer.from(left.tablePrefix, "utf8"), Buffer.from(right.tablePrefix, "utf8"));
+}
+function sameScope(left: OrmCatalogScopeV1, right: OrmCatalogScopeV1): boolean { return left.schema === right.schema && left.tablePrefix === right.tablePrefix; }
+function rejectProxy(value: unknown): void { if (value !== null && (typeof value === "object" || typeof value === "function") && types.isProxy(value)) throw identity(); }
+function identity(): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError(IDENTITY_MISMATCH, IDENTITY_MISMATCH); }
+function ownership(): OrmOwnedStoreAdmissionError { return new OrmOwnedStoreAdmissionError(OWNERSHIP_CONFLICT, OWNERSHIP_CONFLICT); }
+function deepFreeze<T>(value: T): T { if (value && typeof value === "object") { for (const child of Object.values(value)) deepFreeze(child); Object.freeze(value); } return value; }