@crewhaus/migration-engine 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Section 28 — `migration-engine`. Versioned spec migrations registered as
+ * `{ from, to, up, down }` so rollbacks work both directions. The engine
+ * walks the registered chain to bridge any pair of source/target versions
+ * (forward when `from < to`, reverse when `from > to`).
+ *
+ * Spec versions are integer ints (today every spec is `version: 0`). The
+ * first migration registered is the no-op skeleton 0 → 1.
+ *
+ * Specs are passed in as parsed YAML (raw object); migration steps are
+ * pure transforms `(spec) → spec` returning the next-version shape. The
+ * engine is unaware of YAML serialisation — callers use yaml-js or the
+ * spec parser to round-trip.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export type SpecObject = Record<string, unknown> & {
+    readonly version?: number;
+};
+export type Migration = {
+    readonly from: number;
+    readonly to: number;
+    up(spec: SpecObject): SpecObject;
+    down(spec: SpecObject): SpecObject;
+};
+export declare class MigrationError extends CrewhausError {
+    readonly name = "MigrationError";
+    constructor(message: string, cause?: unknown);
+}
+export declare class MigrationEngine {
+    private readonly migrations;
+    constructor();
+    register(m: Migration): void;
+    /**
+     * Walk the registered chain to migrate `spec` from its current version
+     * to `toVersion`. Throws MigrationError when a step is missing.
+     */
+    migrate(spec: SpecObject, toVersion: number): SpecObject;
+    /** Diagnostic: list registered migration keys. */
+    list(): ReadonlyArray<string>;
+    /** Reset the registry (tests). */
+    clear(): void;
+}
+/**
+ * Skeleton migration 0 → 1 that today is a no-op. Future schema changes
+ * land here and bump the IR version on the up() side.
+ */
+export declare const NOOP_0_TO_1: Migration;
+/** A pre-built engine with the v0 → v1 skeleton registered. */
+export declare function createDefaultEngine(): MigrationEngine;

package/dist/index.js

