@platforma-sdk/model 1.58.5 → 1.58.9

package/dist/block_storage.js

@@ -1,269 +1,266 @@
+import { isDataUnrecoverableError } from "./block_migrations.js";
+
+//#region src/block_storage.ts
 /**
- * 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.
- */
+* Discriminator key for BlockStorage format detection.
+* This unique hash-based key identifies data as BlockStorage vs legacy formats.
+*/
 const BLOCK_STORAGE_KEY = "__pl_a7f3e2b9__";
 /**
- * Current BlockStorage schema version.
- * Increment this when the storage structure itself changes (not block state migrations).
- */
+* Current BlockStorage schema version.
+* Increment this when the storage structure itself changes (not block state migrations).
+*/
 const BLOCK_STORAGE_SCHEMA_VERSION = "v1";
 /**
- * Default data version for new blocks without migrations.
- * Unique identifier ensures blocks are created via DataModel API.
- */
+* Default data version for new blocks without migrations.
+* Unique identifier ensures blocks are created via DataModel API.
+*/
 const DATA_MODEL_LEGACY_VERSION = "__pl_v1_d4e8f2a1__";
 /**
- * Type guard to check if a value is a valid BlockStorage object.
- * Checks for the discriminator key and valid schema version.
- */
+* Type guard to check if a value is a valid BlockStorage object.
+* Checks for the discriminator key and valid schema version.
+*/
 function isBlockStorage(value) {
-    if (value === null || typeof value !== "object")
-        return false;
-    const obj = value;
-    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
+	if (value === null || typeof value !== "object") return false;
+	return value[BLOCK_STORAGE_KEY] === "v1";
 }
