@platforma-sdk/model 1.58.3 → 1.58.9

package/dist/block_migrations.d.ts

@@ -1,29 +1,37 @@
-export type DataVersionKey = string;
-export type DataMigrateFn<From, To> = (prev: Readonly<From>) => To;
-export type DataCreateFn<T> = () => T;
-export type DataRecoverFn<T> = (version: DataVersionKey, data: unknown) => T;
+//#region src/block_migrations.d.ts
+type DataVersionKey = string;
+type DataMigrateFn<From, To> = (prev: Readonly<From>) => To;
+type DataCreateFn<T> = () => T;
+type DataRecoverFn<T> = (version: DataVersionKey, data: unknown) => T;
+/**
+ * Minimal interface that .transfer() accepts. PluginInstance implements this.
+ * Defined here to avoid circular dependency with plugin_model.ts.
+ */
+interface TransferTarget<Id extends string = string, TransferData = never> {
+  readonly id: Id;
+  /** Version key in the plugin's data model chain where transferred data enters. */
+  readonly transferVersion: string;
+  /** @internal Phantom field for TransferData type extraction */
+  readonly __transferBrand?: TransferData;
+}
+/** Internal record of a single transfer step in the migration chain. */
+type TransferStep = {
+  pluginId: string; /** Capture data before this step index executes. */
+  beforeStepIndex: number;
+  extract: (data: unknown) => unknown; /** Version key in the plugin's data model chain where the transferred data enters. */
+  targetVersion: string;
+};
+/** Map of plugin ID → versioned data extracted during migration. */
+type TransferRecord = Record<string, DataVersioned<unknown>>;
 /** Versioned data wrapper for persistence */
