@platforma-sdk/model 1.81.1 → 1.83.0

package/src/block_storage_callbacks.ts

@@ -25,7 +25,12 @@ import {
 } from "./block_storage";
 import type { PluginHandle } from "./plugin_handle";
 
-import { stringifyJson, type StringifiedJson } from "@milaboratories/pl-model-common";
+import {
+  stringifyJson,
+  expandTemplateRefs,
+  relocateBlockIds,
+  type StringifiedJson,
+} from "@milaboratories/pl-model-common";
 import type { DataVersioned, TransferRecord } from "./block_migrations";
 import type { StorageDebugView } from "@milaboratories/pl-model-middle-layer";
 
@@ -237,7 +242,20 @@ export function migrateStorage(
  * @throws If initialDataFn or createPluginData throws
  */
 export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {
-  const blockDefault = hooks.getDefaultBlockData();
+  return assembleStorage(hooks.getDefaultBlockData(), hooks);
+}
+
+/**
+ * Wraps freshly created block data and freshly created plugin data into storage.
+ *
+ * Shared by the two ways a block's first storage comes into being — from defaults
+ * and from template params. Only the block's own data differs between them:
+ * plugins have no params channel, so they are always created at their defaults.
+ */
+function assembleStorage(
+  blockData: DataVersioned<unknown>,
+  hooks: Omit<InitialStorageHooks, "getDefaultBlockData">,
+): StringifiedJson<BlockStorage> {
   const pluginRegistry = hooks.getPluginRegistry();
 
   const plugins: Record<PluginHandle, VersionedData<unknown>> = {};
@@ -248,14 +266,238 @@ export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJso
 
   const storage: BlockStorage = {
     [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
-    __dataVersion: blockDefault.version,
-    __data: blockDefault.data,
+    __dataVersion: blockData.version,
+    __data: blockData.data,
     __pluginRegistry: pluginRegistry,
     __plugins: plugins,
   };
   return stringifyJson(storage);
 }
 
+/** Dependencies for creating storage from a template entry's params. */
+export interface ParamsStorageHooks extends Omit<InitialStorageHooks, "getDefaultBlockData"> {
+  /** The block's init factory, called with the entry's params. */
+  getBlockDataFromParams: (params: unknown) => DataVersioned<unknown>;
+  /**
+   * The kind's runtime params check. Applied before the factory sees anything, and its
+   * output is what the factory gets.
+   */
+  parseInitializationParams: (value: unknown) => unknown;
+}
+
+/** Result of checking params against their kind: the params to use, or why they lost. */
+export type TemplateParamsValidationResult =
+  | { error: string }
+  | { error?: undefined; value: unknown };
+
+/**
+ * Check params against their kind's declared shape.
+ *
+ * The kind owns this rather than the block because the params contract belongs to the
+ * kind: many block versions implement one kind, and a per-block check would let them
+ * drift from each other and from the type.
+ *
+ * A parser rejects by throwing and accepts by returning the params to use, so its
+ * output — not the input — is what flows onward. That is what lets a kind strip keys
+ * it does not declare, which is the difference between a typo being ignored and a typo
+ * being reported.
+ *
+ * Every kind declares a parser, so every set of params that reaches here is checked;
+ * there is no pass-through path.
+ *
+ * @param value The params to check, references already in live form
+ * @param parseInitializationParams The kind's parser
+ */
+export function validateTemplateParams(
+  value: unknown,
+  parseInitializationParams: (value: unknown) => unknown,
+): TemplateParamsValidationResult {
+  try {
+    return { value: parseInitializationParams(value) };
+  } catch (e) {
+    // A rejection is an expected outcome for a hand-written file, so it is reported,
+    // not thrown.
+    return { error: `params do not match this block's kind: ${describeRejection(e)}` };
+  }
+}
+
+/** One `{ path, message }` entry of a schema library's error. */
+type IssueLike = { path?: unknown; message?: unknown };
+
+/**
+ * Render whatever a parser threw as one readable line.
+ *
+ * An error carrying an `issues` array is unpacked rather than printed: that is the
+ * shape zod (and several others) use, and its `message` is the whole issue list as
+ * JSON — technically complete and unreadable in a dialog. Duck-typed on purpose, since
+ * this package prescribes no schema library and takes no dependency on one; anything
+ * else falls back to its own message.
+ */
+function describeRejection(e: unknown): string {
+  const issues = (e as { issues?: unknown }).issues;
+  if (!Array.isArray(issues) || issues.length === 0) return messageOf(e);
+
+  return issues
+    .map((issue) => {
+      const { path, message } = issue as IssueLike;
+      const what = typeof message === "string" ? message : "is invalid";
+      const where = Array.isArray(path) ? formatPath(path) : "";
+      return where === "" ? what : `${where}: ${what}`;
+    })
+    .join("; ");
+}
+
+/** `["numbers", 0]` → `numbers[0]` — how the params are written, not how they parse. */
+function formatPath(path: readonly unknown[]): string {
+  return path.reduce<string>((acc, segment) => {
+    if (typeof segment === "number") return `${acc}[${segment}]`;
+    return acc === "" ? String(segment) : `${acc}.${String(segment)}`;
+  }, "");
+}
+
+/**
+ * Result of the `__pl_params_validate` callback.
+ *
+ * Carries no params back. The check is a pre-flight — its answer is "may this entry be
+ * applied", and the params that actually reach the block are produced by
+ * {@link createInitialStorageFromParams}, which parses again. One authoritative
+ * producer, rather than two values that could differ.
+ */
+export type InitializationParamsValidateCallbackResult = { error: string } | { error?: undefined };
+
+/**
+ * Check params that crossed into the model VM as text.
+ *
+ * The pre-flight entry point: a caller asks this before creating anything, once per
+ * template entry, so params a kind rejects are reported while there is still no
+ * project to half-build.
+ *
+ * The readable reference spelling is expanded here too, so what the kind checks is the shape it
+ * declared. The ids it sees are the file's own — no block exists yet — which is why a kind must
+ * not read meaning into a specific id.
+ *
+ * @param paramsJson The entry's params as JSON string
+ * @param parseInitializationParams The kind's parser
+ */
+export function validateTemplateParamsJson(
+  paramsJson: string,
+  parseInitializationParams: (value: unknown) => unknown,
+): InitializationParamsValidateCallbackResult {
+  let params: unknown;
+  try {
+    params = JSON.parse(paramsJson);
+  } catch (e) {
+    return { error: `params are not valid JSON: ${messageOf(e)}` };
+  }
+
+  // Expanded before the kind sees anything, or a hand-written file would be rejected by every
+  // kind that declares a reference: `{ block, name }` is not a `PlRef` and no contract accepts
+  // one. Expansion needs nothing but the params, so this stays a two-argument check — the ids
+  // are not known yet and are not needed to answer the question this asks.
+  const result = validateTemplateParams(expandTemplateRefs(params), parseInitializationParams);
+  if (result.error !== undefined) return { error: result.error };
+  return {};
+}
+
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/**
+ * Result of building initial storage from params.
+ * Returned by the `__pl_storage_initialFromParams` callback.
+ */
+export type ParamsStorageResult =
+  | { error: string }
+  | { error?: undefined; storageJson: StringifiedJson<BlockStorage> };
+
+/**
+ * Creates complete initial storage for a block being created from template params.
+ *
+ * The inverse of {@link deriveTemplateParamsFromStorage}: that projects storage
+ * into params, this builds storage from them. The params are handed to the block's
+ * init factory, whose output is versioned and wrapped exactly as
+ * {@link createInitialStorage} wraps the defaults — so a block created from a
+ * template is indistinguishable from one created in the UI and then edited.
+ *
+ * **This is where a template's references become the block's own**, and it is the only place in
+ * a template's life where a reference is recognized at all. Params travel from the file
+ * untouched — the engine carrying them neither marks a reference nor reads one, because
+ * recognizing one means knowing the reference system, and that knowledge is here.
+ *
+ * Two things happen, in this order. The readable spelling a person may have written
+ * (`{ block, name }`) is expanded into the `PlRef` it stands for. Then every reference naming
+ * an entry that has a block is repointed at it: `blockIds` maps each template-local entry id to
+ * the block id it was given, and an id it does not name is left alone, which is how a reference
+ * to an entry created later ends up naming nothing rather than naming the wrong block.
+ *
+ * Relocation happens before the kind's parser and before the factory, so both see the ids the
+ * block will actually hold. It is one step of this function rather than a callback of its own
+ * precisely because nothing else wants its result: every VM call re-instantiates the runtime
+ * and re-evaluates the whole model bundle, so a separate call would parse the block twice per
+ * entry to produce a value only the next line reads.
+ *
+ * Params arrive as JSON text because this runs across the model-VM boundary, where
+ * only strings pass. Anything the factory rejects is returned as an error rather
+ * than thrown: applying a hand-written template is expected to surface bad params,
+ * and the applier reports every entry's problem in one pass.
+ *
+ * @param paramsJson - The entry's params as JSON string, exactly as the file held them
+ * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object
+ * @param hooks - The block's init factory plus plugin creation
+ * @returns The storage to write, or why the params could not produce any
+ */
+export function createInitialStorageFromParams(
+  paramsJson: string,
+  blockIdsJson: string,
+  hooks: ParamsStorageHooks,
+): ParamsStorageResult {
+  let params: unknown;
+  try {
+    params = JSON.parse(paramsJson);
+  } catch (e) {
+    return { error: `params are not valid JSON: ${messageOf(e)}` };
+  }
+
+  // Read separately from the params, and reported separately, because the two fail for
+  // completely different reasons. Params are the file's and a bad one is the author's mistake;
+  // this argument is the caller's, so the only way it arrives unreadable is a caller that does
+  // not send it — a middle layer older than this block, which is a build to refresh rather than
+  // anything to fix in the template. Folding both into one message sent the reader to the file.
+  let blockIds: Map<string, string>;
+  try {
+    blockIds = new Map(Object.entries(JSON.parse(blockIdsJson) as Record<string, string>));
+  } catch (e) {
+    return {
+      error:
+        `this block was not told which blocks the template's references should point at ` +
+        `(${messageOf(e)}). The application applying the template is older than the block; ` +
+        `rebuild or update it.`,
+    };
+  }
+
+  try {
+    // Spelling first, ids second. Expansion turns `{ block, name }` into a `PlRef` naming an
+    // ENTRY, which is exactly what relocation then repoints — so both spellings reach the
+    // block through the same step and cannot diverge in how they behave.
+    params = relocateBlockIds(expandTemplateRefs(params), blockIds);
+  } catch (e) {
+    return { error: `this entry's references could not be relocated: ${messageOf(e)}` };
+  }
+
+  // Checked here too, not only in the caller's pre-flight pass. The pre-flight is
+  // about reporting every bad entry before anything is created; this is about the
+  // factory never being handed a value the kind rejects, whichever path got here.
+  const checked = validateTemplateParams(params, hooks.parseInitializationParams);
+  if (checked.error !== undefined) return { error: checked.error };
+
+  try {
+    return { storageJson: assembleStorage(hooks.getBlockDataFromParams(checked.value), hooks) };
+  } catch (e) {
+    return { error: `init() threw on the given params: ${messageOf(e)}` };
+  }
+}
+
 // =============================================================================
 // Args Derivation from Storage
 // =============================================================================
@@ -271,19 +513,19 @@ export type ArgsDeriveResult = { error: string } | { error?: undefined; value: u
  * This extracts data from storage and passes it to the block's args() function.
  *
  * @param storageJson - Storage as JSON string
- * @param argsFunction - The block's args derivation function
+ * @param deriveArgs - The block's args derivation function
  * @returns ArgsDeriveResult with derived args or error
  */
 export function deriveArgsFromStorage(
   storageJson: string,
-  argsFunction: (data: unknown) => unknown,
+  deriveArgs: (data: unknown) => unknown,
 ): ArgsDeriveResult {
   // Extract data from storage
   const { data } = normalizeStorage(storageJson);
 
   // Call the args function with extracted data
   try {
-    const result = argsFunction(data);
+    const result = deriveArgs(data);
     return { value: result };
   } catch (e) {
     const errorMsg = e instanceof Error ? e.message : String(e);
@@ -293,25 +535,25 @@ export function deriveArgsFromStorage(
 
 /**
  * Derives prerunArgs from storage.
- * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.
+ * Uses derivePrerunArgs if provided, otherwise falls back to deriveArgs.
  *
  * @param storageJson - Storage as JSON string
- * @param argsFunction - The block's args derivation function (fallback)
- * @param prerunArgsFunction - Optional prerun args derivation function
+ * @param deriveArgs - The block's args derivation function (fallback)
+ * @param derivePrerunArgs - Optional prerun args derivation function
  * @returns ArgsDeriveResult with derived prerunArgs or error
  */
 export function derivePrerunArgsFromStorage(
   storageJson: string,
-  argsFunction: (data: unknown) => unknown,
-  prerunArgsFunction?: (data: unknown) => unknown,
+  deriveArgs: (data: unknown) => unknown,
+  derivePrerunArgs?: (data: unknown) => unknown,
 ): ArgsDeriveResult {
   // Extract data from storage
   const { data } = normalizeStorage(storageJson);
 
   // Try prerunArgs function first if available
-  if (prerunArgsFunction) {
+  if (derivePrerunArgs) {
     try {
-      const result = prerunArgsFunction(data);
+      const result = derivePrerunArgs(data);
       return { value: result };
     } catch (e) {
       const errorMsg = e instanceof Error ? e.message : String(e);
@@ -321,7 +563,7 @@ export function derivePrerunArgsFromStorage(
 
   // Fall back to args function
   try {
-    const result = argsFunction(data);
+    const result = deriveArgs(data);
     return { value: result };
   } catch (e) {
     const errorMsg = e instanceof Error ? e.message : String(e);
@@ -329,5 +571,42 @@ export function derivePrerunArgsFromStorage(
   }
 }
 
+// =============================================================================
+// Template Entry Derivation from Storage
+// =============================================================================
+
+/**
+ * Derives this block's template-entry params from storage.
+ *
+ * The inverse of the data model's `init`: `init` turns `params` into data, this
+ * turns data back into the params that would recreate it.
+ *
+ * The lambda returns ordinary live params — references as `PlRef`s, column identifiers as they
+ * are stored — and that is exactly what gets written. Nothing is marked, normalized or
+ * rewritten on the way out: a template holds what the block holds. Repointing those references
+ * at another project is the business of {@link createInitialStorageFromParams}, on the way back
+ * in, where the ids to point at are known.
+ *
+ * Every block declares the lambda, so every export produces params; a block with
+ * nothing worth restoring returns `{}` rather than declining.
+ *
+ * @param storageJson - Storage as JSON string
+ * @param deriveTemplateParams - The block's templateParams lambda
+ * @returns ArgsDeriveResult holding the params exactly as the block projected them
+ */
+export function deriveTemplateParamsFromStorage<TP extends (data: unknown) => unknown>(
+  storageJson: string,
+  deriveTemplateParams: TP,
+): ArgsDeriveResult {
+  const { data } = normalizeStorage(storageJson);
+
+  try {
+    return { value: deriveTemplateParams(data) };
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    return { error: `templateParams() threw: ${errorMsg}` };
+  }
+}
+
 // Export discriminator key and schema version for external checks
 export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };

package/src/block_storage_facade.ts

@@ -82,6 +82,9 @@ export const BlockStorageFacadeCallbacks = {
   ArgsDerive: "__pl_args_derive",
   PrerunArgsDerive: "__pl_prerunArgs_derive",
   StorageInitial: "__pl_storage_initial",
+  InitializationParamsDerive: "__pl_initializationParams_derive",
+  StorageInitialFromParams: "__pl_storage_initialFromParams",
+  InitializationParamsValidate: "__pl_initializationParams_validate",
 } as const;
 
 /**
@@ -189,6 +192,98 @@ export interface BlockStorageFacade {
    * @returns Initial storage as JSON string
    */
   [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;
+
+  /**
+   * Derive this block's template entry params from storage.
+   * Called when exporting the project as a template.
+   *
+   * Every V3 block declares `.templateParams()` — the model does not build without
+   * it — so every export produces params. A block whose state carries nothing worth
+   * restoring returns `{}`, which is written out and used as-is by init.
+   *
+   * The returned params are written out exactly as they come back, references included: the
+   * template engine carrying them recognizes nothing in there, and the block that receives
+   * them on the way back in is what repoints them. The caller supplies everything else in the
+   * entry — `id`, `kind` — so the lambda cannot set them.
+   *
+   * @param storageJson - Storage as JSON string
+   * @returns Either an error, or the params to write
+   */
+  [BlockStorageFacadeCallbacks.InitializationParamsDerive]: (
+    storageJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; value: unknown };
+
+  /**
+   * Get initial storage JSON for a block created from params.
+   * Called when applying a template, once per entry that carries `params`.
+   *
+   * The mirror image of {@link BlockStorageFacadeCallbacks.InitializationParamsDerive}:
+   * that one turns storage into params, this one turns params into storage. Every
+   * applied entry comes through here, including one whose file omitted `params` —
+   * an omitted key is read as `{}` and checked like any other value, so no entry
+   * reaches a block without passing its kind's contract.
+   * {@link BlockStorageFacadeCallbacks.StorageInitial} stays the UI-creation path,
+   * where there are genuinely no params.
+   *
+   * Separate from `StorageInitial` rather than an optional argument to it,
+   * deliberately: a block bundled with an older SDK does not register this
+   * callback at all, so the caller sees it missing and can say so. Widening
+   * `StorageInitial` would instead have that block silently ignore the params and
+   * produce a default-initialized block that looks successfully applied.
+   *
+   * The params arrive as ordinary live params — references are `PlRef`s, already
+   * pointing at the ids the target project just assigned. Resolution happens in
+   * the engine, before this call, so a block's init factory never handles a
+   * template-local reference.
+   *
+   * Errors are returned, not thrown: a factory rejecting params it cannot use is
+   * an expected outcome for a hand-written template file, and every entry's
+   * problem is reported together.
+   *
+   * **Also where the entry's references are pointed at this project.** Params reach here
+   * exactly as the file held them: nothing between the block that exported them and this call
+   * marks a reference, reads one, or rewrites one, because recognizing one means knowing the
+   * reference system and this bundle is where that knowledge lives. `blockIdsJson` maps each
+   * template-local entry id to the block id it was given, holding the entries created so far —
+   * so an id it does not name is left alone, and a reference to an entry created later names
+   * nothing rather than naming the wrong block.
+   *
+   * Relocating and initializing are one call rather than two because every call
+   * re-instantiates the runtime and re-evaluates the whole model bundle: splitting them would
+   * parse the block twice per entry to produce an intermediate only the second half reads.
+   *
+   * @param paramsJson - The entry's params as JSON string, as the file held them
+   * @param blockIdsJson - template-local entry id → assigned block id, as a JSON object
+   * @returns Either an error, or the initial storage as JSON string
+   */
+  [BlockStorageFacadeCallbacks.StorageInitialFromParams]: (
+    paramsJson: StringifiedJson,
+    blockIdsJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; storageJson: StringifiedJson };
+
+  /**
+   * Check params against this block's kind, creating nothing.
+   *
+   * Called once per entry before a template is applied, so params a kind rejects are
+   * reported against the entry that carries them while there is still no project — the
+   * same reason references and ids are checked before construction starts. Applying
+   * without this call is safe but worse: `StorageInitialFromParams` runs the same check
+   * and refuses, by which point earlier entries have already been created.
+   *
+   * A pass carries nothing back but its own absence of error: every kind declares a
+   * parser, so a pass means the params were checked against the contract, not merely
+   * that they were valid JSON.
+   *
+   * Reference ids inside the params may be placeholders at this point: the check runs
+   * before blocks exist, so what is verified is the shape of the params, not what they
+   * point at.
+   *
+   * @param paramsJson The entry's params as JSON string
+   * @returns Why the params were rejected, or nothing
+   */
+  [BlockStorageFacadeCallbacks.InitializationParamsValidate]: (
+    paramsJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined };
 }
 
 /** Register all facade callbacks at once. Ensures all required callbacks are provided. */

package/src/config/index.ts

@@ -1,6 +1,2 @@
-export * from "./actions";
-export * from "./actions_kinds";
 export * from "./model";
-export * from "./model_meta";
 export * from "./type_engine";
-export { type Checked } from "./type_util";

package/src/config/type_engine.ts

@@ -1,54 +1,11 @@
-import type { ActGetImmediate } from "./actions_kinds";
 import type { Cfg } from "./model";
 
-// Higher kind types pattern taken from here: https://code.lol/post/programming/higher-kinded-types/
-
-type GenericFunction = (x: any) => unknown;
-
-/** This is a type constructor deriving a returned type of config given the
- * context type. Something like ConfAction<Cfg> -> ReturnedType.  */
-export interface ConfAction {
-  readonly ctx: unknown;
-  new: GenericFunction;
-  isSync: boolean;
-}
-
-/** This type basically sets parameter to a ConfAction kind. */
-export type ActionResult<A extends ConfAction, Ctx> = ReturnType<
-  (A & {
-    readonly ctx: Ctx;
-  })["new"]
->;
-
-// Branding pattern taken from here: https://egghead.io/blog/using-branded-types-in-typescript
-
-/** Field key to attach ConfAction information to a config type. */
-declare const __config_action__: unique symbol;
-
-/** Creates branded Cfg type */
-export type TypedConfig<Action extends ConfAction = ConfAction> = Cfg & {
-  [__config_action__]: Action;
-};
-
-export type PrimitiveOrConfig = TypedConfig | string | number | boolean | null;
-
-/** Converts primitive types to immediate config */
-export type PrimitiveToCfg<T extends PrimitiveOrConfig> = T extends string | number | boolean | null
-  ? TypedConfig<ActGetImmediate<T>>
-  : T;
-
-/** Extracts action */
-export type ExtractAction<Cfg extends TypedConfig> = Cfg[typeof __config_action__];
-
-export type POCExtractAction<T extends PrimitiveOrConfig> = ExtractAction<PrimitiveToCfg<T>>;
-
-export type InferVarTypeSafe<Ctx, V> = V extends string
-  ? Ctx extends { [key in V]: infer T }
-    ? T
-    : undefined
-  : unknown;
-
-export type ConfigResult<Cfg extends TypedConfig, Ctx> = ActionResult<ExtractAction<Cfg>, Ctx>;
+/** Config tree of an already published block, as stored in its compiled model.
+ *
+ * Nothing in the SDK builds these any more — the builder DSL that produced them
+ * went away with the v1/v2 block model. The type is kept because the middle
+ * layer still has to read and render configs of blocks published before that. */
+export type TypedConfig = Cfg;
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 declare const plResourceEntry: unique symbol;

package/src/index.ts

@@ -22,7 +22,6 @@ export {
   getPluginData,
 } from "./block_storage";
 export * from "./block_storage_facade";
-export * from "./block_model_legacy";
 export { BlockModelV3 } from "./block_model";
 export type { PluginRecord, ParamsInput } from "./block_model";
 export { DataModel, DataModelBuilder } from "./block_migrations";
@@ -47,7 +46,6 @@ export * from "./pframe";
 export * from "./labels";
 export * from "./columns";
 export * from "./platforma";
-export * from "./ref_util";
 export * from "./render";
 export * from "./version";
 export * from "./raw_globals";