@platforma-sdk/model 1.54.10 → 1.55.0

package/dist/block_storage.d.ts

@@ -8,6 +8,8 @@
  *
  * @module block_storage
  */
+import type { Branded } from "@milaboratories/pl-model-common";
+import type { DataMigrationResult, DataVersioned } from "./block_migrations";
 /**
  * Discriminator key for BlockStorage format detection.
  * This unique hash-based key identifies data as BlockStorage vs legacy formats.
@@ -28,26 +30,41 @@ export declare const DATA_MODEL_DEFAULT_VERSION = "__pl_v1_d4e8f2a1__";
  */
 export type BlockStorageSchemaVersion = "v1";
 /**
- * Plugin key type - keys starting with `@plugin/` are reserved for plugin data
+ * Branded type for plugin names - globally unique plugin type identifiers.
+ * Using a branded type enforces explicit casting (`as PluginName`) which makes
+ * it easy to find all plugin name definitions in the codebase and verify uniqueness.
  */
-export type PluginKey = `@plugin/${string}`;
+export type PluginName = Branded<string, "PluginName">;
+/**
+ * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).
+ * Using a Record highlights that pluginIds must be unique within a block.
+ */
+export type PluginRegistry = Record<string, PluginName>;
+/**
+ * Versioned data - used for both block data and plugin data
+ */
+export interface VersionedData<TData = unknown> {
+    /** Version of the data, used for migrations */
+    __dataVersion: string;
+    /** The persistent data */
+    __data: TData;
+}
 /**
  * Core BlockStorage type that holds:
  * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)
  * - __dataVersion: Version key for block data migrations
  * - __data: The block's user-facing data (state)
- * - @plugin/*: Optional plugin-specific data
+ * - __pluginRegistry: Map from pluginId to pluginName (optional)
+ * - __plugins: Plugin-specific data keyed by pluginId (optional)
  */
 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: string;
-    /** The block's user-facing data (state) */
-    __data: TState;
-} & {
-    [K in PluginKey]?: unknown;
-};
+    /** Registry of plugins: pluginId -> pluginName */
+    __pluginRegistry?: PluginRegistry;
+    /** Plugin-specific data, keyed by pluginId */
+    __plugins?: Record<string, VersionedData<unknown>>;
+} & VersionedData<TState>;
 /**
  * Type guard to check if a value is a valid BlockStorage object.
  * Checks for the discriminator key and valid schema version.
@@ -63,7 +80,7 @@ export declare function isBlockStorage(value: unknown): value is BlockStorage;
 export declare function createBlockStorage<TState = unknown>(initialData?: TState, version?: string): BlockStorage<TState>;
 /**
  * Normalizes raw storage data to BlockStorage format.
- * If the input is already a BlockStorage, returns it as-is.
+ * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).
  * If the input is legacy format (raw state), wraps it in BlockStorage structure.
  *
  * @param raw - Raw storage data (may be legacy format or BlockStorage)
@@ -91,8 +108,12 @@ export declare function getStorageData<TState>(storage: BlockStorage<TState>): T
 export declare function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData;
 /** Payload for storage mutation operations. SDK defines specific operations. */
 export type MutateStoragePayload<T = unknown> = {
-    operation: "update-data";
+    operation: "update-block-data";
     value: T;
+} | {
+    operation: "update-plugin-data";
+    pluginId: string;
+    value: unknown;
 };
 /**
  * Updates the data in BlockStorage (immutable)
@@ -102,21 +123,6 @@ export type MutateStoragePayload<T = unknown> = {
  * @returns A new BlockStorage with updated data
  */
 export declare function updateStorageData<TValue = unknown>(storage: BlockStorage<TValue>, payload: MutateStoragePayload<TValue>): BlockStorage<TValue>;
-/**
- * Gets the data version from BlockStorage
- *
- * @param storage - The BlockStorage instance
- * @returns The data version key
- */
-export declare function getStorageDataVersion(storage: BlockStorage): string;
-/**
- * Updates the data version in BlockStorage (immutable)
- *
- * @param storage - The current BlockStorage
- * @param version - The new version key
- * @returns A new BlockStorage with updated version
- */
-export declare function updateStorageDataVersion<TState>(storage: BlockStorage<TState>, version: string): BlockStorage<TState>;
 /**
  * Storage debug view returned by __pl_storage_debugView callback.
  * Used by developer tools to display block storage info.
@@ -128,96 +134,87 @@ export interface StorageDebugView {
     data: unknown;
 }
 /**
- * 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 declare function getPluginData<TData = unknown>(storage: BlockStorage, pluginName: string): 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 declare function setPluginData<TState>(storage: BlockStorage<TState>, pluginName: string, data: unknown): BlockStorage<TState>;
-/**
- * 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
+ * Result of a successful atomic migration.
  */
