/** * 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 */ import type { Branded } from "@milaboratories/pl-model-common"; import { type DataVersioned, type TransferRecord, isDataUnrecoverableError, } from "./block_migrations"; import type { PluginHandle, PluginFactoryLike, InferFactoryData } from "./plugin_handle"; // ============================================================================= // Core Types // ============================================================================= /** * Discriminator key for BlockStorage format detection. * This unique hash-based key identifies data as BlockStorage vs legacy formats. */ export const BLOCK_STORAGE_KEY = "__pl_a7f3e2b9__"; /** * Current BlockStorage schema version. * Increment this when the storage structure itself changes (not block state migrations). */ export const BLOCK_STORAGE_SCHEMA_VERSION = "v1"; /** * Default data version for new blocks without migrations. * Unique identifier ensures blocks are created via DataModel API. */ export const DATA_MODEL_LEGACY_VERSION = "__pl_v1_d4e8f2a1__"; /** * Type for valid schema versions */ export type BlockStorageSchemaVersion = "v1"; // Add 'v2', 'v3', etc. as schema evolves /** * 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 PluginName = Branded; /** * 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; /** * Versioned data - used for both block data and plugin data */ export interface VersionedData { /** 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) * - __pluginRegistry: Map from pluginId to pluginName (optional) * - __plugins: Plugin-specific data keyed by pluginId (optional) */ export type BlockStorage = { /** Schema version - the key itself is the discriminator */ readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion; /** Registry of plugins: pluginId -> pluginName */ __pluginRegistry?: PluginRegistry; /** Plugin-specific data, keyed by plugin handle */ __plugins?: Record>; } & VersionedData; /** * Type guard to check if a value is a valid BlockStorage object. * Checks for the discriminator key and valid schema version. */ export function isBlockStorage(value: unknown): value is BlockStorage { if (value === null || typeof value !== "object") return false; const obj = value as Record; const schemaVersion = obj[BLOCK_STORAGE_KEY]; // Currently only 'v1' is valid, but this allows future versions return schemaVersion === "v1"; // Add more versions as schema evolves } // ============================================================================= // Factory Functions // ============================================================================= /** * Creates a BlockStorage with the given initial data * * @param initialData - The initial data value (defaults to empty object) * @param version - The initial data version key (defaults to DATA_MODEL_LEGACY_VERSION) * @returns A new BlockStorage instance with discriminator key */ export function createBlockStorage( initialData: TState = {} as TState, version: string = DATA_MODEL_LEGACY_VERSION, ): BlockStorage { 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 */ export function normalizeBlockStorage(raw: unknown): BlockStorage { if (isBlockStorage(raw)) { const storage = raw as BlockStorage; 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 as TState); } // ============================================================================= // Data Access & Update Functions // ============================================================================= /** * Gets the data from BlockStorage * * @param storage - The BlockStorage instance * @returns The data value */ export function getStorageData(storage: BlockStorage): TState { return storage.__data; } /** * Derives data from raw block storage. * This function is meant to be called from sdk/ui-vue to extract * user-facing data from the raw storage returned by the middle layer. * * The middle layer returns raw storage (opaque to it), and the UI * uses this function to derive the actual data value. * * @param rawStorage - Raw storage data from middle layer (may be any format) * @returns The extracted data value, or undefined if storage is undefined/null */ export function deriveDataFromStorage(rawStorage: unknown): TData { // Normalize to BlockStorage format (handles legacy formats too) const storage = normalizeBlockStorage(rawStorage); return getStorageData(storage); } /** Payload for storage mutation operations. SDK defines specific operations. */ export type MutateStoragePayload = | { operation: "update-block-data"; value: T } | { operation: "update-plugin-data"; pluginId: PluginHandle; value: unknown }; /** * Updates the data in BlockStorage (immutable) * * @param storage - The current BlockStorage * @param payload - The update payload with operation and value * @returns A new BlockStorage with updated data */ export function updateStorageData( storage: BlockStorage, payload: MutateStoragePayload, ): BlockStorage { 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 as { operation: string }).operation}`); } } // ============================================================================= // Atomic Migration // ============================================================================= /** * Result of a successful atomic migration. */ export interface MigrationSuccess { success: true; /** The fully migrated storage - commit this to persist */ storage: BlockStorage; } /** * Result of a failed atomic migration. * The original storage is untouched - user must choose to abort or reset. */ export interface MigrationFailure { success: false; /** Description of what failed */ error: string; /** Which step failed: 'block' or pluginId */ failedAt: string; } export type MigrationResult = MigrationSuccess | 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. Returns migrated data and transfers. */ migrateBlockData: (versioned: DataVersioned) => DataVersioned & { transfers: TransferRecord; }; /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */ migratePluginData: ( handle: PluginHandle, versioned: DataVersioned, ) => DataVersioned | undefined; /** The new plugin registry after migration (pluginId -> pluginName) */ newPluginRegistry: PluginRegistry; /** Factory to create initial data for new plugins. Transfer is provided when a * .transfer() was defined for this plugin in the block's migration chain. */ createPluginData: ( handle: PluginHandle, transfer?: DataVersioned, ) => DataVersioned; } /** * 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 function migrateBlockStorage( storage: BlockStorage, config: MigrateBlockStorageConfig, ): MigrationResult { const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config; // Step 1: Migrate block data and collect transfers let migratedData: unknown; let newVersion: string; let transfers: TransferRecord; 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", }; } // Step 2: Migrate plugins const oldPlugins = storage.__plugins ?? {}; const oldRegistry = storage.__pluginRegistry ?? {}; const newPlugins: Record> = {}; for (const [key, pluginName] of Object.entries(newPluginRegistry)) { const handle = key as PluginHandle; 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 if (existingEntry) { // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION. // If the new plugin has upgradeLegacy(), it migrates the old data. // If not, defaultRecover throws DataUnrecoverableError → fall back to init. 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 { // New plugin - create with initial data, passing transfer if available 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, }; } } // Step 3: Build final storage atomically const migratedStorage: BlockStorage = { [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION, __dataVersion: newVersion, __data: migratedData, __pluginRegistry: newPluginRegistry, __plugins: newPlugins, }; return { success: true, storage: migratedStorage, }; } /** * Gets plugin-specific data from block storage. * Accepts raw storage (any format) and normalizes internally. * * When called with a typed PluginHandle, 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 */ export function getPluginData( rawStorage: unknown, handle: PluginHandle, ): InferFactoryData { const storage = normalizeBlockStorage(rawStorage); const pluginEntry = storage.__plugins?.[handle]; if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`); return pluginEntry.__data as InferFactoryData; }