@@ -0,0 +1,101 @@
+/**
+ * Section 28 — `migration-engine`. Versioned spec migrations registered as
+ * `{ from, to, up, down }` so rollbacks work both directions. The engine
+ * walks the registered chain to bridge any pair of source/target versions
+ * (forward when `from < to`, reverse when `from > to`).
+ *
+ * Spec versions are integer ints (today every spec is `version: 0`). The
+ * first migration registered is the no-op skeleton 0 → 1.
+ *
+ * Specs are passed in as parsed YAML (raw object); migration steps are
+ * pure transforms `(spec) → spec` returning the next-version shape. The
+ * engine is unaware of YAML serialisation — callers use yaml-js or the
+ * spec parser to round-trip.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export class MigrationError extends CrewhausError {
+    name = "MigrationError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export class MigrationEngine {
+    migrations;
+    constructor() {
+        this.migrations = new Map();
+    }
+    register(m) {
+        if (m.from === m.to) {
+            throw new MigrationError(`migration ${m.from} → ${m.to} is a no-op (from === to); refusing to register`);
+        }
+        if (Math.abs(m.to - m.from) !== 1) {
+            throw new MigrationError(`migrations must be single-version steps; got ${m.from} → ${m.to}`);
+        }
+        const key = `${m.from}→${m.to}`;
+        if (this.migrations.has(key)) {
+            throw new MigrationError(`duplicate migration ${key}`);
+        }
+        this.migrations.set(key, m);
+    }
+    /**
+     * Walk the registered chain to migrate `spec` from its current version
+     * to `toVersion`. Throws MigrationError when a step is missing.
+     */
+    migrate(spec, toVersion) {
+        const fromVersion = (spec.version ?? 0) | 0;
+        if (fromVersion === toVersion)
+            return spec;
+        let current = spec;
+        if (fromVersion < toVersion) {
+            // Walk up
+            for (let v = fromVersion; v < toVersion; v++) {
+                const key = `${v}→${v + 1}`;
+                const step = this.migrations.get(key);
+                if (!step) {
+                    throw new MigrationError(`no migration registered for ${key}`);
+                }
+                current = step.up(current);
+            }
+        }
+        else {
+            // Walk down
+            for (let v = fromVersion; v > toVersion; v--) {
+                const key = `${v - 1}→${v}`;
+                const step = this.migrations.get(key);
+                if (!step) {
+                    throw new MigrationError(`no migration registered for ${key} (needed for downgrade)`);
+                }
+                current = step.down(current);
+            }
+        }
+        return current;
+    }
+    /** Diagnostic: list registered migration keys. */
+    list() {
+        return [...this.migrations.keys()].sort();
+    }
+    /** Reset the registry (tests). */
+    clear() {
+        this.migrations.clear();
+    }
+}
+/**
+ * Skeleton migration 0 → 1 that today is a no-op. Future schema changes
+ * land here and bump the IR version on the up() side.
+ */
+export const NOOP_0_TO_1 = Object.freeze({
+    from: 0,
+    to: 1,
+    up(spec) {
+        return { ...spec, version: 1 };
+    },
+    down(spec) {
+        return { ...spec, version: 0 };
+    },
+});
+/** A pre-built engine with the v0 → v1 skeleton registered. */
+export function createDefaultEngine() {
+    const e = new MigrationEngine();
+    e.register(NOOP_0_TO_1);
+    return e;
+}

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/migration-engine",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "IR version migrations: register up/down chains; migrate(spec, fromVersion, toVersion) walks the chain",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.3"
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,160 +0,0 @@
-/**
- * Section 28 — `migration-engine` tests:
- *  - T1 round-trip per registered migration
- *  - T4 fixture corpus replay
- */
-import { describe, expect, test } from "bun:test";
-import { MigrationEngine, MigrationError, NOOP_0_TO_1, createDefaultEngine } from "./index";
-
-describe("migration-engine — T1 single-step migrations", () => {
-  test("0 → 1 NOOP migrates and stamps version", () => {
-    const e = createDefaultEngine();
-    const out = e.migrate({ name: "x", target: "cli" }, 1);
-    expect(out.version).toBe(1);
-  });
-
-  test("up + down round-trip", () => {
-    const e = createDefaultEngine();
-    const original = { name: "x", target: "cli", version: 0 };
-    const up = e.migrate(original, 1);
-    expect(up.version).toBe(1);
-    const back = e.migrate(up, 0);
-    expect(back.version).toBe(0);
-  });
-
-  test("from === to is a no-op", () => {
-    const e = createDefaultEngine();
-    const spec = { version: 0 };
-    expect(e.migrate(spec, 0)).toBe(spec);
-  });
-
-  test("missing version step throws", () => {
-    const e = new MigrationEngine();
-    expect(() => e.migrate({ version: 0 }, 1)).toThrow(MigrationError);
-  });
-
-  test("registering same key twice throws", () => {
-    const e = new MigrationEngine();
-    e.register(NOOP_0_TO_1);
-    expect(() => e.register(NOOP_0_TO_1)).toThrow(MigrationError);
-  });
-
-  test("registering same-version migration throws", () => {
-    const e = new MigrationEngine();
-    expect(() =>
-      e.register({
-        from: 0,
-        to: 0,
-        up: (s) => s,
-        down: (s) => s,
-      }),
-    ).toThrow(MigrationError);
-  });
-
-  test("registering >1-step migration throws", () => {
-    const e = new MigrationEngine();
-    expect(() =>
-      e.register({
-        from: 0,
-        to: 2,
-        up: (s) => s,
-        down: (s) => s,
-      }),
-    ).toThrow(MigrationError);
-  });
-});
-
-describe("migration-engine — T4 multi-step chain replay", () => {
-  test("0 → 2 walks 0→1 then 1→2", () => {
-    const e = new MigrationEngine();
-    e.register({
-      from: 0,
-      to: 1,
-      up: (s) => ({ ...s, version: 1, addedAt1: true }),
-      down: (s) => ({ ...s, version: 0 }),
-    });
-    e.register({
-      from: 1,
-      to: 2,
-      up: (s) => ({ ...s, version: 2, addedAt2: true }),
-      down: (s) => ({ ...s, version: 1 }),
-    });
-    const out = e.migrate({ version: 0 }, 2);
-    expect(out.version).toBe(2);
-    expect((out as { addedAt1?: boolean }).addedAt1).toBe(true);
-    expect((out as { addedAt2?: boolean }).addedAt2).toBe(true);
-  });
-
-  test("2 → 0 walks 1→2.down then 0→1.down", () => {
-    const e = new MigrationEngine();
-    e.register({
-      from: 0,
-      to: 1,
-      up: (s) => ({ ...s, version: 1 }),
-      down: (s) => ({ ...s, version: 0, removedAt0: true }),
-    });
-    e.register({
-      from: 1,
-      to: 2,
-      up: (s) => ({ ...s, version: 2 }),
-      down: (s) => ({ ...s, version: 1, removedAt1: true }),
-    });
-    const out = e.migrate({ version: 2 }, 0);
-    expect(out.version).toBe(0);
-    expect((out as { removedAt0?: boolean }).removedAt0).toBe(true);
-    expect((out as { removedAt1?: boolean }).removedAt1).toBe(true);
-  });
-
-  test("list returns sorted migration keys", () => {
-    const e = createDefaultEngine();
-    e.register({
-      from: 1,
-      to: 2,
-      up: (s) => s,
-      down: (s) => s,
-    });
-    expect(e.list()).toEqual(["0→1", "1→2"]);
-  });
-
-  test("clear empties the registry", () => {
-    const e = createDefaultEngine();
-    expect(e.list()).toEqual(["0→1"]);
-    e.clear();
-    expect(e.list()).toEqual([]);
-    // After clearing, the previously-registered step is gone.
-    expect(() => e.migrate({ version: 0 }, 1)).toThrow(MigrationError);
-  });
-});
-
-describe("migration-engine — additional coverage", () => {
-  test("NOOP_0_TO_1.up stamps version 1 and preserves other keys", () => {
-    const out = NOOP_0_TO_1.up({ name: "x", version: 0 });
-    expect(out).toEqual({ name: "x", version: 1 });
-  });
-
-  test("NOOP_0_TO_1.down stamps version 0 and preserves other keys", () => {
-    const out = NOOP_0_TO_1.down({ name: "x", version: 1 });
-    expect(out).toEqual({ name: "x", version: 0 });
-  });
-
-  test("migrate treats a spec with no version field as version 0", () => {
-    const e = createDefaultEngine();
-    // No `version` key at all -> fromVersion defaults to 0, so 0 -> 1 runs.
-    const out = e.migrate({ name: "no-version" }, 1);
-    expect(out.version).toBe(1);
-  });
-
-  test("downgrade throws when the needed step is not registered", () => {
-    const e = new MigrationEngine();
-    // Walking down from 1 to 0 needs the 0→1 step's down(); none registered.
-    expect(() => e.migrate({ version: 1 }, 0)).toThrow(MigrationError);
-  });
-
-  test("MigrationError carries the config code and an optional cause", () => {
-    const cause = new Error("root");
-    const err = new MigrationError("boom", cause);
-    expect(err).toBeInstanceOf(MigrationError);
-    expect(err.name).toBe("MigrationError");
-    expect(err.cause).toBe(cause);
-  });
-});