-export type DataVersioned<T> = {
-    version: DataVersionKey;
-    data: T;
+type DataVersioned<T> = {
+  version: DataVersionKey;
+  data: T;
 };
-/** Create a DataVersioned wrapper with correct shape */
-export declare function makeDataVersioned<T>(version: DataVersionKey, data: T): DataVersioned<T>;
-/** Thrown when a migration step fails. */
-export declare class DataMigrationError extends Error {
-    name: string;
-    constructor(message: string);
-}
-/** Thrown by recover() to signal unrecoverable data. */
-export declare class DataUnrecoverableError extends Error {
-    name: string;
-    constructor(dataVersion: DataVersionKey);
-}
-export declare function isDataUnrecoverableError(error: unknown): error is DataUnrecoverableError;
 type MigrationStep = {
-    fromVersion: DataVersionKey;
-    toVersion: DataVersionKey;
-    migrate: (data: unknown) => unknown;
+  fromVersion: DataVersionKey;
+  toVersion: DataVersionKey;
+  migrate: (data: unknown) => unknown;
 };
 /**
  * Default recover function for unknown versions.
@@ -37,27 +45,27 @@ type MigrationStep = {
  *   return defaultRecover(version, data);
  * })
  */
-export declare const defaultRecover: DataRecoverFn<never>;
 /** Symbol for internal builder creation method */
 declare const FROM_BUILDER: unique symbol;
 /** Legacy V1 model state shape: { args, uiState } */
-export type LegacyV1State<Args, UiState> = {
-    args: Args;
-    uiState: UiState;
+type LegacyV1State<Args, UiState> = {
+  args: Args;
+  uiState: UiState;
 };
 /** Internal state passed from builder to DataModel */
 type BuilderState<S> = {
-    versionChain: DataVersionKey[];
-    steps: MigrationStep[];
-    initialDataFn: () => S;
-    recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
-    /** Index of the first step to run after recovery. Equals the number of steps
-     *  present at the time recover() was called. */
-    recoverFromIndex?: number;
+  versionChain: DataVersionKey[];
+  steps: MigrationStep[];
+  transferSteps: TransferStep[];
+  initialDataFn: () => S;
+  recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
+  /** Index of the first step to run after recovery. Equals the number of steps
+   *  present at the time recover() was called. */
+  recoverFromIndex?: number;
 };
 type RecoverState = {
-    recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
-    recoverFromIndex?: number;
+  recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
+  recoverFromIndex?: number;
 };
 /**
  * Abstract base for both migration chain types.
@@ -68,52 +76,66 @@ type RecoverState = {
  *
  * @internal
  */
-declare abstract class MigrationChainBase<Current> {
-    protected readonly versionChain: DataVersionKey[];
-    protected readonly migrationSteps: MigrationStep[];
-    protected constructor(state: {
-        versionChain: DataVersionKey[];
-        steps: MigrationStep[];
-    });
-    /** Appends a migration step and returns the new versionChain and steps arrays. */
-    protected buildStep<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): {
-        versionChain: DataVersionKey[];
-        steps: MigrationStep[];
-    };
-    /** Returns recover-specific fields for DataModel construction. Overridden by WithRecover. */
-    protected recoverState(): RecoverState;
-    /**
-     * Finalize the DataModel with initial data factory.
-     *
-     * @param initialData - Factory function returning the initial state
-     * @returns Finalized DataModel instance
-     */
-    init(initialData: DataCreateFn<Current>): DataModel<Current>;
+declare abstract class MigrationChainBase<Current, Transfers extends Record<string, unknown> = {}> {
+  protected readonly versionChain: DataVersionKey[];
+  protected readonly migrationSteps: MigrationStep[];
+  protected readonly transferSteps: TransferStep[];
+  protected constructor(state: {
+    versionChain: DataVersionKey[];
+    steps: MigrationStep[];
+    transferSteps?: TransferStep[];
+  });
+  /** Appends a migration step and returns the new versionChain and steps arrays. */
+  protected buildStep<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): {
+    versionChain: DataVersionKey[];
+    steps: MigrationStep[];
+  };
+  /** Validates uniqueness and records a TransferStep. */
+  protected buildTransfer<Id extends string, L>(target: TransferTarget<Id, L>, extract: (data: Current) => L): {
+    transferSteps: TransferStep[];
+  };
+  /** Returns recover-specific fields for DataModel construction. Overridden by WithRecover. */
+  protected recoverState(): RecoverState;
+  /**
+   * Finalize the DataModel with initial data factory.
+   *
+   * @param initialData - Factory function returning the initial state
+   * @returns Finalized DataModel instance
+   */
+  init(initialData: DataCreateFn<Current>): DataModel<Current, Transfers>;
 }
 /**
  * Migration chain after recover() or upgradeLegacy() has been called.
- * Further migrate() calls are allowed; recover() and upgradeLegacy() are not
+ * Further migrate() and transfer() calls are allowed; recover() and upgradeLegacy() are not
  * (enforced by type — no such methods on this class).
  *
  * @typeParam Current - Data type at the current point in the chain
+ * @typeParam Transfers - Accumulated transfer types keyed by plugin ID
  * @internal
  */
-declare class DataModelMigrationChainWithRecover<Current> extends MigrationChainBase<Current> {
-    private readonly recoverFn?;
-    private readonly recoverFromIndex?;
-    /** @internal */
-    constructor(state: {
-        versionChain: DataVersionKey[];
-        steps: MigrationStep[];
-        recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
-        recoverFromIndex?: number;
-    });
-    protected recoverState(): RecoverState;
-    /**
-     * Add a migration step. Same semantics as on the base chain.
-     * recover() and upgradeLegacy() are not available — one has already been called.
-     */
-    migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChainWithRecover<Next>;
+declare class DataModelMigrationChainWithRecover<Current, Transfers extends Record<string, unknown> = {}> extends MigrationChainBase<Current, Transfers> {
+  private readonly recoverFn?;
+  private readonly recoverFromIndex?;
+  /** @internal */
+  constructor(state: {
+    versionChain: DataVersionKey[];
+    steps: MigrationStep[];
+    transferSteps?: TransferStep[];
+    recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
+    recoverFromIndex?: number;
+  });
+  protected recoverState(): RecoverState;
+  /**
+   * Add a migration step. Same semantics as on the base chain.
+   * recover() and upgradeLegacy() are not available — one has already been called.
+   */
+  migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChainWithRecover<Next, Transfers>;
+  /**
+   * Extract data at the current chain position for seeding a new plugin.
+   * The extract function's return type must match the plugin's transfer data type.
+   * Duplicate plugin IDs are rejected at both type and runtime level.
+   */
+  transfer<Id extends string, L>(target: TransferTarget<Id & (Id extends keyof Transfers ? never : string), L>, extract: (data: Current) => L): DataModelMigrationChainWithRecover<Current, Transfers & Record<Id, L>>;
 }
 /**
  * Migration chain builder.
@@ -122,50 +144,70 @@ declare class DataModelMigrationChainWithRecover<Current> extends MigrationChain
  * Duplicate version keys throw at runtime.
  *
  * @typeParam Current - Data type at the current point in the migration chain
+ * @typeParam Transfers - Accumulated transfer types keyed by plugin ID
  * @internal
  */
-declare class DataModelMigrationChain<Current> extends MigrationChainBase<Current> {
-    /** @internal */
-    constructor({ versionChain, steps, }: {
-        versionChain: DataVersionKey[];
-        steps?: MigrationStep[];
-    });
-    /**
-     * Add a migration step transforming data from the current version to the next.
-     *
-     * @typeParam Next - Data type of the next version
-     * @param nextVersion - Version key to migrate to (must be unique in the chain)
-     * @param fn - Migration function
-     * @returns Builder with the next version as current
-     *
-     * @example
-     * .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }))
-     */
-    migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChain<Next>;
-    /**
-     * Set a recovery handler for unknown or legacy versions.
-     *
-     * The recover function is called when data has a version not in the migration chain.
-     * It must return data of the type at this point in the chain (Current). Any migrate()
-     * steps added after recover() will then run on the recovered data.
-     *
-     * Can only be called once — the returned chain has no recover() method.
-     *
-     * @param fn - Recovery function returning Current (the type at this chain position)
-     * @returns Builder with migrate() and init() but without recover()
-     *
-     * @example
-     * // Recover between migrations — recovered data goes through v3 migration
-     * new DataModelBuilder<V1>("v1")
-     *   .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
-     *   .recover((version, data) => {
-     *     if (version === 'legacy') return transformLegacy(data); // returns V2
-     *     return defaultRecover(version, data);
-     *   })
-     *   .migrate<V3>("v3", (v2) => ({ ...v2, description: "" }))
-     *   .init(() => ({ count: 0, label: "", description: "" }));
-     */
-    recover(fn: DataRecoverFn<Current>): DataModelMigrationChainWithRecover<Current>;
+declare class DataModelMigrationChain<Current, Transfers extends Record<string, unknown> = {}> extends MigrationChainBase<Current, Transfers> {
+  /** @internal */
+  constructor({
+    versionChain,
+    steps,
+    transferSteps
+  }: {
+    versionChain: DataVersionKey[];
+    steps?: MigrationStep[];
+    transferSteps?: TransferStep[];
+  });
+  /**
+   * Add a migration step transforming data from the current version to the next.
+   *
+   * @typeParam Next - Data type of the next version
+   * @param nextVersion - Version key to migrate to (must be unique in the chain)
+   * @param fn - Migration function
+   * @returns Builder with the next version as current
+   *
+   * @example
+   * .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }))
+   */
+  migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChain<Next, Transfers>;
+  /**
+   * Extract data at the current chain position for seeding a new plugin.
+   * The extract function's return type must match the plugin's transfer data type.
+   * Duplicate plugin IDs are rejected at both type and runtime level.
+   *
+   * Calling .transfer() on DataModelInitialChain returns DataModelMigrationChain,
+   * which removes .upgradeLegacy() from the chain (preventing a problematic combination).
+   *
+   * @example
+   * .from<V1>("v1")
+   * .transfer(tablePlugin, (v1) => ({ state: v1.tableState }))
+   * .migrate<V2>("v2", ({ tableState: _, ...rest }) => rest)
+   */
+  transfer<Id extends string, L>(target: TransferTarget<Id & (Id extends keyof Transfers ? never : string), L>, extract: (data: Current) => L): DataModelMigrationChain<Current, Transfers & Record<Id, L>>;
+  /**
+   * Set a recovery handler for unknown or legacy versions.
+   *
+   * The recover function is called when data has a version not in the migration chain.
+   * It must return data of the type at this point in the chain (Current). Any migrate()
+   * steps added after recover() will then run on the recovered data.
+   *
+   * Can only be called once — the returned chain has no recover() method.
+   *
+   * @param fn - Recovery function returning Current (the type at this chain position)
+   * @returns Builder with migrate() and init() but without recover()
+   *
+   * @example
+   * // Recover between migrations — recovered data goes through v3 migration
+   * new DataModelBuilder<V1>("v1")
+   *   .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
+   *   .recover((version, data) => {
+   *     if (version === 'legacy') return transformLegacy(data); // returns V2
+   *     return defaultRecover(version, data);
+   *   })
+   *   .migrate<V3>("v3", (v2) => ({ ...v2, description: "" }))
+   *   .init(() => ({ count: 0, label: "", description: "" }));
+   */
+  recover(fn: DataRecoverFn<Current>): DataModelMigrationChainWithRecover<Current, Transfers>;
 }
 /**
  * Initial migration chain returned by `.from()`.
@@ -173,44 +215,45 @@ declare class DataModelMigrationChain<Current> extends MigrationChainBase<Curren
  * any `.migrate()` calls, since legacy data always arrives at the initial version.
  *
  * @typeParam Current - Data type at the initial version
+ * @typeParam Transfers - Accumulated transfer types keyed by plugin ID
  * @internal
  */
-declare class DataModelInitialChain<Current> extends DataModelMigrationChain<Current> {
-    /**
-     * Handle legacy V1 model state ({ args, uiState }) when upgrading a block from
-     * BlockModel V1 to BlockModelV3.
-     *
-     * When a V1 block is upgraded, its stored state `{ args, uiState }` is normalized
-     * to the internal default version. This method inserts a migration step from that
-     * internal version to the version specified in `.from()`, using the provided typed
-     * callback to transform the legacy shape. Non-legacy data passes through unchanged.
-     *
-     * Must be called right after `.from()` — not available after `.migrate()` calls.
-     * Any `.migrate()` steps added after `upgradeLegacy()` will run on the transformed result.
-     *
-     * Can only be called once — the returned chain has no upgradeLegacy() method.
-     * Mutually exclusive with recover().
-     *
-     * @typeParam Args - Type of the legacy block args
-     * @typeParam UiState - Type of the legacy block uiState
-     * @param fn - Typed transform from { args, uiState } to Current
-     * @returns Builder with migrate() and init() but without recover() or upgradeLegacy()
-     *
-     * @example
-     * type OldArgs = { inputFile: string; threshold: number };
-     * type OldUiState = { selectedTab: string };
-     * type BlockData = { inputFile: string; threshold: number; selectedTab: string };
-     *
-     * const dataModel = new DataModelBuilder()
-     *   .from<BlockData>("v1")
-     *   .upgradeLegacy<OldArgs, OldUiState>(({ args, uiState }) => ({
-     *     inputFile: args.inputFile,
-     *     threshold: args.threshold,
-     *     selectedTab: uiState.selectedTab,
-     *   }))
-     *   .init(() => ({ inputFile: '', threshold: 0, selectedTab: 'main' }));
-     */
-    upgradeLegacy<Args, UiState = unknown>(fn: (legacy: LegacyV1State<Args, UiState>) => Current): DataModelMigrationChainWithRecover<Current>;
+declare class DataModelInitialChain<Current, Transfers extends Record<string, unknown> = {}> extends DataModelMigrationChain<Current, Transfers> {
+  /**
+   * Handle legacy V1 model state ({ args, uiState }) when upgrading a block from
+   * BlockModel V1 to BlockModelV3.
+   *
+   * When a V1 block is upgraded, its stored state `{ args, uiState }` is normalized
+   * to the internal default version. This method inserts a migration step from that
+   * internal version to the version specified in `.from()`, using the provided typed
+   * callback to transform the legacy shape. Non-legacy data passes through unchanged.
+   *
+   * Must be called right after `.from()` — not available after `.migrate()` calls.
+   * Any `.migrate()` steps added after `upgradeLegacy()` will run on the transformed result.
+   *
+   * Can only be called once — the returned chain has no upgradeLegacy() method.
+   * Mutually exclusive with recover().
+   *
+   * @typeParam Args - Type of the legacy block args
+   * @typeParam UiState - Type of the legacy block uiState
+   * @param fn - Typed transform from { args, uiState } to Current
+   * @returns Builder with migrate() and init() but without recover() or upgradeLegacy()
+   *
+   * @example
+   * type OldArgs = { inputFile: string; threshold: number };
+   * type OldUiState = { selectedTab: string };
+   * type BlockData = { inputFile: string; threshold: number; selectedTab: string };
+   *
+   * const dataModel = new DataModelBuilder()
+   *   .from<BlockData>("v1")
+   *   .upgradeLegacy<OldArgs, OldUiState>(({ args, uiState }) => ({
+   *     inputFile: args.inputFile,
+   *     threshold: args.threshold,
+   *     selectedTab: uiState.selectedTab,
+   *   }))
+   *   .init(() => ({ inputFile: '', threshold: 0, selectedTab: 'main' }));
+   */
+  upgradeLegacy<Args, UiState = unknown>(fn: (legacy: LegacyV1State<Args, UiState>) => Current): DataModelMigrationChainWithRecover<Current, Transfers>;
 }
 /**
  * Builder entry point for creating DataModel with type-safe migrations.
@@ -258,15 +301,15 @@ declare class DataModelInitialChain<Current> extends DataModelMigrationChain<Cur
  *   }))
  *   .init(() => ({ inputFile: '', selectedTab: 'main' }));
  */
-export declare class DataModelBuilder {
-    /**
-     * Start the migration chain with the given initial data type and version key.
-     *
-     * @typeParam T - Data type for the initial version
-     * @param initialVersion - Version key string (e.g. "v1")
-     * @returns Migration chain builder
-     */
-    from<T>(initialVersion: string): DataModelInitialChain<T>;
+declare class DataModelBuilder {
+  /**
+   * Start the migration chain with the given initial data type and version key.
+   *
+   * @typeParam T - Data type for the initial version
+   * @param initialVersion - Version key string (e.g. "v1")
+   * @returns Migration chain builder
+   */
+  from<T>(initialVersion: string): DataModelInitialChain<T>;
 }
 /**
  * DataModel defines the block's data structure, initial values, and migrations.
@@ -287,48 +330,59 @@ export declare class DataModelBuilder {
  *   .migrate<V3>("v3", (v2) => ({ ...v2, description: "" }))
  *   .init(() => ({ count: 0, label: "", description: "" }));
  */
-export declare class DataModel<State> {
-    /** Latest version key — O(1) access for the common "already current" check. */
-    private readonly latestVersion;
-    /** Maps each known version key to the index of the first step to run from it. O(1) lookup. */
-    private readonly stepsByFromVersion;
-    private readonly steps;
-    private readonly initialDataFn;
-    private readonly recoverFn;
-    private readonly recoverFromIndex;
-    private constructor();
-    /**
-     * Internal method for creating DataModel from builder.
-     * Uses Symbol key to prevent external access.
-     * @internal
-     */
-    static [FROM_BUILDER]<S>(state: BuilderState<S>): DataModel<S>;
-    /**
-     * The latest (current) version key in the migration chain.
-     */
-    get version(): DataVersionKey;
-    /**
-     * Get a fresh copy of the initial data.
-     */
-    initialData(): State;
-    /**
-     * Get initial data wrapped with current version.
-     * Used when creating new blocks or resetting to defaults.
-     */
-    getDefaultData(): DataVersioned<State>;
-    private recoverFrom;
-    /**
-     * Migrate versioned data from any version to the latest.
-     *
-     * - If version is in chain, applies needed migrations (O(1) lookup)
-     * - If version is unknown, attempts recovery; falls back to initial data
-     * - If a migration step fails, throws so the caller can preserve original data
-     *
-     * @param versioned - Data with version tag
-     * @returns Migrated data at the latest version
-     * @throws If a migration step from a known version fails
-     */
-    migrate(versioned: DataVersioned<unknown>): DataVersioned<State>;
+declare class DataModel<State, Transfers extends Record<string, unknown> = {}> {
+  /** @internal Phantom field to anchor the Transfers type parameter. */
+  readonly __transfers?: Transfers;
+  /** Latest version key — O(1) access for the common "already current" check. */
+  private readonly latestVersion;
+  /** Maps each known version key to the index of the first step to run from it. O(1) lookup. */
+  private readonly stepsByFromVersion;
+  private readonly steps;
+  private readonly transferSteps;
+  private readonly initialDataFn;
+  private readonly recoverFn;
+  private readonly recoverFromIndex;
+  private constructor();
+  /**
+   * Internal method for creating DataModel from builder.
+   * Uses Symbol key to prevent external access.
+   * @internal
+   */
+  static [FROM_BUILDER]<S, T extends Record<string, unknown> = {}>(state: BuilderState<S>): DataModel<S, T>;
+  /**
+   * The latest (current) version key in the migration chain.
+   */
+  get version(): DataVersionKey;
+  /**
+   * Get a fresh copy of the initial data.
+   */
+  initialData(): State;
+  /**
+   * Get initial data wrapped with current version.
+   * Used when creating new blocks or resetting to defaults.
+   */
+  getDefaultData(): DataVersioned<State>;
+  private recoverFrom;
+  /**
+   * Migrate versioned data from any version to the latest.
+   * Collects transfer extractions at their designated chain positions.
+   *
+   * - If version is in chain, applies needed migrations (O(1) lookup)
+   * - If version is unknown, attempts recovery; falls back to initial data
+   * - If a migration step fails, throws so the caller can preserve original data
+   *
+   * Transfers only fire during normal step-by-step migration:
+   * - Recovery path: returns empty transfers
+   * - Fast-path (already at latest): returns empty transfers
+   *
+   * @param versioned - Data with version tag
+   * @returns Migrated data at the latest version with transfer record
+   * @throws If a migration step from a known version fails
+   */
+  migrate(versioned: DataVersioned<unknown>): DataVersioned<State> & {
+    transfers: TransferRecord;
+  };
 }
-export {};
+//#endregion
+export { DataModel, DataModelBuilder, DataRecoverFn, DataVersioned, TransferRecord, TransferTarget };
 //# sourceMappingURL=block_migrations.d.ts.map