-export declare function removePluginData<TState>(storage: BlockStorage<TState>, pluginName: string): BlockStorage<TState>;
-/**
- * Gets all plugin names that have data stored
- *
- * @param storage - The BlockStorage instance
- * @returns Array of plugin names (without `@plugin/` prefix)
- */
-export declare function getPluginNames(storage: BlockStorage): string[];
-/**
- * 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 declare function getFromStorage<TState, K extends keyof BlockStorage<TState>>(storage: BlockStorage<TState>, key: K): BlockStorage<TState>[K];
-/**
- * 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 declare function updateStorage<TState, K extends keyof BlockStorage<TState>>(storage: BlockStorage<TState>, key: K, value: BlockStorage<TState>[K]): BlockStorage<TState>;
-/**
- * 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: string, toVersion: string) => BlockStorage<TState>;
+export interface MigrationSuccess<TState> {
+    success: true;
+    /** The fully migrated storage - commit this to persist */
+    storage: BlockStorage<TState>;
 }
 /**
- * Default implementations of storage handlers
+ * Result of a failed atomic migration.
+ * The original storage is untouched - user must choose to abort or reset.
  */
-export declare const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>>;
+export interface MigrationFailure {
+    success: false;
+    /** Description of what failed */
+    error: string;
+    /** Which step failed: 'block' or pluginId */
+    failedAt: string;
+}
+export type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;
+/**
+ * Configuration for atomic block storage migration.
+ * Callbacks use DataVersioned format (the DataModel API format).
+ * Conversion to internal VersionedData format is handled by migrateBlockStorage().
+ */
+export interface MigrateBlockStorageConfig {
+    /** Migrate block data from any version to latest */
+    migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
+    /** Migrate each plugin's data. Return undefined to remove the plugin. */
+    migratePluginData: (pluginId: string, versioned: DataVersioned<unknown>) => DataMigrationResult<unknown> | undefined;
+    /** The new plugin registry after migration (pluginId -> pluginName) */
+    newPluginRegistry: PluginRegistry;
+    /** Factory to create initial data for new plugins */
+    createPluginData: (pluginId: string) => DataVersioned<unknown>;
+}
 /**
- * Merges custom handlers with defaults
+ * Performs atomic migration of block storage including block data and all plugins.
+ *
+ * Migration is atomic: either everything succeeds and a new storage is returned,
+ * or an error is returned and the original storage is completely untouched.
+ *
+ * Migration steps:
+ * 1. Migrate block data
+ * 2. For each plugin in newPluginRegistry:
+ *    - If plugin exists with same name: migrate its data
+ *    - Otherwise (new or type changed): create with initial data
+ *    Plugins not in newPluginRegistry are dropped.
+ *
+ * If any step throws, migration fails and original storage is preserved.
+ * User can then choose to:
+ * - Abort: keep original storage, don't update block
+ * - Reset: call createBlockStorage() to start fresh
+ *
+ * @param storage - The original storage (will not be modified)
+ * @param config - Migration configuration
+ * @returns Migration result - either success with new storage, or failure with error info
+ *
+ * @example
+ * const result = migrateBlockStorage(storage, {
+ *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),
+ *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),
+ *   newPluginRegistry: { table1: 'dataTable' as PluginName },
+ *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),
+ * });
+ *
+ * if (result.success) {
+ *   commitStorage(result.storage);
+ * } else {
+ *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);
+ *   if (userChoice === 'reset') {
+ *     commitStorage(createBlockStorage(initialData, currentVersion));
+ *   }
+ *   // else: abort, keep original
+ * }
+ */
+export declare function migrateBlockStorage(storage: BlockStorage<unknown>, config: MigrateBlockStorageConfig): MigrationResult<unknown>;
+/**
+ * Gets plugin-specific data from BlockStorage (for UI)
  *
- * @param customHandlers - Custom handlers to merge
- * @returns Complete handlers with defaults for missing functions
+ * @param storage - The BlockStorage instance
+ * @param pluginId - The plugin instance id
+ * @returns The plugin data or undefined if not set
  */
-export declare function mergeBlockStorageHandlers<TState>(customHandlers?: BlockStorageHandlers<TState>): Required<BlockStorageHandlers<TState>>;
+export declare function getPluginData<TData = unknown>(storage: BlockStorage, pluginId: string): TData | undefined;
 //# sourceMappingURL=block_storage.d.ts.map