-// =============================================================================
-// 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 key (defaults to DATA_MODEL_LEGACY_VERSION)
- * @returns A new BlockStorage instance with discriminator key
- */
+* Creates a BlockStorage with the given initial data
+*
+* @param initialData - The initial data value (defaults to empty object)
+* @param version - The initial data version key (defaults to DATA_MODEL_LEGACY_VERSION)
+* @returns A new BlockStorage instance with discriminator key
+*/
 function createBlockStorage(initialData = {}, version = DATA_MODEL_LEGACY_VERSION) {
-    return {
-        [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
-        __dataVersion: version,
-        __data: initialData,
-        __pluginRegistry: {},
-        __plugins: {},
-    };
+	return {
+		[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 (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)
- * @returns Normalized BlockStorage
- */
+* Normalizes raw storage data to BlockStorage format.
+* 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)
+* @returns Normalized BlockStorage
+*/
 function normalizeBlockStorage(raw) {
-    if (isBlockStorage(raw)) {
-        const storage = raw;
-        return {
-            ...storage,
-            // Fix for early released version where __dataVersion was a number
-            __dataVersion: typeof storage.__dataVersion === "number"
-                ? DATA_MODEL_LEGACY_VERSION
-                : storage.__dataVersion,
-            // Ensure plugin fields have defaults
-            __pluginRegistry: storage.__pluginRegistry ?? {},
-            __plugins: storage.__plugins ?? {},
-        };
-    }
-    // Legacy format: raw is the state directly
-    return createBlockStorage(raw);
+	if (isBlockStorage(raw)) {
+		const storage = raw;
+		return {
+			...storage,
+			__dataVersion: typeof storage.__dataVersion === "number" ? DATA_MODEL_LEGACY_VERSION : storage.__dataVersion,
+			__pluginRegistry: storage.__pluginRegistry ?? {},
+			__plugins: storage.__plugins ?? {}
+		};
+	}
+	return createBlockStorage(raw);
 }
-// =============================================================================
-// Data Access & Update Functions
-// =============================================================================
 /**
- * Gets the data from BlockStorage
- *
- * @param storage - The BlockStorage instance
- * @returns The data value
- */
+* Gets the data from BlockStorage
+*
+* @param storage - The BlockStorage instance
+* @returns The data value
+*/
 function getStorageData(storage) {
-    return storage.__data;
+	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
- */
+* 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
+*/
 function deriveDataFromStorage(rawStorage) {
-    // Normalize to BlockStorage format (handles legacy formats too)
-    const storage = normalizeBlockStorage(rawStorage);
-    return getStorageData(storage);
+	return getStorageData(normalizeBlockStorage(rawStorage));
 }
 /**
- * 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
- */
+* 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
+*/
 function updateStorageData(storage, payload) {
-    switch (payload.operation) {
-        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_LEGACY_VERSION;
-            return {
-                ...storage,
-                __plugins: {
-                    ...currentPlugins,
-                    [pluginId]: {
-                        __dataVersion: version,
-                        __data: value,
-                    },
-                },
-            };
-        }
-        default:
-            throw new Error(`Unknown storage operation: ${payload.operation}`);
-    }
+	switch (payload.operation) {
+		case "update-block-data": return {
+			...storage,
+			__data: payload.value
+		};
+		case "update-plugin-data": {
+			const { pluginId, value } = payload;
+			const currentPlugins = storage.__plugins ?? {};
+			const version = currentPlugins[pluginId]?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;
+			return {
+				...storage,
+				__plugins: {
+					...currentPlugins,
+					[pluginId]: {
+						__dataVersion: version,
+						__data: value
+					}
+				}
+			};
+		}
+		default: throw new Error(`Unknown storage operation: ${payload.operation}`);
+	}
 }
 /**
- * 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
- * }
- */
+* 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
+* }
+*/
 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 [key, pluginName] of Object.entries(newPluginRegistry)) {
-        const handle = key;
-        const existingEntry = oldPlugins[handle];
-        const existingName = oldRegistry[handle];
-        try {
-            if (existingEntry && existingName === pluginName) {
-                // Plugin exists with same type - migrate its data
-                const migrated = migratePluginData(handle, {
-                    version: existingEntry.__dataVersion,
-                    data: existingEntry.__data,
-                });
-                if (migrated) {
-                    newPlugins[handle] = { __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(handle);
-                newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };
-            }
-        }
-        catch (error) {
-            return {
-                success: false,
-                error: error instanceof Error ? error.message : String(error),
-                failedAt: handle,
-            };
-        }
-    }
-    // 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,
-    };
+	const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;
+	let migratedData;
+	let newVersion;
+	let transfers;
+	try {
+		const result = migrateBlockData({
+			version: storage.__dataVersion,
+			data: storage.__data
+		});
+		migratedData = result.data;
+		newVersion = result.version;
+		transfers = result.transfers;
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : String(error),
+			failedAt: "block"
+		};
+	}
+	const oldPlugins = storage.__plugins ?? {};
+	const oldRegistry = storage.__pluginRegistry ?? {};
+	const newPlugins = {};
+	for (const [key, pluginName] of Object.entries(newPluginRegistry)) {
+		const handle = key;
+		const existingEntry = oldPlugins[handle];
+		const existingName = oldRegistry[handle];
+		try {
+			if (existingEntry && existingName === pluginName) {
+				const migrated = migratePluginData(handle, {
+					version: existingEntry.__dataVersion,
+					data: existingEntry.__data
+				});
+				if (migrated) newPlugins[handle] = {
+					__dataVersion: migrated.version,
+					__data: migrated.data
+				};
+			} else if (existingEntry) {
+				let recovered = false;
+				try {
+					const migrated = migratePluginData(handle, {
+						version: DATA_MODEL_LEGACY_VERSION,
+						data: existingEntry.__data
+					});
+					if (migrated) {
+						newPlugins[handle] = {
+							__dataVersion: migrated.version,
+							__data: migrated.data
+						};
+						recovered = true;
+					}
+				} catch (recoverError) {
+					if (!isDataUnrecoverableError(recoverError)) throw recoverError;
+				}
+				if (!recovered) {
+					const transfer = transfers[handle];
+					const initial = createPluginData(handle, transfer);
+					newPlugins[handle] = {
+						__dataVersion: initial.version,
+						__data: initial.data
+					};
+				}
+			} else {
+				const transfer = transfers[handle];
+				const initial = createPluginData(handle, transfer);
+				newPlugins[handle] = {
+					__dataVersion: initial.version,
+					__data: initial.data
+				};
+			}
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+				failedAt: handle
+			};
+		}
+	}
+	return {
+		success: true,
+		storage: {
+			[BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+			__dataVersion: newVersion,
+			__data: migratedData,
+			__pluginRegistry: newPluginRegistry,
+			__plugins: newPlugins
+		}
+	};
 }
 /**
- * Gets plugin-specific data from block storage.
- * Accepts raw storage (any format) and normalizes internally.
- *
- * When called with a typed PluginHandle<F>, the return type is automatically
- * inferred from the factory's phantom `__types.data` field.
- *
- * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)
- * @param handle - The plugin handle (branded plugin instance id)
- * @returns The plugin data, typed via factory inference
- * @throws If plugin is not found in storage
- */
+* Gets plugin-specific data from block storage.
+* Accepts raw storage (any format) and normalizes internally.
+*
+* When called with a typed PluginHandle<F>, the return type is automatically
+* inferred from the factory's phantom `__types.data` field.
+*
+* @param rawStorage - Raw block storage (may be legacy format or BlockStorage)
+* @param handle - The plugin handle (branded plugin instance id)
+* @returns The plugin data, typed via factory inference
+* @throws If plugin is not found in storage
+*/
 function getPluginData(rawStorage, handle) {
-    const storage = normalizeBlockStorage(rawStorage);
-    const pluginEntry = storage.__plugins?.[handle];
-    if (!pluginEntry)
-        throw new Error(`Plugin '${handle}' not found in block storage`);
-    return pluginEntry.__data;
+	const pluginEntry = normalizeBlockStorage(rawStorage).__plugins?.[handle];
+	if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);
+	return pluginEntry.__data;
 }
 
