@platforma-sdk/model 1.53.11 → 1.53.13

package/src/block_storage.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it } from "vitest";
 import {
   BLOCK_STORAGE_KEY,
   BLOCK_STORAGE_SCHEMA_VERSION,
@@ -18,63 +18,65 @@ import {
   updateStorageData,
   updateStorageDataVersion,
   updateStorage,
-} from './block_storage';
+} 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__');
+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');
+    it("should have correct schema version", () => {
+      expect(BLOCK_STORAGE_SCHEMA_VERSION).toBe("v1");
     });
   });
 
-  describe('isBlockStorage', () => {
-    it('should return true for valid BlockStorage with discriminator', () => {
+  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 });
+    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', () => {
+    it("should return false for null", () => {
       expect(isBlockStorage(null)).toBe(false);
     });
 
-    it('should return false for undefined', () => {
+    it("should return false for undefined", () => {
       expect(isBlockStorage(undefined)).toBe(false);
     });
 
-    it('should return false for primitive values', () => {
+    it("should return false for primitive values", () => {
       expect(isBlockStorage(42)).toBe(false);
-      expect(isBlockStorage('string')).toBe(false);
+      expect(isBlockStorage("string")).toBe(false);
       expect(isBlockStorage(true)).toBe(false);
     });
 
-    it('should return false for objects without discriminator', () => {
-      expect(isBlockStorage({ __dataVersion: 'v1', __data: {} })).toBe(false);
+    it("should return false for objects without discriminator", () => {
+      expect(isBlockStorage({ __dataVersion: "v1", __data: {} })).toBe(false);
     });
 
-    it('should return false for objects with wrong discriminator value', () => {
-      expect(isBlockStorage({ [BLOCK_STORAGE_KEY]: 'wrong', __dataVersion: 'v1', __data: {} })).toBe(false);
+    it("should return false for objects with wrong discriminator value", () => {
+      expect(
+        isBlockStorage({ [BLOCK_STORAGE_KEY]: "wrong", __dataVersion: "v1", __data: {} }),
+      ).toBe(false);
     });
   });
 
-  describe('createBlockStorage', () => {
-    it('should create storage with discriminator key and default values', () => {
+  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(DATA_MODEL_DEFAULT_VERSION);
       expect(storage.__data).toEqual({});
     });
 
-    it('should create storage with custom initial data', () => {
+    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);
@@ -82,37 +84,37 @@ describe('BlockStorage', () => {
       expect(storage.__data).toEqual(data);
     });
 
-    it('should create storage with custom version', () => {
-      const storage = createBlockStorage({ foo: 'bar' }, 'v5');
+    it("should create storage with custom version", () => {
+      const storage = createBlockStorage({ foo: "bar" }, "v5");
       expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(storage.__dataVersion).toBe('v5');
-      expect(storage.__data).toEqual({ foo: 'bar' });
+      expect(storage.__dataVersion).toBe("v5");
+      expect(storage.__data).toEqual({ foo: "bar" });
     });
   });
 
-  describe('normalizeBlockStorage', () => {
-    it('should return BlockStorage as-is', () => {
-      const storage = createBlockStorage({ data: 'test' }, 'v2');
+  describe("normalizeBlockStorage", () => {
+    it("should return BlockStorage as-is", () => {
+      const storage = createBlockStorage({ data: "test" }, "v2");
       const normalized = normalizeBlockStorage(storage);
       expect(normalized).toEqual(storage);
     });
 
-    it('should wrap legacy data in BlockStorage structure', () => {
-      const legacyData = { numbers: [1, 2, 3], name: 'test' };
+    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(DATA_MODEL_DEFAULT_VERSION);
       expect(normalized.__data).toEqual(legacyData);
     });
 
-    it('should wrap primitive legacy data', () => {
-      const normalized = normalizeBlockStorage('simple string');
+    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(DATA_MODEL_DEFAULT_VERSION);
-      expect(normalized.__data).toBe('simple string');
+      expect(normalized.__data).toBe("simple string");
     });
 
-    it('should wrap null legacy data', () => {
+    it("should wrap null legacy data", () => {
       const normalized = normalizeBlockStorage(null);
       expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
       expect(normalized.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
@@ -120,117 +122,120 @@ describe('BlockStorage', () => {
     });
   });
 
-  describe('Data access functions', () => {
-    const storage = createBlockStorage({ count: 42 }, 'v3');
+  describe("Data access functions", () => {
+    const storage = createBlockStorage({ count: 42 }, "v3");
 
-    it('getStorageData should return the data', () => {
+    it("getStorageData should return the data", () => {
       expect(getStorageData(storage)).toEqual({ count: 42 });
     });
 
-    it('getStorageDataVersion should return the version', () => {
-      expect(getStorageDataVersion(storage)).toBe('v3');
+    it("getStorageDataVersion should return the version", () => {
+      expect(getStorageDataVersion(storage)).toBe("v3");
     });
 
-    it('updateStorageData should return new storage with updated data', () => {
-      const newStorage = updateStorageData(storage, { operation: 'update-data', value: { count: 100 } });
+    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('v3');
+      expect(newStorage.__dataVersion).toBe("v3");
       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, 'v5');
-      expect(newStorage.__dataVersion).toBe('v5');
+    it("updateStorageDataVersion should return new storage with updated version", () => {
+      const newStorage = updateStorageDataVersion(storage, "v5");
+      expect(newStorage.__dataVersion).toBe("v5");
       expect(newStorage.__data).toEqual({ count: 42 });
       expect(newStorage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
       // Original should be unchanged
-      expect(storage.__dataVersion).toBe('v3');
+      expect(storage.__dataVersion).toBe("v3");
     });
   });
 
-  describe('Plugin data functions', () => {
+  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("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 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("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("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', () => {
+    it("getPluginNames should return all plugin names", () => {
       let storage = createBlockStorage({});
-      storage = setPluginData(storage, 'alpha', {});
-      storage = setPluginData(storage, 'beta', {});
-      storage = setPluginData(storage, 'gamma', {});
+      storage = setPluginData(storage, "alpha", {});
+      storage = setPluginData(storage, "beta", {});
+      storage = setPluginData(storage, "gamma", {});
       const names = getPluginNames(storage);
-      expect(names.sort()).toEqual(['alpha', 'beta', 'gamma']);
+      expect(names.sort()).toEqual(["alpha", "beta", "gamma"]);
     });
 
-    it('getPluginNames should return empty array when no plugins', () => {
+    it("getPluginNames should return empty array when no plugins", () => {
       expect(getPluginNames(baseStorage)).toEqual([]);
     });
   });
 
-  describe('Generic storage access', () => {
-    const storage = createBlockStorage('hello', 'v2');
+  describe("Generic storage access", () => {
+    const storage = createBlockStorage("hello", "v2");
 
-    it('getFromStorage should get __data', () => {
-      expect(getFromStorage(storage, '__data')).toBe('hello');
+    it("getFromStorage should get __data", () => {
+      expect(getFromStorage(storage, "__data")).toBe("hello");
     });
 
-    it('getFromStorage should get __dataVersion', () => {
-      expect(getFromStorage(storage, '__dataVersion')).toBe('v2');
+    it("getFromStorage should get __dataVersion", () => {
+      expect(getFromStorage(storage, "__dataVersion")).toBe("v2");
     });
 
-    it('updateStorage should update any key', () => {
-      const updated = updateStorage(storage, '__data', 'world');
-      expect(updated.__data).toBe('world');
-      expect(storage.__data).toBe('hello'); // immutable
+    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');
+  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(DATA_MODEL_DEFAULT_VERSION);
       });
 
-      it('deriveStateForArgs should return data directly', () => {
-        const storage = createBlockStorage({ data: 'test' });
-        expect(defaultBlockStorageHandlers.deriveStateForArgs(storage)).toEqual({ data: 'test' });
+      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, 'v1', 'v3');
-        expect(result.__dataVersion).toBe('v3');
-        expect(result.__data).toEqual({ data: 'test' });
+      it("migrateStorage should update version only", () => {
+        const storage = createBlockStorage({ data: "test" });
+        const result = defaultBlockStorageHandlers.migrateStorage(storage, "v1", "v3");
+        expect(result.__dataVersion).toBe("v3");
+        expect(result.__data).toEqual({ data: "test" });
       });
     });
 
-    describe('mergeBlockStorageHandlers', () => {
-      it('should return defaults when no custom handlers provided', () => {
+    describe("mergeBlockStorageHandlers", () => {
+      it("should return defaults when no custom handlers provided", () => {
         const handlers = mergeBlockStorageHandlers();
         expect(handlers.transformStateForStorage).toBe(
           defaultBlockStorageHandlers.transformStateForStorage,
@@ -239,8 +244,11 @@ describe('BlockStorage', () => {
         expect(handlers.migrateStorage).toBe(defaultBlockStorageHandlers.migrateStorage);
       });
 
-      it('should override with custom handlers', () => {
-        const customTransform = <T>(storage: ReturnType<typeof createBlockStorage<T>>, data: T) => ({
+      it("should override with custom handlers", () => {
+        const customTransform = <T>(
+          storage: ReturnType<typeof createBlockStorage<T>>,
+          data: T,
+        ) => ({
           ...storage,
           __data: data,
           __dataVersion: `${storage.__dataVersion}-next`,
@@ -256,4 +264,3 @@ describe('BlockStorage', () => {
     });
   });
 });
-

package/src/block_storage.ts

@@ -17,24 +17,24 @@
  * 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__';
+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';
+export const BLOCK_STORAGE_SCHEMA_VERSION = "v1";
 
 /**
  * Default data version for new blocks without migrations.
  * Unique identifier ensures blocks are created via DataModel API.
  */
-export const DATA_MODEL_DEFAULT_VERSION = '__pl_v1_d4e8f2a1__';
+export const DATA_MODEL_DEFAULT_VERSION = "__pl_v1_d4e8f2a1__";
 
 /**
  * Type for valid schema versions
  */
-export type BlockStorageSchemaVersion = 'v1'; // Add 'v2', 'v3', etc. as schema evolves
+export type BlockStorageSchemaVersion = "v1"; // Add 'v2', 'v3', etc. as schema evolves
 
 /**
  * Plugin key type - keys starting with `@plugin/` are reserved for plugin data
@@ -65,11 +65,11 @@ export type BlockStorage<TState = unknown> = {
  * 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;
+  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
+  return schemaVersion === "v1"; // Add more versions as schema evolves
 }
 
 // =============================================================================
@@ -108,9 +108,10 @@ export function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStor
     return {
       ...storage,
       // Fix for early released version where __dataVersion was a number
-      __dataVersion: typeof storage.__dataVersion === 'number'
-        ? DATA_MODEL_DEFAULT_VERSION
-        : storage.__dataVersion,
+      __dataVersion:
+        typeof storage.__dataVersion === "number"
+          ? DATA_MODEL_DEFAULT_VERSION
+          : storage.__dataVersion,
     };
   }
   // Legacy format: raw is the state directly
@@ -142,16 +143,14 @@ export function getStorageData<TState>(storage: BlockStorage<TState>): TState {
  * @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 {
+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 };
+export type MutateStoragePayload<T = unknown> = { operation: "update-data"; value: T };
 
 /**
  * Updates the data in BlockStorage (immutable)
@@ -165,7 +164,7 @@ export function updateStorageData<TValue = unknown>(
   payload: MutateStoragePayload<TValue>,
 ): BlockStorage<TValue> {
   switch (payload.operation) {
-    case 'update-data':
+    case "update-data":
       return { ...storage, __data: payload.value };
     default:
       throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);
@@ -267,8 +266,8 @@ export function removePluginData<TState>(
  */
 export function getPluginNames(storage: BlockStorage): string[] {
   return Object.keys(storage)
-    .filter((key): key is PluginKey => key.startsWith('@plugin/'))
-    .map((key) => key.slice('@plugin/'.length));
+    .filter((key): key is PluginKey => key.startsWith("@plugin/"))
+    .map((key) => key.slice("@plugin/".length));
 }
 
 // =============================================================================
@@ -282,10 +281,10 @@ export function getPluginNames(storage: BlockStorage): string[] {
  * @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] {
+export function getFromStorage<TState, K extends keyof BlockStorage<TState>>(
+  storage: BlockStorage<TState>,
+  key: K,
+): BlockStorage<TState>[K] {
   return storage[key];
 }
 
@@ -297,10 +296,7 @@ export function getFromStorage<
  * @param value - The new value
  * @returns A new BlockStorage with the updated value
  */
-export function updateStorage<
-  TState,
-  K extends keyof BlockStorage<TState>,
->(
+export function updateStorage<TState, K extends keyof BlockStorage<TState>>(
   storage: BlockStorage<TState>,
   key: K,
   value: BlockStorage<TState>[K],
@@ -362,7 +358,8 @@ export const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>
   transformStateForStorage: <TState>(
     storage: BlockStorage<TState>,
     newState: TState,
-  ): BlockStorage<TState> => updateStorageData(storage, { operation: 'update-data', value: newState }),
+  ): BlockStorage<TState> =>
+    updateStorageData(storage, { operation: "update-data", value: newState }),
 
   deriveStateForArgs: <TState>(storage: BlockStorage<TState>): TState => getStorageData(storage),