@platforma-sdk/model 1.54.13 → 1.55.0

package/src/block_migrations.test.ts

@@ -1,39 +1,5 @@
 import { describe, expect, it } from "vitest";
-import {
-  DataModelBuilder,
-  defaultRecover,
-  defineDataVersions,
-  makeDataVersioned,
-} from "./block_migrations";
-
-describe("defineDataVersions", () => {
-  it("throws on duplicate version values", () => {
-    expect(() =>
-      defineDataVersions({
-        V1: "v1",
-        V2: "v1", // duplicate!
-      }),
-    ).toThrow("Duplicate version values: v1");
-  });
-
-  it("throws on empty version values", () => {
-    expect(() =>
-      defineDataVersions({
-        V1: "v1",
-        V2: "", // empty!
-      }),
-    ).toThrow("Version values must be non-empty strings (empty: V2)");
-  });
-
-  it("allows unique version values", () => {
-    const versions = defineDataVersions({
-      V1: "v1",
-      V2: "v2",
-    });
-    expect(versions.V1).toBe("v1");
-    expect(versions.V2).toBe("v2");
-  });
-});
+import { DataModelBuilder, defaultRecover, makeDataVersioned } from "./block_migrations";
 
 describe("makeDataVersioned", () => {
   it("creates correct DataVersioned shape", () => {
@@ -44,19 +10,9 @@ describe("makeDataVersioned", () => {
 
 describe("DataModel migrations", () => {
   it("resets to initial data on unknown version", () => {
-    const Version = defineDataVersions({
-      V1: "v1",
-      V2: "v2",
-    });
-
-    type VersionedData = {
-      [Version.V1]: { count: number };
-      [Version.V2]: { count: number; label: string };
-    };
-
-    const dataModel = new DataModelBuilder<VersionedData>()
-      .from(Version.V1)
-      .migrate(Version.V2, (v1) => ({ ...v1, label: "" }))
+    const dataModel = new DataModelBuilder()
+      .from<{ count: number }>("v1")
+      .migrate<{ count: number; label: string }>("v2", (v1) => ({ ...v1, label: "" }))
       .init(() => ({ count: 0, label: "" }));
 
     const result = dataModel.migrate(makeDataVersioned("legacy", { count: 42 }));
@@ -65,141 +21,155 @@ describe("DataModel migrations", () => {
     expect(result.warning).toBe(`Unknown version 'legacy'`);
   });
 
-  it("uses recover() for unknown versions", () => {
-    const Version = defineDataVersions({
-      V1: "v1",
-      V2: "v2",
-    });
+  it("throws at build time on duplicate version key", () => {
+    expect(() =>
+      new DataModelBuilder()
+        .from<{ count: number }>("v1")
+        .migrate<{ count: number; label: string }>("v2", (v1) => ({ ...v1, label: "" }))
+        .migrate<{ count: number; label: string; description: string }>("v1", (v2) => ({
+          ...v2,
+          description: "",
+        })),
+    ).toThrow("Duplicate version 'v1' in migration chain");
+  });
 
-    type VersionedData = {
-      [Version.V1]: { count: number };
-      [Version.V2]: { count: number; label: string };
-    };
-
-    const dataModel = new DataModelBuilder<VersionedData>()
-      .from(Version.V1)
-      .migrate(Version.V2, (v1) => ({ ...v1, label: "" }))
-      .recover((version, data) => {
-        if (version === "legacy" && typeof data === "object" && data !== null && "count" in data) {
-          return { count: (data as { count: number }).count, label: "recovered" };
-        }
-        return defaultRecover(version, data);
+  it("returns initial data on migration failure", () => {
+    const dataModel = new DataModelBuilder()
+      .from<{ numbers: number[] }>("v1")
+      .migrate<{ numbers: number[]; label: string }>("v2", (v1) => {
+        if (v1.numbers.includes(666)) throw new Error("Forbidden number");
+        return { ...v1, label: "ok" };
       })
-      .init(() => ({ count: 0, label: "" }));
+      .init(() => ({ numbers: [], label: "" }));
 
-    const result = dataModel.migrate(makeDataVersioned("legacy", { count: 7 }));
+    const result = dataModel.migrate(makeDataVersioned("v1", { numbers: [666] }));
     expect(result.version).toBe("v2");
-    expect(result.data).toStrictEqual({ count: 7, label: "recovered" });
-    expect(result.warning).toBeUndefined();
+    expect(result.data).toStrictEqual({ numbers: [], label: "" });
+    expect(result.warning).toBe(`Migration v1→v2 failed: Forbidden number`);
   });
 
-  it("allows recover() to delegate to defaultRecover", () => {
-    const Version = defineDataVersions({
-      V1: "v1",
-      V2: "v2",
+  describe("recover()", () => {
+    it("recover() after from() — handles unknown version before any migrations run", () => {
+      const dataModel = new DataModelBuilder()
+        .from<{ count: number }>("v1")
+        .recover((version, data) => {
+          if (
+            version === "legacy" &&
+            typeof data === "object" &&
+            data !== null &&
+            "count" in data
+          ) {
+            return { count: (data as { count: number }).count };
+          }
+          return defaultRecover(version, data);
+        })
+        .migrate<{ count: number; label: string }>("v2", (v1) => ({ ...v1, label: "default" }))
+        .init(() => ({ count: 0, label: "" }));
+
+      // Legacy data is recovered as V1 then goes through v1→v2 migration
+      const result = dataModel.migrate(makeDataVersioned("legacy", { count: 5 }));
+      expect(result.version).toBe("v2");
+      expect(result.data).toStrictEqual({ count: 5, label: "default" });
+      expect(result.warning).toBeUndefined();
     });
 
-    type VersionedData = {
-      [Version.V1]: { count: number };
-      [Version.V2]: { count: number; label: string };
-    };
-
-    const dataModel = new DataModelBuilder<VersionedData>()
-      .from(Version.V1)
-      .migrate(Version.V2, (v1) => ({ ...v1, label: "" }))
-      .recover((version, data) => defaultRecover(version, data))
-      .init(() => ({ count: 0, label: "" }));
+    it("recover() between migrations — recovered data goes through subsequent migrations", () => {
+      type V2 = { count: number; label: string };
+      type V3 = { count: number; label: string; description: string };
+
+      const dataModel = new DataModelBuilder()
+        .from<{ count: number }>("v1")
+        .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
+        .recover((version, data) => {
+          if (
+            version === "legacy" &&
+            typeof data === "object" &&
+            data !== null &&
+            "count" in data
+          ) {
+            return { count: (data as { count: number }).count, label: "recovered" };
+          }
+          return defaultRecover(version, data);
+        })
+        .migrate<V3>("v3", (v2) => ({ ...v2, description: "added" }))
+        .init(() => ({ count: 0, label: "", description: "" }));
+
+      const result = dataModel.migrate(makeDataVersioned("legacy", { count: 7 }));
+      expect(result.version).toBe("v3");
+      expect(result.data).toStrictEqual({ count: 7, label: "recovered", description: "added" });
+      expect(result.warning).toBeUndefined();
+    });
 
-    const result = dataModel.migrate(makeDataVersioned("legacy", { count: 7 }));
-    expect(result.version).toBe("v2");
-    expect(result.data).toStrictEqual({ count: 0, label: "" });
-    expect(result.warning).toBe(`Unknown version 'legacy'`);
-  });
+    it("recover() at the end of chain — recovered data is the final type", () => {
+      type V2 = { count: number; label: string };
+
+      const dataModel = new DataModelBuilder()
+        .from<{ count: number }>("v1")
+        .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
+        .recover((version, data) => {
+          if (
+            version === "legacy" &&
+            typeof data === "object" &&
+            data !== null &&
+            "count" in data
+          ) {
+            return { count: (data as { count: number }).count, label: "recovered" };
+          }
+          return defaultRecover(version, data);
+        })
+        .init(() => ({ count: 0, label: "" }));
+
+      const result = dataModel.migrate(makeDataVersioned("legacy", { count: 9 }));
+      expect(result.version).toBe("v2");
+      expect(result.data).toStrictEqual({ count: 9, label: "recovered" });
+      expect(result.warning).toBeUndefined();
+    });
 
-  it("returns initial data on migration failure", () => {
-    const Version = defineDataVersions({
-      V1: "v1",
-      V2: "v2",
+    it("recover() delegates to defaultRecover for truly unknown versions", () => {
+      const dataModel = new DataModelBuilder()
+        .from<{ count: number }>("v1")
+        .migrate<{ count: number; label: string }>("v2", (v1) => ({ ...v1, label: "" }))
+        .recover((version, data) => defaultRecover(version, data))
+        .init(() => ({ count: 0, label: "" }));
+
+      const result = dataModel.migrate(makeDataVersioned("unknown", { count: 7 }));
+      expect(result.version).toBe("v2");
+      expect(result.data).toStrictEqual({ count: 0, label: "" });
+      expect(result.warning).toBe(`Unknown version 'unknown'`);
     });
 
-    type VersionedData = {
-      [Version.V1]: { numbers: number[] };
-      [Version.V2]: { numbers: number[]; label: string };
-    };
-
-    const dataModel = new DataModelBuilder<VersionedData>()
-      .from(Version.V1)
-      .migrate(Version.V2, (v1) => {
-        if (v1.numbers.includes(666)) {
-          throw new Error("Forbidden number");
-        }
-        return { ...v1, label: "ok" };
-      })
-      .init(() => ({ numbers: [], label: "" }));
+    it("migration failure after recover() resets to initial data", () => {
+      type V2 = { count: number; label: string };
+      type V3 = { count: number; label: string; description: string };
+
+      const dataModel = new DataModelBuilder()
+        .from<{ count: number }>("v1")
+        .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
+        .recover((version, data) => {
+          if (
+            version === "legacy" &&
+            typeof data === "object" &&
+            data !== null &&
+            "count" in data
+          ) {
+            return { count: (data as { count: number }).count, label: "recovered" };
+          }
+          return defaultRecover(version, data);
+        })
+        .migrate<V3>("v3", (_v2) => {
+          throw new Error("v3 failed");
+        })
+        .init(() => ({ count: 0, label: "", description: "" }));
+
+      const result = dataModel.migrate(makeDataVersioned("legacy", { count: 7 }));
+      expect(result.version).toBe("v3");
+      expect(result.data).toStrictEqual({ count: 0, label: "", description: "" });
+      expect(result.warning).toBe("Migration v2→v3 failed: v3 failed");
+    });
 
-    const result = dataModel.migrate(makeDataVersioned("v1", { numbers: [666] }));
-    expect(result.version).toBe("v2");
-    expect(result.data).toStrictEqual({ numbers: [], label: "" });
-    expect(result.warning).toBe(`Migration v1→v2 failed: Forbidden number`);
+    it("recover() cannot be called twice — enforced by type (no recover() on WithRecover)", () => {
+      // This is a compile-time-only check — WithRecover has no recover() method.
+      // Verified by the absence of recover() in DataModelMigrationChainWithRecover.
+    });
   });
 });
-
-function _compileTimeTypeChecks() {
-  const Version = defineDataVersions({
-    V1: "v1",
-    V2: "v2",
-  });
-
-  type VersionedData = {
-    [Version.V1]: { count: number };
-    [Version.V2]: { count: number; label: string };
-  };
-
-  // Valid: complete migration chain
-  new DataModelBuilder<VersionedData>()
-    .from(Version.V1)
-    .migrate(Version.V2, (v1) => ({ ...v1, label: "" }))
-    .init(() => ({ count: 0, label: "" }));
-
-  // Valid: with recover()
-  new DataModelBuilder<VersionedData>()
-    .from(Version.V1)
-    .migrate(Version.V2, (v1) => ({ ...v1, label: "" }))
-    .recover((version, data) => defaultRecover(version, data))
-    .init(() => ({ count: 0, label: "" }));
-
-  new DataModelBuilder<VersionedData>()
-    // @ts-expect-error invalid initial version key
-    .from("v3");
-
-  new DataModelBuilder<VersionedData>()
-    .from(Version.V1)
-    // @ts-expect-error invalid migration target key
-    .migrate("v3", (v1) => ({ ...v1, label: "" }));
-
-  new DataModelBuilder<VersionedData>()
-    .from(Version.V1)
-    // @ts-expect-error migration return type must match target version
-    .migrate(Version.V2, (v1) => ({ ...v1, invalid: true }));
-
-  // Incomplete migration chain - V2 not covered
-  // This errors at compile-time with the `this` parameter constraint:
-  // "The 'this' context of type 'DataModelMigrationChain<..., "v1", "v2">' is not assignable to method's 'this' of type 'DataModelMigrationChain<..., "v1", never>'"
-  // Note: @ts-expect-error doesn't work reliably in unused functions
-  // new DataModelBuilder<VersionedData>()
-  //   .from(Version.V1)
-  //   .init(() => ({ count: 0 }));
-
-  new DataModelBuilder<VersionedData>()
-    .from(Version.V1)
-    .migrate(Version.V2, (v1) => ({ ...v1, label: "" }))
-    .recover((version, data) => defaultRecover(version, data))
-    // @ts-expect-error recover() returns builder without recover() method - cannot call twice (only init() available)
-    .recover((version, data) => defaultRecover(version, data));
-
-  new DataModelBuilder<VersionedData>()
-    .from(Version.V1)
-    .recover((version, data) => defaultRecover(version, data))
-    // @ts-expect-error recover() returns builder without migrate() method (only init() available)
-    .migrate(Version.V2, (v1) => ({ ...v1, label: "" }));
-}