+//#endregion
 export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, DATA_MODEL_LEGACY_VERSION, createBlockStorage, deriveDataFromStorage, getPluginData, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData };
-//# sourceMappingURL=block_storage.js.map
+//# sourceMappingURL=block_storage.js.map

package/dist/block_storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.js","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned } from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Throws on failure. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins */\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data\n  let migratedData: unknown;\n  let newVersion: string;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else {\n        // New plugin or type changed - create with initial data\n        const initial = createPluginData(handle);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage.js","names":[],"sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport {\n  type DataVersioned,\n  type TransferRecord,\n  isDataUnrecoverableError,\n} from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Returns migrated data and transfers. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins. Transfer is provided when a\n   *  .transfer() was defined for this plugin in the block's migration chain. */\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data and collect transfers\n  let migratedData: unknown;\n  let newVersion: string;\n  let transfers: TransferRecord;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n    transfers = result.transfers;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else if (existingEntry) {\n        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.\n        // If the new plugin has upgradeLegacy(), it migrates the old data.\n        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.\n        let recovered = false;\n        try {\n          const migrated = migratePluginData(handle, {\n            version: DATA_MODEL_LEGACY_VERSION,\n            data: existingEntry.__data,\n          });\n          if (migrated) {\n            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n            recovered = true;\n          }\n        } catch (recoverError) {\n          if (!isDataUnrecoverableError(recoverError)) throw recoverError;\n        }\n        if (!recovered) {\n          const transfer = transfers[handle];\n          const initial = createPluginData(handle, transfer);\n          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n        }\n      } else {\n        // New plugin - create with initial data, passing transfer if available\n        const transfer = transfers[handle];\n        const initial = createPluginData(handle, transfer);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"mappings":"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"}