package/src/index.ts

@@ -1,122 +0,0 @@
-/**
- * Section 28 — `migration-engine`. Versioned spec migrations registered as
- * `{ from, to, up, down }` so rollbacks work both directions. The engine
- * walks the registered chain to bridge any pair of source/target versions
- * (forward when `from < to`, reverse when `from > to`).
- *
- * Spec versions are integer ints (today every spec is `version: 0`). The
- * first migration registered is the no-op skeleton 0 → 1.
- *
- * Specs are passed in as parsed YAML (raw object); migration steps are
- * pure transforms `(spec) → spec` returning the next-version shape. The
- * engine is unaware of YAML serialisation — callers use yaml-js or the
- * spec parser to round-trip.
- */
-import { CrewhausError } from "@crewhaus/errors";
-
-export type SpecObject = Record<string, unknown> & {
-  readonly version?: number;
-};
-
-export type Migration = {
-  readonly from: number;
-  readonly to: number;
-  up(spec: SpecObject): SpecObject;
-  down(spec: SpecObject): SpecObject;
-};
-
-export class MigrationError extends CrewhausError {
-  override readonly name = "MigrationError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export class MigrationEngine {
-  private readonly migrations: Map<string, Migration>;
-
-  constructor() {
-    this.migrations = new Map<string, Migration>();
-  }
-
-  register(m: Migration): void {
-    if (m.from === m.to) {
-      throw new MigrationError(
-        `migration ${m.from} → ${m.to} is a no-op (from === to); refusing to register`,
-      );
-    }
-    if (Math.abs(m.to - m.from) !== 1) {
-      throw new MigrationError(`migrations must be single-version steps; got ${m.from} → ${m.to}`);
-    }
-    const key = `${m.from}→${m.to}`;
-    if (this.migrations.has(key)) {
-      throw new MigrationError(`duplicate migration ${key}`);
-    }
-    this.migrations.set(key, m);
-  }
-
-  /**
-   * Walk the registered chain to migrate `spec` from its current version
-   * to `toVersion`. Throws MigrationError when a step is missing.
-   */
-  migrate(spec: SpecObject, toVersion: number): SpecObject {
-    const fromVersion = (spec.version ?? 0) | 0;
-    if (fromVersion === toVersion) return spec;
-
-    let current = spec;
-    if (fromVersion < toVersion) {
-      // Walk up
-      for (let v = fromVersion; v < toVersion; v++) {
-        const key = `${v}→${v + 1}`;
-        const step = this.migrations.get(key);
-        if (!step) {
-          throw new MigrationError(`no migration registered for ${key}`);
-        }
-        current = step.up(current);
-      }
-    } else {
-      // Walk down
-      for (let v = fromVersion; v > toVersion; v--) {
-        const key = `${v - 1}→${v}`;
-        const step = this.migrations.get(key);
-        if (!step) {
-          throw new MigrationError(`no migration registered for ${key} (needed for downgrade)`);
-        }
-        current = step.down(current);
-      }
-    }
-    return current;
-  }
-
-  /** Diagnostic: list registered migration keys. */
-  list(): ReadonlyArray<string> {
-    return [...this.migrations.keys()].sort();
-  }
-
-  /** Reset the registry (tests). */
-  clear(): void {
-    this.migrations.clear();
-  }
-}
-
-/**
- * Skeleton migration 0 → 1 that today is a no-op. Future schema changes
- * land here and bump the IR version on the up() side.
- */
-export const NOOP_0_TO_1: Migration = Object.freeze({
-  from: 0,
-  to: 1,
-  up(spec) {
-    return { ...spec, version: 1 };
-  },
-  down(spec) {
-    return { ...spec, version: 0 };
-  },
-});
-
-/** A pre-built engine with the v0 → v1 skeleton registered. */
-export function createDefaultEngine(): MigrationEngine {
-  const e = new MigrationEngine();
-  e.register(NOOP_0_TO_1);
-  return e;
-}