package/dist/block_storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.d.ts","sourceRoot":"","sources":["../src/block_storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage.d.ts","sourceRoot":"","sources":["../src/block_storage.ts"],"names":[],"mappings":"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"}

package/dist/block_storage.js

@@ -53,11 +53,13 @@ function createBlockStorage(initialData = {}, version = DATA_MODEL_DEFAULT_VERSI
         [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
         __dataVersion: version,
         __data: initialData,
+        __pluginRegistry: {},
+        __plugins: {},
     };
 }
 /**
  * Normalizes raw storage data to BlockStorage format.
- * If the input is already a BlockStorage, returns it as-is.
+ * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).
  * If the input is legacy format (raw state), wraps it in BlockStorage structure.
  *
  * @param raw - Raw storage data (may be legacy format or BlockStorage)
@@ -72,6 +74,9 @@ function normalizeBlockStorage(raw) {
             __dataVersion: typeof storage.__dataVersion === "number"
                 ? DATA_MODEL_DEFAULT_VERSION
                 : storage.__dataVersion,
+            // Ensure plugin fields have defaults
+            __pluginRegistry: storage.__pluginRegistry ?? {},
+            __plugins: storage.__plugins ?? {},
         };
     }
     // Legacy format: raw is the state directly
@@ -114,124 +119,144 @@ function deriveDataFromStorage(rawStorage) {
  */
 function updateStorageData(storage, payload) {
     switch (payload.operation) {
-        case "update-data":
+        case "update-block-data":
             return { ...storage, __data: payload.value };
+        case "update-plugin-data": {
+            const { pluginId, value } = payload;
+            const currentPlugins = storage.__plugins ?? {};
+            const existingEntry = currentPlugins[pluginId];
+            const version = existingEntry?.__dataVersion ?? DATA_MODEL_DEFAULT_VERSION;
+            return {
+                ...storage,
+                __plugins: {
+                    ...currentPlugins,
+                    [pluginId]: {
+                        __dataVersion: version,
+                        __data: value,
+                    },
+                },
+            };
+        }
         default:
             throw new Error(`Unknown storage operation: ${payload.operation}`);
     }
 }
 /**
- * Gets the data version from BlockStorage
+ * Performs atomic migration of block storage including block data and all plugins.
  *
- * @param storage - The BlockStorage instance
- * @returns The data version key
- */
-function getStorageDataVersion(storage) {
-    return storage.__dataVersion;
-}
-/**
- * Updates the data version in BlockStorage (immutable)
+ * Migration is atomic: either everything succeeds and a new storage is returned,
+ * or an error is returned and the original storage is completely untouched.
  *
- * @param storage - The current BlockStorage
- * @param version - The new version key
- * @returns A new BlockStorage with updated version
- */
-function updateStorageDataVersion(storage, version) {
-    return { ...storage, __dataVersion: version };
-}
-// =============================================================================
-// Plugin Data Functions
-// =============================================================================
-/**
- * Gets plugin-specific data from BlockStorage
+ * Migration steps:
+ * 1. Migrate block data
+ * 2. For each plugin in newPluginRegistry:
+ *    - If plugin exists with same name: migrate its data
+ *    - Otherwise (new or type changed): create with initial data
+ *    Plugins not in newPluginRegistry are dropped.
  *
- * @param storage - The BlockStorage instance
- * @param pluginName - The plugin name (without `@plugin/` prefix)
- * @returns The plugin data or undefined if not set
- */
-function getPluginData(storage, pluginName) {
-    const key = `@plugin/${pluginName}`;
-    return storage[key];
-}
-/**
- * Sets plugin-specific data in BlockStorage (immutable)
+ * If any step throws, migration fails and original storage is preserved.
+ * User can then choose to:
+ * - Abort: keep original storage, don't update block
+ * - Reset: call createBlockStorage() to start fresh
  *
- * @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
- */
-function setPluginData(storage, pluginName, data) {
-    const key = `@plugin/${pluginName}`;
-    return { ...storage, [key]: data };
-}
-/**
- * Removes plugin-specific data from BlockStorage (immutable)
+ * @param storage - The original storage (will not be modified)
+ * @param config - Migration configuration
+ * @returns Migration result - either success with new storage, or failure with error info
  *
- * @param storage - The current BlockStorage
- * @param pluginName - The plugin name (without `@plugin/` prefix)
- * @returns A new BlockStorage with the plugin data removed
- */
-function removePluginData(storage, pluginName) {
-    const key = `@plugin/${pluginName}`;
-    const { [key]: _, ...rest } = storage;
-    return rest;
-}
-/**
- * Gets all plugin names that have data stored
+ * @example
+ * const result = migrateBlockStorage(storage, {
+ *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),
+ *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),
+ *   newPluginRegistry: { table1: 'dataTable' as PluginName },
+ *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),
+ * });
  *
- * @param storage - The BlockStorage instance
- * @returns Array of plugin names (without `@plugin/` prefix)
+ * if (result.success) {
+ *   commitStorage(result.storage);
+ * } else {
+ *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);
+ *   if (userChoice === 'reset') {
+ *     commitStorage(createBlockStorage(initialData, currentVersion));
+ *   }
+ *   // else: abort, keep original
+ * }
  */
