@platforma-sdk/model 1.51.6 → 1.52.0

package/src/block_storage.ts

@@ -0,0 +1,365 @@
+/**
+ * BlockStorage - Typed storage abstraction for block persistent data.
+ *
+ * This module provides:
+ * - A typed structure for block storage with versioning and plugin support
+ * - Utility functions for manipulating storage
+ * - Handler interfaces for model-level customization
+ *
+ * @module block_storage
+ */
+
+// =============================================================================
+// Core Types
+// =============================================================================
+
+/**
+ * Discriminator key for BlockStorage format detection.
+ * This unique hash-based key identifies data as BlockStorage vs legacy formats.
+ */
+export const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';
+
+/**
+ * Current BlockStorage schema version.
+ * Increment this when the storage structure itself changes (not block state migrations).
+ */
+export const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';
+
+/**
+ * Type for valid schema versions
+ */
+export type BlockStorageSchemaVersion = 'v1'; // Add 'v2', 'v3', etc. as schema evolves
+
+/**
+ * Plugin key type - keys starting with `@plugin/` are reserved for plugin data
+ */
+export type PluginKey = `@plugin/${string}`;
+
+/**
+ * Core BlockStorage type that holds:
+ * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)
+ * - __dataVersion: Version number for block data migrations
+ * - __data: The block's user-facing data (state)
+ * - @plugin/*: Optional plugin-specific data
+ */
+export type BlockStorage<TState = unknown> = {
+  /** Schema version - the key itself is the discriminator */
+  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;
+  /** Version of the block data, used for migrations */
+  __dataVersion: number;
+  /** The block's user-facing data (state) */
+  __data: TState;
+} & {
+  /** Plugin-specific data, keyed by `@plugin/<pluginName>` */
+  [K in PluginKey]?: unknown;
+};
+
+/**
+ * Type guard to check if a value is a valid BlockStorage object.
+ * Checks for the discriminator key and valid schema version.
+ */
+export function isBlockStorage(value: unknown): value is BlockStorage {
+  if (value === null || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+  const schemaVersion = obj[BLOCK_STORAGE_KEY];
+  // Currently only 'v1' is valid, but this allows future versions
+  return schemaVersion === 'v1'; // Add more versions as schema evolves
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/**
+ * Creates a BlockStorage with the given initial data
+ *
+ * @param initialData - The initial data value (defaults to empty object)
+ * @param version - The initial data version (defaults to 1)
+ * @returns A new BlockStorage instance with discriminator key
+ */
+export function createBlockStorage<TState = unknown>(
+  initialData: TState = {} as TState,
+  version: number = 1,
+): BlockStorage<TState> {
+  return {
+    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+    __dataVersion: version,
+    __data: initialData,
+  };
+}
+
+/**
+ * Normalizes raw storage data to BlockStorage format.
+ * If the input is already a BlockStorage, returns it as-is.
+ * If the input is legacy format (raw state), wraps it in BlockStorage structure.
+ *
+ * @param raw - Raw storage data (may be legacy format or BlockStorage)
+ * @returns Normalized BlockStorage
+ */
+export function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {
+  if (isBlockStorage(raw)) {
+    return raw as BlockStorage<TState>;
+  }
+  // Legacy format: raw is the state directly
+  return createBlockStorage(raw as TState, 1);
+}
+
+// =============================================================================
+// Data Access & Update Functions
+// =============================================================================
+
+/**
+ * Gets the data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data value
+ */
+export function getStorageData<TState>(storage: BlockStorage<TState>): TState {
+  return storage.__data;
+}
+
+/**
+ * Derives data from raw block storage.
+ * This function is meant to be called from sdk/ui-vue to extract
+ * user-facing data from the raw storage returned by the middle layer.
+ *
+ * The middle layer returns raw storage (opaque to it), and the UI
+ * uses this function to derive the actual data value.
+ *
+ * @param rawStorage - Raw storage data from middle layer (may be any format)
+ * @returns The extracted data value, or undefined if storage is undefined/null
+ */
+export function deriveDataFromStorage<TData = unknown>(
+  rawStorage: unknown,
+): TData {
+  // Normalize to BlockStorage format (handles legacy formats too)
+  const storage = normalizeBlockStorage<TData>(rawStorage);
+  return getStorageData(storage);
+}
+
+/** Payload for storage mutation operations. SDK defines specific operations. */
+export type MutateStoragePayload<T = unknown> = { operation: 'update-data'; value: T };
+
+/**
+ * Updates the data in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param payload - The update payload with operation and value
+ * @returns A new BlockStorage with updated data
+ */
+export function updateStorageData<TValue = unknown>(
+  storage: BlockStorage<TValue>,
+  payload: MutateStoragePayload<TValue>,
+): BlockStorage<TValue> {
+  switch (payload.operation) {
+    case 'update-data':
+      return { ...storage, __data: payload.value };
+    default:
+      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);
+  }
+}
+
+/**
+ * Gets the data version from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data version number
+ */
+export function getStorageDataVersion(storage: BlockStorage): number {
+  return storage.__dataVersion;
+}
+
+/**
+ * Updates the data version in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param version - The new version number
+ * @returns A new BlockStorage with updated version
+ */
+export function updateStorageDataVersion<TState>(
+  storage: BlockStorage<TState>,
+  version: number,
+): BlockStorage<TState> {
+  return { ...storage, __dataVersion: version };
+}
+
+// =============================================================================
+// Plugin Data Functions
+// =============================================================================
+
+/**
+ * Gets plugin-specific data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns The plugin data or undefined if not set
+ */
+export function getPluginData<TData = unknown>(
+  storage: BlockStorage,
+  pluginName: string,
+): TData | undefined {
+  const key: PluginKey = `@plugin/${pluginName}`;
+  return storage[key] as TData | undefined;
+}
+
+/**
+ * Sets plugin-specific data in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @param data - The plugin data to store
+ * @returns A new BlockStorage with updated plugin data
+ */
+export function setPluginData<TState>(
+  storage: BlockStorage<TState>,
+  pluginName: string,
+  data: unknown,
+): BlockStorage<TState> {
+  const key: PluginKey = `@plugin/${pluginName}`;
+  return { ...storage, [key]: data };
+}
+
+/**
+ * Removes plugin-specific data from BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns A new BlockStorage with the plugin data removed
+ */
+export function removePluginData<TState>(
+  storage: BlockStorage<TState>,
+  pluginName: string,
+): BlockStorage<TState> {
+  const key: PluginKey = `@plugin/${pluginName}`;
+  const { [key]: _, ...rest } = storage;
+  return rest as BlockStorage<TState>;
+}
+
+/**
+ * Gets all plugin names that have data stored
+ *
+ * @param storage - The BlockStorage instance
+ * @returns Array of plugin names (without `@plugin/` prefix)
+ */
+export function getPluginNames(storage: BlockStorage): string[] {
+  return Object.keys(storage)
+    .filter((key): key is PluginKey => key.startsWith('@plugin/'))
+    .map((key) => key.slice('@plugin/'.length));
+}
+
+// =============================================================================
+// Generic Storage Access
+// =============================================================================
+
+/**
+ * Gets a value from BlockStorage by key
+ *
+ * @param storage - The BlockStorage instance
+ * @param key - The key to retrieve
+ * @returns The value at the given key
+ */
+export function getFromStorage<
+  TState,
+  K extends keyof BlockStorage<TState>,
+>(storage: BlockStorage<TState>, key: K): BlockStorage<TState>[K] {
+  return storage[key];
+}
+
+/**
+ * Updates a value in BlockStorage by key (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param key - The key to update
+ * @param value - The new value
+ * @returns A new BlockStorage with the updated value
+ */
+export function updateStorage<
+  TState,
+  K extends keyof BlockStorage<TState>,
+>(
+  storage: BlockStorage<TState>,
+  key: K,
+  value: BlockStorage<TState>[K],
+): BlockStorage<TState> {
+  return { ...storage, [key]: value };
+}
+
+// =============================================================================
+// Storage Handlers (for Phase 2 - Model-Level Customization)
+// =============================================================================
+
+/**
+ * Interface for model-configurable storage operations.
+ * These handlers allow block models to customize how storage is managed.
+ */
+export interface BlockStorageHandlers<TState = unknown> {
+  /**
+   * Called when setState is invoked - transforms the new state before storing.
+   * Default behavior: replaces the state directly.
+   *
+   * @param currentStorage - The current BlockStorage
+   * @param newState - The new state being set
+   * @returns The updated BlockStorage
+   */
+  transformStateForStorage?: (
+    currentStorage: BlockStorage<TState>,
+    newState: TState,
+  ) => BlockStorage<TState>;
+
+  /**
+   * Called when reading state for args derivation.
+   * Default behavior: returns the state directly.
+   *
+   * @param storage - The current BlockStorage
+   * @returns The state to use for args derivation
+   */
+  deriveStateForArgs?: (storage: BlockStorage<TState>) => TState;
+
+  /**
+   * Called during storage schema migration.
+   * Default behavior: updates stateVersion only.
+   *
+   * @param oldStorage - The storage before migration
+   * @param fromVersion - The version migrating from
+   * @param toVersion - The version migrating to
+   * @returns The migrated BlockStorage
+   */
+  migrateStorage?: (
+    oldStorage: BlockStorage<TState>,
+    fromVersion: number,
+    toVersion: number,
+  ) => BlockStorage<TState>;
+}
+
+/**
+ * Default implementations of storage handlers
+ */
+export const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>> = {
+  transformStateForStorage: <TState>(
+    storage: BlockStorage<TState>,
+    newState: TState,
+  ): BlockStorage<TState> => updateStorageData(storage, { operation: 'update-data', value: newState }),
+
+  deriveStateForArgs: <TState>(storage: BlockStorage<TState>): TState => getStorageData(storage),
+
+  migrateStorage: <TState>(
+    storage: BlockStorage<TState>,
+    _fromVersion: number,
+    toVersion: number,
+  ): BlockStorage<TState> => updateStorageDataVersion(storage, toVersion),
+};
+
+/**
+ * Merges custom handlers with defaults
+ *
+ * @param customHandlers - Custom handlers to merge
+ * @returns Complete handlers with defaults for missing functions
+ */
+export function mergeBlockStorageHandlers<TState>(
+  customHandlers?: BlockStorageHandlers<TState>,
+): Required<BlockStorageHandlers<TState>> {
+  return {
+    ...defaultBlockStorageHandlers,
+    ...customHandlers,
+  } as Required<BlockStorageHandlers<TState>>;
+}

package/src/block_storage_vm.ts

@@ -0,0 +1,349 @@
+/**
+ * BlockStorage VM Integration - Internal module for VM-based storage operations.
+ *
+ * This module auto-registers internal callbacks that the middle layer can invoke
+ * to perform storage transformations. Block developers never interact with these
+ * directly - they only see `state`.
+ *
+ * Registered callbacks (all prefixed with `__pl_` for internal SDK use):
+ * - `__pl_storage_normalize`: (rawStorage) => { storage, data }
+ * - `__pl_storage_applyUpdate`: (currentStorageJson, payload) => updatedStorageJson
+ * - `__pl_storage_getInfo`: (rawStorage) => JSON string with storage info
+ * - `__pl_storage_migrate`: (currentStorageJson) => MigrationResult
+ * - `__pl_args_derive`: (storageJson) => ArgsDeriveResult
+ * - `__pl_prerunArgs_derive`: (storageJson) => ArgsDeriveResult
+ *
+ * Callbacks registered by DataModel.registerCallbacks():
+ * - `__pl_data_initial`: () => initial data
+ * - `__pl_data_upgrade`: (versioned) => UpgradeResult
+ * - `__pl_storage_initial`: () => initial BlockStorage as JSON string
+ *
+ * @module block_storage_vm
+ * @internal
+ */
+
+import {
+  BLOCK_STORAGE_KEY,
+  BLOCK_STORAGE_SCHEMA_VERSION,
+  type BlockStorage,
+  type MutateStoragePayload,
+  createBlockStorage,
+  getStorageData,
+  isBlockStorage,
+  updateStorageData,
+} from './block_storage';
+import { tryGetCfgRenderCtx, tryRegisterCallback } from './internal';
+
+/**
+ * Result of storage normalization
+ */
+export interface NormalizeStorageResult {
+  /** The normalized BlockStorage object */
+  storage: BlockStorage;
+  /** The extracted data (what developers see) */
+  data: unknown;
+}
+
+/**
+ * Normalizes raw storage data and extracts state.
+ * Handles all formats:
+ * - New BlockStorage format (has discriminator)
+ * - Legacy V1/V2 format ({ args, uiState })
+ * - Raw V3 state (any other format)
+ *
+ * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+ * @returns Object with normalized storage and extracted state
+ */
+function normalizeStorage(rawStorage: unknown): NormalizeStorageResult {
+  // Handle undefined/null
+  if (rawStorage === undefined || rawStorage === null) {
+    const storage = createBlockStorage({});
+    return { storage, data: {} };
+  }
+
+  // Parse JSON string if needed
+  let parsed = rawStorage;
+  if (typeof rawStorage === 'string') {
+    try {
+      parsed = JSON.parse(rawStorage);
+    } catch {
+      // If parsing fails, treat string as the data
+      const storage = createBlockStorage(rawStorage);
+      return { storage, data: rawStorage };
+    }
+  }
+
+  // Check for BlockStorage format (has discriminator)
+  if (isBlockStorage(parsed)) {
+    return { storage: parsed, data: getStorageData(parsed) };
+  }
+
+  // Check for legacy V1/V2 format: { args, uiState }
+  if (isLegacyModelV1ApiFormat(parsed)) {
+    // For legacy format, the whole object IS the data
+    const storage = createBlockStorage(parsed);
+    return { storage, data: parsed };
+  }
+
+  // Raw V3 data - wrap it
+  const storage = createBlockStorage(parsed);
+  return { storage, data: parsed };
+}
+
+/**
+ * Applies a state update to existing storage.
+ * Used when setData is called from the frontend.
+ *
+ * @param currentStorageJson - Current storage as JSON string (must be defined)
+ * @param newData - New data from application
+ * @returns Updated storage as JSON string
+ */
+function applyStorageUpdate(currentStorageJson: string, payload: MutateStoragePayload): string {
+  const { storage: currentStorage } = normalizeStorage(currentStorageJson);
+
+  // Update data while preserving other storage fields (version, plugins)
+  const updatedStorage = updateStorageData(currentStorage, payload);
+
+  return JSON.stringify(updatedStorage);
+}
+
+/**
+ * Checks if data is in legacy Model API v1 format.
+ * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.
+ */
+function isLegacyModelV1ApiFormat(data: unknown): data is { args?: unknown } {
+  if (data === null || typeof data !== 'object') return false;
+  if (isBlockStorage(data)) return false;
+
+  const obj = data as Record<string, unknown>;
+  return 'args' in obj;
+}
+
+// =============================================================================
+// Auto-register internal callbacks when module is loaded in VM
+// =============================================================================
+
+// Register normalize callback
+tryRegisterCallback('__pl_storage_normalize', (rawStorage: unknown) => {
+  return normalizeStorage(rawStorage);
+});
+
+// Register apply update callback (requires existing storage)
+tryRegisterCallback('__pl_storage_applyUpdate', (currentStorageJson: string, payload: MutateStoragePayload) => {
+  return applyStorageUpdate(currentStorageJson, payload);
+});
+
+/**
+ * Storage info result returned by __pl_storage_getInfo callback.
+ */
+export interface StorageInfo {
+  /** Current data version (1-based, starts at 1) */
+  dataVersion: number;
+}
+
+/**
+ * Gets storage info from raw storage data.
+ * Returns structured info about the storage state.
+ *
+ * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+ * @returns JSON string with storage info
+ */
+function getStorageInfo(rawStorage: unknown): string {
+  const { storage } = normalizeStorage(rawStorage);
+  const info: StorageInfo = {
+    dataVersion: storage.__dataVersion,
+  };
+  return JSON.stringify(info);
+}
+
+// Register get info callback
+tryRegisterCallback('__pl_storage_getInfo', (rawStorage: unknown) => {
+  return getStorageInfo(rawStorage);
+});
+
+// =============================================================================
+// Migration Support
+// =============================================================================
+
+/**
+ * Result of storage migration.
+ * Returned by __pl_storage_migrate callback.
+ *
+ * - Error result: { error: string } - serious failure (no context, etc.)
+ * - Success result: { newStorageJson: string, info: string, warn?: string } - migration succeeded or reset to initial
+ */
+export type MigrationResult =
+  | { error: string }
+  | { error?: undefined; newStorageJson: string; info: string; warn?: string };
+
+/** Result from Migrator.upgrade() */
+interface UpgradeResult {
+  version: number;
+  data: unknown;
+  warning?: string;
+}
+
+/**
+ * Runs storage migration using the DataModel's upgrade callback.
+ * This is the main entry point for the middle layer to trigger migrations.
+ *
+ * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:
+ * - Handles all migration logic internally
+ * - Returns { version, data, warning? } - warning present if reset to initial data
+ *
+ * @param currentStorageJson - Current storage as JSON string (or undefined)
+ * @returns MigrationResult
+ */
+function migrateStorage(currentStorageJson: string | undefined): MigrationResult {
+  // Get the callback registry context
+  const ctx = tryGetCfgRenderCtx();
+  if (ctx === undefined) {
+    return { error: 'Not in config rendering context' };
+  }
+
+  // Normalize storage to get current data and version
+  const { storage: currentStorage, data: currentData } = normalizeStorage(currentStorageJson);
+  const currentVersion = currentStorage.__dataVersion;
+
+  // Helper to create storage with given data and version
+  const createStorageJson = (data: unknown, version: number): string => {
+    return JSON.stringify({
+      ...currentStorage,
+      __dataVersion: version,
+      __data: data,
+    });
+  };
+
+  // Get the upgrade callback (registered by DataModel.registerCallbacks())
+  const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'] as ((v: { version: number; data: unknown }) => UpgradeResult) | undefined;
+  if (typeof upgradeCallback !== 'function') {
+    return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };
+  }
+
+  // Call the migrator's upgrade function
+  let result: UpgradeResult;
+  try {
+    result = upgradeCallback({ version: currentVersion, data: currentData });
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    return { error: `upgrade() threw: ${errorMsg}` };
+  }
+
+  // Build info message
+  const info = result.version === currentVersion
+    ? `No migration needed (v${currentVersion})`
+    : result.warning
+      ? `Reset to initial data (v${result.version})`
+      : `Migrated v${currentVersion}→v${result.version}`;
+
+  return {
+    newStorageJson: createStorageJson(result.data, result.version),
+    info,
+    warn: result.warning,
+  };
+}
+
+// Register migrate callback
+tryRegisterCallback('__pl_storage_migrate', (currentStorageJson: string | undefined) => {
+  return migrateStorage(currentStorageJson);
+});
+
+// =============================================================================
+// Args Derivation from Storage
+// =============================================================================
+
+/**
+ * Result of args derivation from storage.
+ * Returned by __pl_args_derive and __pl_prerunArgs_derive callbacks.
+ */
+export type ArgsDeriveResult =
+  | { error: string }
+  | { error?: undefined; value: unknown };
+
+/**
+ * Derives args from storage using the registered 'args' callback.
+ * This extracts data from storage and passes it to the block's args() function.
+ *
+ * @param storageJson - Storage as JSON string
+ * @returns ArgsDeriveResult with derived args or error
+ */
+function deriveArgsFromStorage(storageJson: string): ArgsDeriveResult {
+  const ctx = tryGetCfgRenderCtx();
+  if (ctx === undefined) {
+    return { error: 'Not in config rendering context' };
+  }
+
+  // Extract data from storage
+  const { data } = normalizeStorage(storageJson);
+
+  // Get the args callback (registered by BlockModelV3.args())
+  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;
+  if (typeof argsCallback !== 'function') {
+    return { error: 'args callback not found' };
+  }
+
+  // Call the args callback with extracted data
+  try {
+    const result = argsCallback(data);
+    return { value: result };
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    return { error: `args() threw: ${errorMsg}` };
+  }
+}
+
+// Register args derivation callback
+tryRegisterCallback('__pl_args_derive', (storageJson: string) => {
+  return deriveArgsFromStorage(storageJson);
+});
+
+/**
+ * Derives prerunArgs from storage using the registered 'prerunArgs' callback.
+ * Falls back to 'args' callback if 'prerunArgs' is not defined.
+ *
+ * @param storageJson - Storage as JSON string
+ * @returns ArgsDeriveResult with derived prerunArgs or error
+ */
+function derivePrerunArgsFromStorage(storageJson: string): ArgsDeriveResult {
+  const ctx = tryGetCfgRenderCtx();
+  if (ctx === undefined) {
+    return { error: 'Not in config rendering context' };
+  }
+
+  // Extract data from storage
+  const { data } = normalizeStorage(storageJson);
+
+  // Try prerunArgs callback first
+  const prerunArgsCallback = ctx.callbackRegistry['prerunArgs'] as ((data: unknown) => unknown) | undefined;
+  if (typeof prerunArgsCallback === 'function') {
+    try {
+      const result = prerunArgsCallback(data);
+      return { value: result };
+    } catch (e) {
+      const errorMsg = e instanceof Error ? e.message : String(e);
+      return { error: `prerunArgs() threw: ${errorMsg}` };
+    }
+  }
+
+  // Fall back to args callback
+  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;
+  if (typeof argsCallback !== 'function') {
+    return { error: 'args callback not found (fallback from missing prerunArgs)' };
+  }
+
+  try {
+    const result = argsCallback(data);
+    return { value: result };
+  } catch (e) {
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    return { error: `args() threw (fallback): ${errorMsg}` };
+  }
+}
+
+// Register prerunArgs derivation callback
+tryRegisterCallback('__pl_prerunArgs_derive', (storageJson: string) => {
+  return derivePrerunArgsFromStorage(storageJson);
+});
+
+// Export discriminator key and schema version for external checks
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };