@platforma-sdk/model 1.58.5 → 1.58.11

package/dist/block_storage.d.ts

@@ -1,54 +1,36 @@
-/**
- * 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 } from "./block_migrations";
-import type { PluginHandle, PluginFactoryLike, InferFactoryData } from "./plugin_handle";
+import { InferFactoryData, PluginFactoryLike, PluginHandle } from "./plugin_handle.js";
+import { DataVersioned, TransferRecord } from "./block_migrations.js";
+import { Branded } from "@milaboratories/pl-model-common";
+
+//#region src/block_storage.d.ts
 /**
  * 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__";
-/**
- * Current BlockStorage schema version.
- * Increment this when the storage structure itself changes (not block state migrations).
- */
-export declare const BLOCK_STORAGE_SCHEMA_VERSION = "v1";
-/**
- * Default data version for new blocks without migrations.
- * Unique identifier ensures blocks are created via DataModel API.
- */
-export declare const DATA_MODEL_LEGACY_VERSION = "__pl_v1_d4e8f2a1__";
+declare const BLOCK_STORAGE_KEY = "__pl_a7f3e2b9__";
 /**
  * Type for valid schema versions
  */
-export type BlockStorageSchemaVersion = "v1";
+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<string, "PluginName">;
+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<PluginHandle, PluginName>;
+type PluginRegistry = Record<PluginHandle, 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;
+interface VersionedData<TData = unknown> {
+  /** Version of the data, used for migrations */
+  __dataVersion: string;
+  /** The persistent data */
+  __data: TData;
 }
 /**
  * Core BlockStorage type that holds:
@@ -58,19 +40,16 @@ export interface VersionedData<TData = unknown> {
  * - __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;
-    /** Registry of plugins: pluginId -> pluginName */
-    __pluginRegistry?: PluginRegistry;
-    /** Plugin-specific data, keyed by plugin handle */
-    __plugins?: Record<PluginHandle, VersionedData<unknown>>;
+type BlockStorage<TState = unknown> = {
+  /** 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<PluginHandle, 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.
  */
-export declare function isBlockStorage(value: unknown): value is BlockStorage;
+declare function isBlockStorage(value: unknown): value is BlockStorage;
 /**
  * Creates a BlockStorage with the given initial data
  *
@@ -78,7 +57,7 @@ export declare function isBlockStorage(value: unknown): value is BlockStorage;
  * @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<TState = unknown>(initialData?: TState, version?: string): BlockStorage<TState>;
+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 (with defaults for missing fields).
@@ -87,14 +66,14 @@ export declare function createBlockStorage<TState = unknown>(initialData?: TStat
  * @param raw - Raw storage data (may be legacy format or BlockStorage)
  * @returns Normalized BlockStorage
  */
-export declare function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState>;
+declare function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState>;
 /**
  * Gets the data from BlockStorage
  *
  * @param storage - The BlockStorage instance
  * @returns The data value
  */
-export declare function getStorageData<TState>(storage: BlockStorage<TState>): TState;
+declare function getStorageData<TState>(storage: BlockStorage<TState>): TState;
 /**
  * Derives data from raw block storage.
  * This function is meant to be called from sdk/ui-vue to extract
@@ -106,15 +85,15 @@ export declare function getStorageData<TState>(storage: BlockStorage<TState>): T
  * @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<TData = unknown>(rawStorage: unknown): TData;
+declare function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData;
 /** Payload for storage mutation operations. SDK defines specific operations. */
-export type MutateStoragePayload<T = unknown> = {
-    operation: "update-block-data";
-    value: T;
+type MutateStoragePayload<T = unknown> = {
+  operation: "update-block-data";
+  value: T;
 } | {
-    operation: "update-plugin-data";
-    pluginId: PluginHandle;
-    value: unknown;
+  operation: "update-plugin-data";
+  pluginId: PluginHandle;
+  value: unknown;
 };
 /**
  * Updates the data in BlockStorage (immutable)
@@ -123,51 +102,54 @@ export type MutateStoragePayload<T = unknown> = {
  * @param payload - The update payload with operation and value
  * @returns A new BlockStorage with updated data
  */
-export declare function updateStorageData<TValue = unknown>(storage: BlockStorage<TValue>, payload: MutateStoragePayload<TValue>): BlockStorage<TValue>;
+declare function updateStorageData<TValue = unknown>(storage: BlockStorage<TValue>, payload: MutateStoragePayload<TValue>): BlockStorage<TValue>;
 /**
  * Storage debug view returned by __pl_storage_debugView callback.
  * Used by developer tools to display block storage info.
  */
-export interface StorageDebugView {
-    /** Current data version key */
-    dataVersion: string;
-    /** Raw data payload stored in BlockStorage */
-    data: unknown;
+interface StorageDebugView {
+  /** Current data version key */
+  dataVersion: string;
+  /** Raw data payload stored in BlockStorage */
+  data: unknown;
 }
 /**
  * Result of a successful atomic migration.
  */
-export interface MigrationSuccess<TState> {
-    success: true;
-    /** The fully migrated storage - commit this to persist */
-    storage: BlockStorage<TState>;
+interface MigrationSuccess<TState> {
+  success: true;
+  /** The fully migrated storage - commit this to persist */
+  storage: BlockStorage<TState>;
 }
 /**
  * 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;
+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;
+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. Throws on failure. */
-    migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;
-    /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */
-    migratePluginData: (handle: PluginHandle, versioned: DataVersioned<unknown>) => DataVersioned<unknown> | undefined;
-    /** The new plugin registry after migration (pluginId -> pluginName) */
-    newPluginRegistry: PluginRegistry;
-    /** Factory to create initial data for new plugins */
-    createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
+interface MigrateBlockStorageConfig {
+  /** Migrate block data from any version to latest. Returns migrated data and transfers. */
+  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {
+    transfers: TransferRecord;
+  };
+  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */
+  migratePluginData: (handle: PluginHandle, versioned: DataVersioned<unknown>) => DataVersioned<unknown> | 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<unknown>) => DataVersioned<unknown>;
 }
 /**
  * Performs atomic migration of block storage including block data and all plugins.
@@ -209,7 +191,7 @@ export interface MigrateBlockStorageConfig {
  *   // else: abort, keep original
  * }
  */
-export declare function migrateBlockStorage(storage: BlockStorage<unknown>, config: MigrateBlockStorageConfig): MigrationResult<unknown>;
+declare function migrateBlockStorage(storage: BlockStorage<unknown>, config: MigrateBlockStorageConfig): MigrationResult<unknown>;
 /**
  * Gets plugin-specific data from block storage.
  * Accepts raw storage (any format) and normalizes internally.
@@ -222,5 +204,7 @@ export declare function migrateBlockStorage(storage: BlockStorage<unknown>, conf
  * @returns The plugin data, typed via factory inference
  * @throws If plugin is not found in storage
  */
-export declare function getPluginData<F extends PluginFactoryLike>(rawStorage: unknown, handle: PluginHandle<F>): InferFactoryData<F>;
+declare function getPluginData<F extends PluginFactoryLike>(rawStorage: unknown, handle: PluginHandle<F>): InferFactoryData<F>;
+//#endregion
+export { BlockStorage, BlockStorageSchemaVersion, MigrateBlockStorageConfig, MigrationFailure, MigrationResult, MigrationSuccess, MutateStoragePayload, PluginName, PluginRegistry, StorageDebugView, VersionedData, createBlockStorage, deriveDataFromStorage, getPluginData, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData };
 //# sourceMappingURL=block_storage.d.ts.map