@platforma-sdk/model 1.81.0 → 1.82.0

package/src/template_init.test.ts

@@ -0,0 +1,413 @@
+import { describe, expect, test } from "vitest";
+import type { PlRef } from "@milaboratories/pl-model-common";
+import { createPlRef, stringifyJson } from "@milaboratories/pl-model-common";
+import type { PluginHandle } from "./plugin_handle";
+import type { PluginName } from "./block_storage";
+import { BLOCK_STORAGE_KEY, createBlockStorage, isBlockStorage } from "./block_storage";
+import {
+  createInitialStorage,
+  createInitialStorageFromParams,
+  deriveTemplateParamsFromStorage,
+  validateTemplateParams,
+  validateTemplateParamsJson,
+} from "./block_storage_callbacks";
+import { DataModelBuilder } from "./block_migrations";
+import { defineBlockKind } from "@platforma-sdk/block-kind";
+
+/**
+ * The apply half of the template contract: params in, storage out.
+ *
+ * `template_params.test.ts` covers the export direction. These cover the inverse,
+ * plus the one property that ties the two together — params that survive a round
+ * trip through storage.
+ */
+
+type Params = { sources?: PlRef[]; label: string };
+
+/**
+ * Deliberately permissive: these tests are about what the apply path does with params
+ * the kind already accepted, so the parser here only carries the shape through. The
+ * rejection behaviour is covered by the `validateTemplateParams` cases below, which
+ * supply their own strict parsers.
+ */
+const passThrough = (value: unknown) => value as Params;
+
+/**
+ * No entries created yet, so nothing to repoint.
+ *
+ * Relocation is the callback's other half and is covered where it lives — `relocateBlockIds`
+ * in `pl-model-common`. What these tests drive is the factory and the shape of the storage it
+ * produces, and an empty map keeps the params arriving exactly as written.
+ */
+const NO_IDS = JSON.stringify({});
+
+const kind = defineBlockKind<Params>({
+  name: "@platforma-open/milaboratories.demo.kind",
+  version: "1.0.0",
+  parseInitializationParams: passThrough,
+});
+
+type BlockData = { sources: PlRef[]; label: string; scratch: number };
+
+const dataModel = new DataModelBuilder({ kind }).from<BlockData>("v1").init(({ params }) => ({
+  sources: params?.sources ?? [],
+  label: params?.label ?? "",
+  scratch: 0,
+}));
+
+const upstream = "3f1c2b7a-0000-4000-8000-000000000001";
+
+/** Hooks for a block with no plugins — the common case. */
+const noPlugins = {
+  getPluginRegistry: () => ({}),
+  createPluginData: () => {
+    throw new Error("no plugins registered");
+  },
+};
+
+const fromParams = (params: unknown) =>
+  createInitialStorageFromParams(JSON.stringify(params), NO_IDS, {
+    getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+    parseInitializationParams: passThrough,
+    ...noPlugins,
+  });
+
+/** Storage the callback produced, parsed back. Fails the test if it errored. */
+function storageOf(result: ReturnType<typeof fromParams>) {
+  if (result.error !== undefined) throw new Error(`expected storage, got: ${result.error}`);
+  return JSON.parse(result.storageJson) as Record<string, unknown>;
+}
+
+describe("createInitialStorageFromParams", () => {
+  test("the block's init factory receives the entry's params", () => {
+    const storage = storageOf(fromParams({ label: "run 1" }));
+
+    expect(storage.__data).toEqual({ sources: [], label: "run 1", scratch: 0 });
+  });
+
+  test("references arrive as PlRefs and land in data untouched", () => {
+    // The engine resolves template-local references before this point, so what the
+    // factory sees is an ordinary live reference to a block that already exists.
+    const ref = createPlRef(upstream, "reads");
+    const storage = storageOf(fromParams({ label: "wired", sources: [ref] }));
+
+    expect((storage.__data as BlockData).sources).toEqual([ref]);
+  });
+
+  test("the result is well-formed storage at the current data version", () => {
+    const storage = storageOf(fromParams({ label: "x" }));
+
+    expect(isBlockStorage(storage)).toBe(true);
+    expect(storage[BLOCK_STORAGE_KEY]).toBeDefined();
+    expect(storage.__dataVersion).toBe(dataModel.version);
+  });
+
+  test("a block created from params is shaped exactly like one created from defaults", () => {
+    // Same envelope, only `__data` differs — which is what lets an applied block be
+    // read, migrated and edited by every path that never heard of templates.
+    const fromDefaults = JSON.parse(
+      createInitialStorage({
+        getDefaultBlockData: () => dataModel.getDefaultData(),
+        getPluginRegistry: noPlugins.getPluginRegistry,
+        createPluginData: noPlugins.createPluginData,
+      }),
+    ) as Record<string, unknown>;
+    const applied = storageOf(fromParams({ label: "x" }));
+
+    expect(Object.keys(applied).sort()).toEqual(Object.keys(fromDefaults).sort());
+    expect({ ...applied, __data: null }).toEqual({ ...fromDefaults, __data: null });
+  });
+
+  test("empty params are used as-is, not treated as absent", () => {
+    // An entry with `params: {}` says "initialize from nothing in particular";
+    // the factory's own fallbacks fill in, and the applier never substitutes
+    // defaults on the block's behalf.
+    expect(storageOf(fromParams({})).__data).toEqual({ sources: [], label: "", scratch: 0 });
+  });
+
+  test("params that are not valid JSON are reported", () => {
+    const result = createInitialStorageFromParams("{not json", NO_IDS, {
+      getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+      parseInitializationParams: passThrough,
+      ...noPlugins,
+    });
+
+    expect(result.error).toMatch(/params are not valid JSON/);
+  });
+
+  test("a factory that rejects the params is reported, not propagated", () => {
+    // The expected failure mode for a hand-written template file: params the block
+    // cannot make sense of. It must come back as a problem the applier can attach
+    // to an entry, not as a throw that aborts the whole apply.
+    const result = createInitialStorageFromParams(JSON.stringify({ label: "" }), NO_IDS, {
+      getBlockDataFromParams: () => {
+        throw new Error("label must not be empty");
+      },
+      parseInitializationParams: passThrough,
+      ...noPlugins,
+    });
+
+    expect(result).toEqual({ error: "init() threw on the given params: label must not be empty" });
+  });
+
+  test("plugins are created at their defaults, never from params", () => {
+    // Params belong to the block's kind; a plugin has no params channel, so it is
+    // initialized the same way whether the block came from a template or the UI.
+    const handle = "p1" as PluginHandle;
+    const result = createInitialStorageFromParams(JSON.stringify({ label: "x" }), NO_IDS, {
+      getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+      parseInitializationParams: passThrough,
+      getPluginRegistry: () => ({ [handle]: "demoPlugin" as PluginName }),
+      createPluginData: (h) => {
+        expect(h).toBe(handle);
+        return { version: "v1", data: { items: [] } };
+      },
+    });
+
+    expect(storageOf(result).__plugins).toEqual({
+      [handle]: { __dataVersion: "v1", __data: { items: [] } },
+    });
+  });
+});
+
+describe("DataModel.getDataFromParams", () => {
+  test("a factory that ignores params matches getDefaultData", () => {
+    const paramless = new DataModelBuilder().from<{ n: number }>("v1").init(() => ({ n: 7 }));
+
+    expect(paramless.getDataFromParams({ n: 99 })).toEqual(paramless.getDefaultData());
+  });
+
+  test("undefined params are what a factory sees from getDefaultData", () => {
+    // The two entry points must not diverge on the "no params" case: an entry
+    // without params goes through StorageInitial, and a factory written against
+    // `params?.x ?? default` has to behave identically either way.
+    expect(dataModel.getDataFromParams(undefined)).toEqual(dataModel.getDefaultData());
+  });
+});
+
+describe("params round trip", () => {
+  test("init then templateParams returns the params it started from", () => {
+    // The closest thing to an export→import round trip available without the engine: params
+    // → storage → params. It comes back byte-identical, references included — a template
+    // holds what the block holds, so the two ends of the trip have nothing to convert.
+    const params = { label: "run 1", sources: [createPlRef(upstream, "reads")] };
+
+    const storageJson = stringifyJson(
+      createBlockStorage(storageOf(fromParams(params)).__data as BlockData),
+    );
+    const derived = deriveTemplateParamsFromStorage(storageJson, (data) => {
+      const d = data as BlockData;
+      return { sources: d.sources, label: d.label };
+    });
+
+    expect(derived).toEqual({ value: params });
+  });
+});
+
+describe("validateTemplateParams", () => {
+  test("the parser's output is what flows on, not its input", () => {
+    // This is what makes a schema able to strip keys the kind does not declare, which
+    // is the difference between a typo being ignored and a typo being caught.
+    const result = validateTemplateParams({ label: "x", stray: 1 }, () => ({ label: "x" }));
+
+    expect(result).toEqual({ value: { label: "x" } });
+  });
+
+  test("there is no unchecked pass", () => {
+    // Every kind declares a parser, so the result carries no "was this checked" flag:
+    // a pass means the params were held to the contract. A parser is the only way a
+    // value gets through, and one that rejects everything is still a parser.
+    expect(
+      validateTemplateParams({ anything: true }, () => {
+        throw new Error("this kind takes no params");
+      }).error,
+    ).toMatch(/do not match this block's kind/);
+  });
+});
+
+describe("params reaching init", () => {
+  test("init sees what the parser returned", () => {
+    const storage = storageOf(
+      createInitialStorageFromParams(JSON.stringify({ label: "raw", stray: 1 }), NO_IDS, {
+        getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+        parseInitializationParams: () => ({ label: "parsed" }),
+        ...noPlugins,
+      }),
+    );
+
+    expect((storage.__data as BlockData).label).toBe("parsed");
+  });
+
+  test("params the kind rejects never reach init", () => {
+    // Checked here as well as in the caller's pre-flight: the pre-flight exists to
+    // report every bad entry before anything is created, this exists so the factory is
+    // never handed a value the kind refused, whichever path got here.
+    let reached = false;
+    const result = createInitialStorageFromParams(JSON.stringify({ label: "" }), NO_IDS, {
+      getBlockDataFromParams: (p) => {
+        reached = true;
+        return dataModel.getDataFromParams(p);
+      },
+      parseInitializationParams: () => {
+        throw new Error("label must not be empty");
+      },
+      ...noPlugins,
+    });
+
+    expect(reached).toBe(false);
+    expect(result.error).toMatch(/do not match this block's kind/);
+  });
+});
+
+describe("validateTemplateParamsJson", () => {
+  test("valid params against a real schema", () => {
+    expect(validateTemplateParamsJson(JSON.stringify({ n: 1 }), (v) => v)).toEqual({});
+  });
+
+  test("a rejection comes back as a message, not a throw", () => {
+    const result = validateTemplateParamsJson(JSON.stringify({}), () => {
+      throw new Error("n: Required");
+    });
+
+    expect(result.error).toContain("n: Required");
+  });
+
+  test("params that are not JSON are reported", () => {
+    expect(validateTemplateParamsJson("{oops", (v) => v).error).toMatch(/not valid JSON/);
+  });
+});
+
+describe("the kind carries the check", () => {
+  test("a kind's parser reaches the data model that declared it", () => {
+    // The threading that makes any of this work: the kind object is not kept, but the
+    // parser is lifted off it beside the kind reference, so `done()` can register it.
+    const parse = (v: unknown) => v as Params;
+    const checkedKind = defineBlockKind<Params>({
+      name: "@platforma-open/milaboratories.checked.kind",
+      version: "1.0.0",
+      parseInitializationParams: parse,
+    });
+    const model = new DataModelBuilder({ kind: checkedKind })
+      .from<BlockData>("v1")
+      .init(() => ({ sources: [], label: "", scratch: 0 }));
+
+    expect(model.templateParamsParser).toBe(parse);
+  });
+
+  test("a kind-less data model carries no parser — the plugin case", () => {
+    // The only remaining way this slot is empty. A BLOCK data model always has a kind,
+    // and a kind always supplies a parser; a PLUGIN data model is built with no kind at
+    // all, because a plugin has no params channel of its own. Such a model can no longer
+    // reach `BlockModelV3.create`, so nothing reads this as a block's parser.
+    const pluginDataModel = new DataModelBuilder()
+      .from<BlockData>("v1")
+      .init(() => ({ sources: [], label: "", scratch: 0 }));
+
+    expect(pluginDataModel.templateParamsParser).toBeUndefined();
+  });
+});
+
+describe("how a rejection reads", () => {
+  test("a schema library's issue list is unpacked, not dumped as JSON", () => {
+    // A zod error's own `message` is the entire issue array as JSON. Complete, and
+    // unreadable in the dialog this ends up in. The shape is duck-typed because this
+    // package prescribes no schema library.
+    const zodLike = Object.assign(new Error("[{...}]"), {
+      issues: [
+        { code: "invalid_type", path: ["numbers", 0], message: "Expected number, received string" },
+        { code: "unrecognized_keys", path: [], message: "Unrecognized key(s) in object: 'colour'" },
+      ],
+    });
+
+    const result = validateTemplateParams({}, () => {
+      throw zodLike;
+    });
+
+    expect(result.error).toBe(
+      "params do not match this block's kind: numbers[0]: Expected number, received string; " +
+        "Unrecognized key(s) in object: 'colour'",
+    );
+  });
+
+  test("a path is written the way the params are written", () => {
+    const result = validateTemplateParams({}, () => {
+      throw Object.assign(new Error("x"), {
+        issues: [{ path: ["steps", 2, "name"], message: "Required" }],
+      });
+    });
+
+    expect(result.error).toContain("steps[2].name: Required");
+  });
+
+  test("a plain error keeps its own words", () => {
+    const result = validateTemplateParams({}, () => {
+      throw new Error("numbers must not be empty");
+    });
+
+    expect(result.error).toBe("params do not match this block's kind: numbers must not be empty");
+  });
+});
+
+describe("a caller that predates this callback", () => {
+  test("is named as the cause, instead of blaming the template's params", () => {
+    // A middle layer older than the block calls this with one argument, so the id map arrives
+    // as `undefined`. It happened for real: an entry with no references at all failed with
+    // "params are not valid JSON", sending the reader to a file that was perfectly fine.
+    const result = createInitialStorageFromParams(
+      JSON.stringify({ label: "x" }),
+      undefined as unknown as string,
+      {
+        getBlockDataFromParams: (p) => dataModel.getDataFromParams(p),
+        parseInitializationParams: passThrough,
+        ...noPlugins,
+      },
+    );
+
+    expect(result.error).toMatch(/not told which blocks/);
+    expect(result.error).toMatch(/older than the block; rebuild or update it/);
+  });
+});
+
+describe("the readable reference spelling", () => {
+  const hooks = () => ({
+    getBlockDataFromParams: (p: unknown) => dataModel.getDataFromParams(p),
+    parseInitializationParams: passThrough,
+    ...noPlugins,
+  });
+
+  test("becomes a PlRef, and is repointed like a long-form one", () => {
+    // What a hand-written file gets to say: `{ block, name }`, no `__isRef`. It arrives at the
+    // block as the reference it stands for, pointing at the block the entry was given.
+    const result = createInitialStorageFromParams(
+      JSON.stringify({ label: "x", sources: [{ block: "samples", name: "reads" }] }),
+      JSON.stringify({ samples: "block-1" }),
+      hooks(),
+    );
+
+    expect(JSON.parse(result.storageJson!).__data).toEqual({
+      label: "x",
+      sources: [createPlRef("block-1", "reads")],
+      scratch: 0,
+    });
+  });
+
+  test("the kind's parser is the check, and it sees the expanded form", () => {
+    // The whole reason expansion happens before the parser: a contract declared against `PlRef`
+    // would reject `{ block, name }` outright, so the readable spelling would be unusable.
+    const rejectsShorthand = (value: unknown) => {
+      const { sources } = value as { sources: unknown };
+      if (!Array.isArray(sources) || sources.some((s) => (s as PlRef).__isRef !== true)) {
+        throw new Error("'sources' must be an array of references");
+      }
+      return value as Params;
+    };
+
+    const result = createInitialStorageFromParams(
+      JSON.stringify({ label: "x", sources: [{ block: "samples", name: "reads" }] }),
+      JSON.stringify({}),
+      { ...hooks(), parseInitializationParams: rejectsShorthand },
+    );
+
+    expect(result.error).toBeUndefined();
+  });
+});

package/src/template_params.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, expectTypeOf, test } from "vitest";
+import type { PlRef } from "@milaboratories/pl-model-common";
+import { createPlRef, stringifyJson } from "@milaboratories/pl-model-common";
+import { createBlockStorage } from "./block_storage";
+import { deriveTemplateParamsFromStorage } from "./block_storage_callbacks";
+import { BlockModelV3 } from "./block_model";
+import { DataModelBuilder } from "./block_migrations";
+import { defineBlockKind } from "@platforma-sdk/block-kind";
+
+// A kind whose params carry a reference — the case that exercises the rewrite.
+type Params = { sources?: PlRef[]; label: string };
+
+const kind = defineBlockKind<Params>({
+  name: "@platforma-open/milaboratories.demo.kind",
+  version: "1.0.0",
+  // These tests are about the export direction, so the parser only carries the shape
+  // through; rejection behaviour lives in `template_init.test.ts`.
+  parseInitializationParams: (value) => value as Params,
+});
+
+type BlockData = { sources: PlRef[]; label: string; scratch: number };
+
+const dataModel = new DataModelBuilder({ kind }).from<BlockData>("v1").init(({ params }) => ({
+  sources: params?.sources ?? [],
+  label: params?.label ?? "",
+  // Derived/runtime state — must NOT survive into a template entry.
+  scratch: 0,
+}));
+
+const upstream = "3f1c2b7a-0000-4000-8000-000000000001";
+
+const storageOf = (data: BlockData) => stringifyJson(createBlockStorage(data));
+
+describe("deriveTemplateParamsFromStorage", () => {
+  test("projects data back to params, untouched", () => {
+    const result = deriveTemplateParamsFromStorage(
+      storageOf({ sources: [createPlRef(upstream, "reads")], label: "run 1", scratch: 42 }),
+      (data) => {
+        const d = data as BlockData;
+        return { sources: d.sources, label: d.label };
+      },
+    );
+
+    // `scratch` is dropped because the lambda does not return it. Everything the lambda DID
+    // return is written exactly as it is: the reference is not marked, normalized or rewritten
+    // on the way out, because pointing it at another project is the receiving block's job, on
+    // the way back in.
+    expect(result).toEqual({
+      value: { sources: [createPlRef(upstream, "reads")], label: "run 1" },
+    });
+  });
+
+  test("a block with nothing to project yields empty params, not absent ones", () => {
+    // Every block declares the lambda, so there is no "no params" outcome to test for.
+    // A block whose state carries nothing worth restoring returns `{}`, and `{}` is what
+    // gets written — the entry is still checked against the kind on the way back in.
+    expect(
+      deriveTemplateParamsFromStorage(
+        storageOf({ sources: [], label: "", scratch: 0 }),
+        () => ({}),
+      ),
+    ).toEqual({ value: {} });
+  });
+
+  test("a throwing lambda is reported, not propagated", () => {
+    const result = deriveTemplateParamsFromStorage(
+      storageOf({ sources: [], label: "", scratch: 0 }),
+      () => {
+        throw new Error("not exportable yet");
+      },
+    );
+
+    expect(result).toEqual({ error: "templateParams() threw: not exportable yet" });
+  });
+});
+
+describe("BlockModelV3.templateParams", () => {
+  test("the lambda's return type is the kind's params", () => {
+    const model = BlockModelV3.create({ dataModel, kind })
+      .args((data) => ({ label: data.label }))
+      .templateParams((data) => ({ sources: data.sources, label: data.label }));
+
+    expectTypeOf(model.templateParams).parameter(0).toEqualTypeOf<(data: BlockData) => Params>();
+  });
+
+  test("a projection that drifts from the kind's params does not compile", () => {
+    const builder = BlockModelV3.create({ dataModel, kind }).args((data) => ({
+      label: data.label,
+    }));
+
+    // @ts-expect-error - `label` is required by Params
+    builder.templateParams((data) => ({ sources: data.sources }));
+    // @ts-expect-error - wrong type for a declared param
+    builder.templateParams(() => ({ label: 42 }));
+  });
+
+  test("KNOWN HOLE: an extra field the kind does not declare is not rejected", () => {
+    const builder = BlockModelV3.create({ dataModel, kind }).args((data) => ({
+      label: data.label,
+    }));
+
+    // No `@ts-expect-error` here, and that is the point: TypeScript does not
+    // apply excess-property checks to an object literal returned from a
+    // contextually-typed arrow, so `scratch` type-checks and would be written
+    // into the exported file. The kind's parser does not catch it either — that runs
+    // on params coming IN, and nothing runs on what the projection hands back. The
+    // asymmetry is real: such a file is written happily and rejected on re-import by
+    // the same kind that would have caught it here. This test pins current behaviour.
+    builder.templateParams((data) => ({
+      label: data.label,
+      sources: data.sources,
+      scratch: data.scratch,
+    }));
+  });
+
+  test("a model that declares it builds", () => {
+    expect(() =>
+      BlockModelV3.create({ dataModel, kind })
+        .args((data) => ({ label: data.label }))
+        .templateParams((data) => ({ sources: data.sources, label: data.label }))
+        .done(),
+    ).not.toThrow();
+  });
+
+  test("a model that omits it does not build", () => {
+    // The projection is not optional. Without this gate a block exports an entry with
+    // no params, which applies as a default-initialized block that looks restored — so
+    // the failure has to land on whoever wrote the model, at build.
+    expect(() =>
+      BlockModelV3.create({ dataModel, kind })
+        .args((data) => ({ label: data.label }))
+        .done(),
+    ).toThrow(/templateParams\(\) not set/);
+  });
+});