-function getPluginNames(storage) {
-    return Object.keys(storage)
-        .filter((key) => key.startsWith("@plugin/"))
-        .map((key) => key.slice("@plugin/".length));
+function migrateBlockStorage(storage, config) {
+    const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;
+    // Step 1: Migrate block data
+    let migratedData;
+    let newVersion;
+    try {
+        const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });
+        migratedData = result.data;
+        newVersion = result.version;
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+            failedAt: "block",
+        };
+    }
+    // Step 2: Migrate plugins
+    const oldPlugins = storage.__plugins ?? {};
+    const oldRegistry = storage.__pluginRegistry ?? {};
+    const newPlugins = {};
+    for (const [pluginId, pluginName] of Object.entries(newPluginRegistry)) {
+        const existingEntry = oldPlugins[pluginId];
+        const existingName = oldRegistry[pluginId];
+        try {
+            if (existingEntry && existingName === pluginName) {
+                // Plugin exists with same type - migrate its data
+                const migrated = migratePluginData(pluginId, {
+                    version: existingEntry.__dataVersion,
+                    data: existingEntry.__data,
+                });
+                if (migrated) {
+                    newPlugins[pluginId] = { __dataVersion: migrated.version, __data: migrated.data };
+                }
+                // If undefined returned, plugin is intentionally removed
+            }
+            else {
+                // New plugin or type changed - create with initial data
+                const initial = createPluginData(pluginId);
+                newPlugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };
+            }
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                failedAt: pluginId,
+            };
+        }
+    }
+    // Step 3: Build final storage atomically
+    const migratedStorage = {
+        [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+        __dataVersion: newVersion,
+        __data: migratedData,
+        __pluginRegistry: newPluginRegistry,
+        __plugins: newPlugins,
+    };
+    return {
+        success: true,
+        storage: migratedStorage,
+    };
 }
-// =============================================================================
-// Generic Storage Access
-// =============================================================================
 /**
- * Gets a value from BlockStorage by key
+ * Gets plugin-specific data from BlockStorage (for UI)
  *
  * @param storage - The BlockStorage instance
- * @param key - The key to retrieve
- * @returns The value at the given key
- */
-function getFromStorage(storage, key) {
-    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
- */
-function updateStorage(storage, key, value) {
-    return { ...storage, [key]: value };
-}
-/**
- * Default implementations of storage handlers
- */
-const defaultBlockStorageHandlers = {
-    transformStateForStorage: (storage, newState) => updateStorageData(storage, { operation: "update-data", value: newState }),
-    deriveStateForArgs: (storage) => getStorageData(storage),
-    migrateStorage: (storage, _fromVersion, toVersion) => updateStorageDataVersion(storage, toVersion),
-};
-/**
- * Merges custom handlers with defaults
- *
- * @param customHandlers - Custom handlers to merge
- * @returns Complete handlers with defaults for missing functions
+ * @param pluginId - The plugin instance id
+ * @returns The plugin data or undefined if not set
  */
-function mergeBlockStorageHandlers(customHandlers) {
-    return {
-        ...defaultBlockStorageHandlers,
-        ...customHandlers,
-    };
+function getPluginData(storage, pluginId) {
+    const pluginEntry = storage.__plugins?.[pluginId];
+    if (!pluginEntry)
+        return undefined;
+    return pluginEntry.__data;
 }
 
-export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, DATA_MODEL_DEFAULT_VERSION, createBlockStorage, defaultBlockStorageHandlers, deriveDataFromStorage, getFromStorage, getPluginData, getPluginNames, getStorageData, getStorageDataVersion, isBlockStorage, mergeBlockStorageHandlers, normalizeBlockStorage, removePluginData, setPluginData, updateStorage, updateStorageData, updateStorageDataVersion };
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, DATA_MODEL_DEFAULT_VERSION, createBlockStorage, deriveDataFromStorage, getPluginData, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData };
 //# sourceMappingURL=block_storage.js.map