import { InferFactoryData, PluginFactoryLike, PluginHandle } from "./plugin_handle.js"; import { DataVersioned, TransferRecord } from "./block_migrations.js"; import { Branded } from "@milaboratories/pl-model-common"; /** * Discriminator key for BlockStorage format detection. * This unique hash-based key identifies data as BlockStorage vs legacy formats. */ export declare const BLOCK_STORAGE_KEY = "__pl_a7f3e2b9__"; /** * Type for valid schema versions */ export type BlockStorageSchemaVersion = "v1"; /** * 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 declare function isBlockStorage(value: unknown): value is BlockStorage; /** * 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 declare function createBlockStorage(initialData?: TState, version?: string): 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 */ export declare function normalizeBlockStorage(raw: unknown): BlockStorage; /** * Gets the data from BlockStorage * * @param storage - The BlockStorage instance * @returns The data value */ export declare function getStorageData(storage: BlockStorage): TState; /** * 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 declare function deriveDataFromStorage(rawStorage: unknown): TData; /** 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 declare function updateStorageData(storage: BlockStorage, payload: MutateStoragePayload): BlockStorage; /** * 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 declare function migrateBlockStorage(storage: BlockStorage, config: MigrateBlockStorageConfig): MigrationResult; /** * 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 declare function getPluginData(rawStorage: unknown, handle: PluginHandle): InferFactoryData; //# sourceMappingURL=block_storage.d.ts.map