@platforma-sdk/model 1.51.9 → 1.52.3

package/src/block_storage.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it } from 'vitest';
+import {
+  BLOCK_STORAGE_KEY,
+  BLOCK_STORAGE_SCHEMA_VERSION,
+  createBlockStorage,
+  defaultBlockStorageHandlers,
+  getFromStorage,
+  getPluginData,
+  getPluginNames,
+  getStorageData,
+  getStorageDataVersion,
+  isBlockStorage,
+  mergeBlockStorageHandlers,
+  normalizeBlockStorage,
+  removePluginData,
+  setPluginData,
+  updateStorageData,
+  updateStorageDataVersion,
+  updateStorage,
+} from './block_storage';
+
+describe('BlockStorage', () => {
+  describe('BLOCK_STORAGE_KEY and BLOCK_STORAGE_SCHEMA_VERSION', () => {
+    it('should have correct key constant', () => {
+      expect(typeof BLOCK_STORAGE_KEY).toBe('string');
+      expect(BLOCK_STORAGE_KEY).toBe('__pl_a7f3e2b9__');
+    });
+
+    it('should have correct schema version', () => {
+      expect(BLOCK_STORAGE_SCHEMA_VERSION).toBe('v1');
+    });
+  });
+
+  describe('isBlockStorage', () => {
+    it('should return true for valid BlockStorage with discriminator', () => {
+      const storage = createBlockStorage({});
+      expect(isBlockStorage(storage)).toBe(true);
+    });
+
+    it('should return true for BlockStorage with plugin data', () => {
+      const storage = setPluginData(createBlockStorage({ foo: 'bar' }), 'test', { data: 123 });
+      expect(isBlockStorage(storage)).toBe(true);
+    });
+
+    it('should return false for null', () => {
+      expect(isBlockStorage(null)).toBe(false);
+    });
+
+    it('should return false for undefined', () => {
+      expect(isBlockStorage(undefined)).toBe(false);
+    });
+
+    it('should return false for primitive values', () => {
+      expect(isBlockStorage(42)).toBe(false);
+      expect(isBlockStorage('string')).toBe(false);
+      expect(isBlockStorage(true)).toBe(false);
+    });
+
+    it('should return false for objects without discriminator', () => {
+      expect(isBlockStorage({ __dataVersion: 1, __data: {} })).toBe(false);
+    });
+
+    it('should return false for objects with wrong discriminator value', () => {
+      expect(isBlockStorage({ [BLOCK_STORAGE_KEY]: 'wrong', __dataVersion: 1, __data: {} })).toBe(false);
+    });
+  });
+
+  describe('createBlockStorage', () => {
+    it('should create storage with discriminator key and default values', () => {
+      const storage = createBlockStorage();
+      expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      expect(storage.__dataVersion).toBe(1);
+      expect(storage.__data).toEqual({});
+    });
+
+    it('should create storage with custom initial data', () => {
+      const data = { numbers: [1, 2, 3] };
+      const storage = createBlockStorage(data);
+      expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      expect(storage.__dataVersion).toBe(1);
+      expect(storage.__data).toEqual(data);
+    });
+
+    it('should create storage with custom version', () => {
+      const storage = createBlockStorage({ foo: 'bar' }, 5);
+      expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      expect(storage.__dataVersion).toBe(5);
+      expect(storage.__data).toEqual({ foo: 'bar' });
+    });
+  });
+
+  describe('normalizeBlockStorage', () => {
+    it('should return BlockStorage as-is', () => {
+      const storage = createBlockStorage({ data: 'test' }, 2);
+      const normalized = normalizeBlockStorage(storage);
+      expect(normalized).toEqual(storage);
+    });
+
+    it('should wrap legacy data in BlockStorage structure', () => {
+      const legacyData = { numbers: [1, 2, 3], name: 'test' };
+      const normalized = normalizeBlockStorage(legacyData);
+      expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      expect(normalized.__dataVersion).toBe(1);
+      expect(normalized.__data).toEqual(legacyData);
+    });
+
+    it('should wrap primitive legacy data', () => {
+      const normalized = normalizeBlockStorage('simple string');
+      expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      expect(normalized.__dataVersion).toBe(1);
+      expect(normalized.__data).toBe('simple string');
+    });
+
+    it('should wrap null legacy data', () => {
+      const normalized = normalizeBlockStorage(null);
+      expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      expect(normalized.__dataVersion).toBe(1);
+      expect(normalized.__data).toBeNull();
+    });
+  });
+
+  describe('Data access functions', () => {
+    const storage = createBlockStorage({ count: 42 }, 3);
+
+    it('getStorageData should return the data', () => {
+      expect(getStorageData(storage)).toEqual({ count: 42 });
+    });
+
+    it('getStorageDataVersion should return the version', () => {
+      expect(getStorageDataVersion(storage)).toBe(3);
+    });
+
+    it('updateStorageData should return new storage with updated data', () => {
+      const newStorage = updateStorageData(storage, { operation: 'update-data', value: { count: 100 } });
+      expect(newStorage.__data).toEqual({ count: 100 });
+      expect(newStorage.__dataVersion).toBe(3);
+      expect(newStorage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      // Original should be unchanged
+      expect(storage.__data).toEqual({ count: 42 });
+    });
+
+    it('updateStorageDataVersion should return new storage with updated version', () => {
+      const newStorage = updateStorageDataVersion(storage, 5);
+      expect(newStorage.__dataVersion).toBe(5);
+      expect(newStorage.__data).toEqual({ count: 42 });
+      expect(newStorage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
+      // Original should be unchanged
+      expect(storage.__dataVersion).toBe(3);
+    });
+  });
+
+  describe('Plugin data functions', () => {
+    const baseStorage = createBlockStorage({});
+
+    it('setPluginData should add plugin data', () => {
+      const storage = setPluginData(baseStorage, 'table', { columns: ['a', 'b'] });
+      expect(storage['@plugin/table']).toEqual({ columns: ['a', 'b'] });
+    });
+
+    it('getPluginData should retrieve plugin data', () => {
+      const storage = setPluginData(baseStorage, 'chart', { type: 'bar' });
+      expect(getPluginData(storage, 'chart')).toEqual({ type: 'bar' });
+    });
+
+    it('getPluginData should return undefined for missing plugin', () => {
+      expect(getPluginData(baseStorage, 'nonexistent')).toBeUndefined();
+    });
+
+    it('removePluginData should remove plugin data', () => {
+      let storage = setPluginData(baseStorage, 'toRemove', { data: 'test' });
+      storage = setPluginData(storage, 'toKeep', { other: 'data' });
+      const result = removePluginData(storage, 'toRemove');
+      expect(result['@plugin/toRemove']).toBeUndefined();
+      expect(result['@plugin/toKeep']).toEqual({ other: 'data' });
+    });
+
+    it('getPluginNames should return all plugin names', () => {
+      let storage = createBlockStorage({});
+      storage = setPluginData(storage, 'alpha', {});
+      storage = setPluginData(storage, 'beta', {});
+      storage = setPluginData(storage, 'gamma', {});
+      const names = getPluginNames(storage);
+      expect(names.sort()).toEqual(['alpha', 'beta', 'gamma']);
+    });
+
+    it('getPluginNames should return empty array when no plugins', () => {
+      expect(getPluginNames(baseStorage)).toEqual([]);
+    });
+  });
+
+  describe('Generic storage access', () => {
+    const storage = createBlockStorage('hello', 2);
+
+    it('getFromStorage should get __data', () => {
+      expect(getFromStorage(storage, '__data')).toBe('hello');
+    });
+
+    it('getFromStorage should get __dataVersion', () => {
+      expect(getFromStorage(storage, '__dataVersion')).toBe(2);
+    });
+
+    it('updateStorage should update any key', () => {
+      const updated = updateStorage(storage, '__data', 'world');
+      expect(updated.__data).toBe('world');
+      expect(storage.__data).toBe('hello'); // immutable
+    });
+  });
+
+  describe('BlockStorageHandlers', () => {
+    describe('defaultBlockStorageHandlers', () => {
+      it('transformStateForStorage should replace data', () => {
+        const storage = createBlockStorage('old');
+        const result = defaultBlockStorageHandlers.transformStateForStorage(storage, 'new');
+        expect(result.__data).toBe('new');
+        expect(result.__dataVersion).toBe(1);
+      });
+
+      it('deriveStateForArgs should return data directly', () => {
+        const storage = createBlockStorage({ data: 'test' });
+        expect(defaultBlockStorageHandlers.deriveStateForArgs(storage)).toEqual({ data: 'test' });
+      });
+
+      it('migrateStorage should update version only', () => {
+        const storage = createBlockStorage({ data: 'test' });
+        const result = defaultBlockStorageHandlers.migrateStorage(storage, 1, 3);
+        expect(result.__dataVersion).toBe(3);
+        expect(result.__data).toEqual({ data: 'test' });
+      });
+    });
+
+    describe('mergeBlockStorageHandlers', () => {
+      it('should return defaults when no custom handlers provided', () => {
+        const handlers = mergeBlockStorageHandlers();
+        expect(handlers.transformStateForStorage).toBe(
+          defaultBlockStorageHandlers.transformStateForStorage,
+        );
+        expect(handlers.deriveStateForArgs).toBe(defaultBlockStorageHandlers.deriveStateForArgs);
+        expect(handlers.migrateStorage).toBe(defaultBlockStorageHandlers.migrateStorage);
+      });
+
+      it('should override with custom handlers', () => {
+        const customTransform = <T>(storage: ReturnType<typeof createBlockStorage<T>>, data: T) => ({
+          ...storage,
+          __data: data,
+          __dataVersion: storage.__dataVersion + 1,
+        });
+
+        const handlers = mergeBlockStorageHandlers({
+          transformStateForStorage: customTransform,
+        });
+
+        expect(handlers.transformStateForStorage).toBe(customTransform);
+        expect(handlers.deriveStateForArgs).toBe(defaultBlockStorageHandlers.deriveStateForArgs);
+      });
+    });
+  });
+});
+

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>>;
+}