@platforma-sdk/model 1.58.5 → 1.58.11

package/dist/plugin_model.d.ts

@@ -1,87 +1,246 @@
+import { PluginFactoryLike } from "./plugin_handle.js";
+import { DataModel, DataRecoverFn, DataVersioned, TransferTarget } from "./block_migrations.js";
+import { PluginName } from "./block_storage.js";
+import { PluginRenderCtx } from "./render/api.js";
+import "./render/index.js";
+import { BlockCodeKnownFeatureFlags } from "@milaboratories/pl-model-common";
+
+//#region src/plugin_model.d.ts
+/** Symbol for internal builder creation method */
+declare const FROM_BUILDER: unique symbol;
+/** Symbol for internal plugin model creation — not accessible to external consumers */
+declare const CREATE_PLUGIN_MODEL: unique symbol;
+type PluginData = Record<string, unknown>;
+type PluginParams = undefined | Record<string, unknown>;
+type PluginOutputs = Record<string, unknown>;
+type PluginConfig = undefined | Record<string, unknown>;
 /**
- * PluginModel - Builder for creating plugin types with data model and outputs.
+ * Plugin data model with typed migration chain and config-aware initialization.
  *
- * Plugins are UI components with their own model logic and persistent state.
- * Block developers register plugin instances via BlockModelV3.plugin() method.
+ * @typeParam Data - Current (latest) plugin data type
+ * @typeParam Versions - Map of version keys to their data types (accumulated by the chain)
+ * @typeParam Config - Config type passed to init function (undefined if none)
+ */
+declare class PluginDataModel<Data extends PluginData, Versions extends Record<string, unknown> = {}, Config = undefined> {
+  readonly dataModel: DataModel<Data>;
+  private readonly configInitFn;
+  /** @internal Phantom field to anchor the Versions type parameter. */
+  readonly __versions?: Versions;
+  private constructor();
+  /** @internal */
+  static [FROM_BUILDER]<Data extends PluginData, Versions extends Record<string, unknown>, Config>(dataModel: DataModel<Data>, configInitFn: (config?: Config) => Data): PluginDataModel<Data, Versions, Config>;
+  /** Create fresh data with optional config. */
+  getDefaultData(config?: Config): DataVersioned<Data>;
+}
+/** Internal state for plugin data model chain. */
+type PluginChainState = {
+  initialVersion: string;
+  migrations: Array<{
+    toVersion: string;
+    fn: (data: unknown) => unknown;
+  }>;
+  recoverFn?: (version: string, data: unknown) => unknown;
+  recoverAtIndex?: number;
+};
+/**
+ * Builder for creating PluginDataModel with type-safe migrations.
+ * Mirrors DataModelBuilder — same .from(), .migrate(), .recover(), .init() chain.
  *
- * @module plugin_model
+ * @example
+ * const pluginData = new PluginDataModelBuilder()
+ *   .from<TableData>("v1")
+ *   .migrate<FilteredTableData>("v2", (v1) => ({ ...v1, filters: [] }))
+ *   .init<TableConfig>((config?) => ({
+ *     state: createDefaultState(config?.ops),
+ *     filters: [],
+ *   }));
  */
-import type { BlockCodeKnownFeatureFlags } from "@milaboratories/pl-model-common";
-import type { DataModel } from "./block_migrations";
-import type { PluginName } from "./block_storage";
-import type { PluginFactoryLike } from "./plugin_handle";
-import type { PluginRenderCtx } from "./render";
-/** Symbol for internal builder creation method */
-declare const FROM_BUILDER: unique symbol;
-export type PluginData = Record<string, unknown>;
-export type PluginParams = undefined | Record<string, unknown>;
-export type PluginOutputs = Record<string, unknown>;
-export type PluginConfig = undefined | Record<string, unknown>;
+declare class PluginDataModelBuilder {
+  from<Data extends PluginData, const V extends string>(version: V): PluginDataModelInitialChain<Data, Record<V, Data>>;
+}
+/**
+ * Chain returned by .migrate(). Supports .migrate(), .recover(), .init().
+ * No .upgradeLegacy() — that is only available on the initial chain.
+ */
+declare class PluginDataModelChain<Data extends PluginData, Versions extends Record<string, unknown>> {
+  protected readonly state: PluginChainState;
+  protected constructor(state: PluginChainState);
+  /** @internal */
+  static [FROM_BUILDER]<Data extends PluginData, Versions extends Record<string, unknown>>(state: PluginChainState): PluginDataModelChain<Data, Versions>;
+  /**
+   * Add a migration step transforming data from the current version to the next.
+   */
+  migrate<Next extends PluginData, const NextV extends string>(version: NextV, fn: (current: Data) => Next): PluginDataModelChain<Next, Versions & Record<NextV, Next>>;
+  /**
+   * Set a recovery handler for unknown or legacy versions.
+   * Can only be called once — the returned chain has no recover() method.
+   */
+  recover(fn: DataRecoverFn<Data>): PluginDataModelWithRecover<Data, Versions>;
+  /** Finalize the PluginDataModel. */
+  init<Config = undefined>(fn: (config?: Config) => Data): PluginDataModel<Data, Versions, Config>;
+}
 /**
- * Configured plugin instance returned by PluginModelFactory.create().
+ * Initial chain returned by new PluginDataModelBuilder().from().
+ * Extends PluginDataModelChain with .upgradeLegacy() — available only before
+ * any .migrate() calls, matching the block's DataModelInitialChain pattern.
+ */
+declare class PluginDataModelInitialChain<Data extends PluginData, Versions extends Record<string, unknown>> extends PluginDataModelChain<Data, Versions> {
+  /** @internal */
+  static [FROM_BUILDER]<Data extends PluginData, Versions extends Record<string, unknown>>(state: PluginChainState): PluginDataModelInitialChain<Data, Versions>;
+  /**
+   * Handle data from a previous plugin type occupying this slot.
+   * Prepends a migration from DATA_MODEL_LEGACY_VERSION to the initial version.
+   * When a plugin type changes, the old data arrives with DATA_MODEL_LEGACY_VERSION —
+   * this function transforms it into the initial version, then the normal chain runs.
+   *
+   * Must be called right after .from() — not available after .migrate().
+   * Mutually exclusive with recover().
+   *
+   * @param fn - Transform from old plugin's raw data to this plugin's initial data type
+   */
+  upgradeLegacy(fn: (data: unknown) => Data): PluginDataModelWithRecover<Data, Versions>;
+}
+/**
+ * Chain after .recover() — supports .migrate(), .init(). No second recover().
+ */
+declare class PluginDataModelWithRecover<Data extends PluginData, Versions extends Record<string, unknown>> {
+  private readonly state;
+  private constructor();
+  /** @internal */
+  static [FROM_BUILDER]<Data extends PluginData, Versions extends Record<string, unknown>>(state: PluginChainState): PluginDataModelWithRecover<Data, Versions>;
+  migrate<Next extends PluginData, const NextV extends string>(version: NextV, fn: (current: Data) => Next): PluginDataModelWithRecover<Next, Versions & Record<NextV, Next>>;
+  init<Config = undefined>(fn: (config?: Config) => Data): PluginDataModel<Data, Versions, Config>;
+}
+/**
+ * A named plugin instance created by `factory.create({ pluginId, ... })`.
+ * Passed to both `.transfer()` (on migration chain) and `.plugin()` (on BlockModelV3).
+ * Implements TransferTarget so the migration chain can accept it.
+ *
+ * @typeParam Id - Plugin instance ID literal type
+ * @typeParam Data - Plugin data type
+ * @typeParam Params - Plugin params type
+ * @typeParam Outputs - Plugin outputs type
+ * @typeParam TransferData - Type of data entering the plugin via transfer (never if no transfer)
+ */
+declare class PluginInstance<Id extends string = string, Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs, TransferData = never> implements TransferTarget<Id, TransferData> {
+  readonly id: Id;
+  readonly transferVersion: string;
+  /** @internal */
+  readonly __transferBrand?: TransferData;
+  private readonly factory;
+  private readonly config;
+  private constructor();
+  /** @internal */
+  static [FROM_BUILDER]<Id extends string, Data extends PluginData, Params extends PluginParams, Outputs extends PluginOutputs, TransferData>(id: Id, factory: PluginModelFactory<Data, Params, Outputs, any, any>, transferVersion: string, config?: any): PluginInstance<Id, Data, Params, Outputs, TransferData>;
+  /** @internal Create a PluginModel from this instance. Used by BlockModelV3.plugin(). */
+  [CREATE_PLUGIN_MODEL](): PluginModel<Data, Params, Outputs>;
+}
+/**
+ * Configured plugin instance returned by PluginModelFactory[CREATE_PLUGIN_MODEL]().
  * Contains the plugin's name, data model, and output definitions.
  */
-export declare class PluginModel<Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs> {
-    /** Globally unique plugin name */
-    readonly name: PluginName;
-    /** Data model instance for this plugin */
-    readonly dataModel: DataModel<Data>;
-    /** Output definitions - functions that compute outputs from plugin context */
-    readonly outputs: {
-        [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
-    };
-    /** Feature flags declared by this plugin */
-    readonly featureFlags?: BlockCodeKnownFeatureFlags;
-    private constructor();
-    /**
-     * Internal method for creating PluginModel from factory.
-     * Uses Symbol key to prevent external access.
-     * @internal
-     */
-    static [FROM_BUILDER]<Data extends PluginData, Params extends PluginParams, Outputs extends PluginOutputs>(options: {
-        name: PluginName;
-        dataModel: DataModel<Data>;
-        outputs: {
-            [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
-        };
-        featureFlags?: BlockCodeKnownFeatureFlags;
-    }): PluginModel<Data, Params, Outputs>;
-    /**
-     * Creates a new PluginModelBuilder for building plugin definitions.
-     *
-     * @param options.name - Globally unique plugin name
-     * @param options.data - Factory function that creates the data model from config
-     * @returns PluginModelBuilder for chaining output definitions
-     *
-     * @example
-     * const dataModelChain = new DataModelBuilder().from<MyData>("v1");
-     *
-     * const myPlugin = PluginModel.define({
-     *   name: 'myPlugin' as PluginName,
-     *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),
-     * })
-     *   .output('computed', (ctx) => ctx.data.value * ctx.params.multiplier)
-     *   .build();
-     */
-    static define<Data extends PluginData, Params extends PluginParams, Config extends PluginConfig>(options: {
-        name: PluginName;
-        data: (config?: Config) => DataModel<Data>;
-        featureFlags?: BlockCodeKnownFeatureFlags;
-    }): PluginModelBuilder<Data, Params, {}, Config>;
+declare class PluginModel<Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs> {
+  /** Globally unique plugin name */
+  readonly name: PluginName;
+  /** Data model instance for this plugin */
+  readonly dataModel: DataModel<Data>;
+  /** Output definitions - functions that compute outputs from plugin context */
+  readonly outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K] };
+  /** Feature flags declared by this plugin */
+  readonly featureFlags?: BlockCodeKnownFeatureFlags;
+  /** Create fresh default data. Config (if any) is captured at creation time. */
+  readonly getDefaultData: () => DataVersioned<Data>;
+  private constructor();
+  /**
+   * Internal method for creating PluginModel from factory.
+   * Uses Symbol key to prevent external access.
+   * @internal
+   */
+  static [FROM_BUILDER]<Data extends PluginData, Params extends PluginParams, Outputs extends PluginOutputs>(options: {
+    name: PluginName;
+    dataModel: DataModel<Data>;
+    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K] };
+    featureFlags?: BlockCodeKnownFeatureFlags;
+    getDefaultData: () => DataVersioned<Data>;
+  }): PluginModel<Data, Params, Outputs>;
+  /**
+   * Creates a new PluginModelBuilder with a PluginDataModel (supports transfer / config).
+   *
+   * @example
+   * const pluginData = new PluginDataModelBuilder().from<TableData>("v1")
+   *   .migrate<FilteredTableData>("v2", (v1) => ({ ...v1, filters: [] }))
+   *   .init<TableConfig>((config?) => ({
+   *     state: createDefaultState(config?.ops),
+   *     filters: [],
+   *   }));
+   *
+   * const myPlugin = PluginModel.define({
+   *   name: 'myPlugin' as PluginName,
+   *   data: pluginData,
+   * }).build();
+   */
+  static define<Data extends PluginData, Params extends PluginParams = undefined, Versions extends Record<string, unknown> = {}, Config extends PluginConfig = undefined>(options: {
+    name: PluginName;
+    data: PluginDataModel<Data, Versions, Config>;
+    featureFlags?: BlockCodeKnownFeatureFlags;
+  }): PluginModelBuilder<Data, Params, {}, Config, Versions>;
+  /**
+   * Creates a new PluginModelBuilder with a data model factory function (backward compatible).
+   *
+   * @example
+   * const myPlugin = PluginModel.define({
+   *   name: 'myPlugin' as PluginName,
+   *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),
+   * }).build();
+   */
+  static define<Data extends PluginData, Params extends PluginParams = undefined, Config extends PluginConfig = undefined>(options: {
+    name: PluginName;
+    data: (config?: Config) => DataModel<Data>;
+    featureFlags?: BlockCodeKnownFeatureFlags;
+  }): PluginModelBuilder<Data, Params, {}, Config, {}>;
 }
 /** Plugin factory returned by PluginModelBuilder.build(). */
-export interface PluginFactory<Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs, Config extends PluginConfig = undefined> extends PluginFactoryLike {
-    create(config?: Config): PluginModel<Data, Params, Outputs>;
-    /**
-     * @internal Phantom field for structural type extraction.
-     * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike.
-     */
-    readonly __types?: {
-        data: Data;
-        params: Params;
-        outputs: Outputs;
-        config: Config;
-    };
+interface PluginFactory<Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs, Config extends PluginConfig = undefined, Versions extends Record<string, unknown> = {}> extends PluginFactoryLike<Data, Params, Outputs> {
+  /** Create a named plugin instance, optionally with transfer at a specific version. */
+  create<const Id extends string, const V extends string & keyof Versions = never>(options: {
+    pluginId: Id;
+    transferAt?: V;
+    config?: Config;
+  }): PluginInstance<Id, Data, Params, Outputs, Versions[V]>;
+  /**
+   * @internal Phantom field for structural type extraction.
+   * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike.
+   */
+  readonly __types?: {
+    data: Data;
+    params: Params;
+    outputs: Outputs;
+    config: Config;
+    versions: Versions;
+  };
+}
+declare class PluginModelFactory<Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs, Config extends PluginConfig = undefined, Versions extends Record<string, unknown> = {}> implements PluginFactory<Data, Params, Outputs, Config, Versions> {
+  private readonly name;
+  private readonly dataFn;
+  private readonly getDefaultDataFn?;
+  readonly outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K] };
+  private readonly featureFlags?;
+  private constructor();
+  /** @internal */
+  static [FROM_BUILDER]<Data extends PluginData, Params extends PluginParams, Outputs extends PluginOutputs, Config extends PluginConfig, Versions extends Record<string, unknown>>(options: {
+    name: PluginName;
+    dataFn: (config?: Config) => DataModel<Data>;
+    getDefaultDataFn?: (config?: Config) => DataVersioned<Data>;
+    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K] };
+    featureFlags?: BlockCodeKnownFeatureFlags;
+  }): PluginModelFactory<Data, Params, Outputs, Config, Versions>;
+  create<const Id extends string, const V extends string & keyof Versions = never>(options: {
+    pluginId: Id;
+    transferAt?: V;
+    config?: Config;
+  }): PluginInstance<Id, Data, Params, Outputs, Versions[V]>;
+  /** @internal Create a PluginModel from config. Config is captured in getDefaultData closure. */
+  [CREATE_PLUGIN_MODEL](config?: Config): PluginModel<Data, Params, Outputs>;
 }
 /**
  * Builder for creating PluginType with type-safe output definitions.
@@ -92,66 +251,58 @@ export interface PluginFactory<Data extends PluginData = PluginData, Params exte
  * @typeParam Params - Params derived from block's RenderCtx (optional)
  * @typeParam Config - Static configuration passed to plugin factory (optional)
  * @typeParam Outputs - Accumulated output types
+ * @typeParam Versions - Version map from PluginDataModel (empty for function-based data)
  *
  * @example
- * const dataModelChain = new DataModelBuilder().from<TableData>("v1");
- *
- * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({
+ * const dataTable = PluginModel.define({
  *     name: 'dataTable' as PluginName,
- *     data: (cfg) => {
- *       return dataModelChain.init(() => ({ state: createInitialState(cfg.ops) }));
- *     },
+ *     data: pluginDataModel,
  *   })
  *   .output('model', (ctx) => createTableModel(ctx))
  *   .build();
  */
-declare class PluginModelBuilder<Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs, Config extends PluginConfig = undefined> {
-    private readonly name;
-    private readonly data;
-    private readonly outputs;
-    private readonly featureFlags?;
-    private constructor();
-    /**
-     * Internal method for creating PluginModelBuilder.
-     * Uses Symbol key to prevent external access.
-     * @internal
-     */
-    static [FROM_BUILDER]<Data extends PluginData, Params extends PluginParams, Outputs extends PluginOutputs, Config extends PluginConfig>(options: {
-        name: PluginName;
-        data: (config?: Config) => DataModel<Data>;
-        outputs?: {
-            [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
-        };
-        featureFlags?: BlockCodeKnownFeatureFlags;
-    }): PluginModelBuilder<Data, Params, Outputs, Config>;
-    /**
-     * Adds an output to the plugin.
-     *
-     * @param key - Output name
-     * @param fn - Function that computes the output value from plugin context
-     * @returns PluginModel with the new output added
-     *
-     * @example
-     * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))
-     * .output('isReady', (ctx) => ctx.params.columns !== undefined)
-     */
-    output<const Key extends string, T>(key: Key, fn: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => T): PluginModelBuilder<Data, Params, Outputs & {
-        [K in Key]: T;
-    }, Config>;
-    /**
-     * Finalizes the plugin definition and returns a ConfigurablePluginModel.
-     *
-     * @returns Callable plugin factory that accepts config and returns PluginModel
-     *
-     * @example
-     * const myPlugin = new PluginModelBuilder('myPlugin', () => dataModel)
-     *   .output('value', (ctx) => ctx.data.value)
-     *   .build();
-     *
-     * // Later, call create() with config to get a configured instance:
-     * const configured = myPlugin.create({ defaultValue: 'test' });
-     */
-    build(): PluginFactory<Data, Params, Outputs, Config>;
+declare class PluginModelBuilder<Data extends PluginData = PluginData, Params extends PluginParams = undefined, Outputs extends PluginOutputs = PluginOutputs, Config extends PluginConfig = undefined, Versions extends Record<string, unknown> = {}> {
+  private readonly name;
+  private readonly dataFn;
+  private readonly getDefaultDataFn?;
+  private readonly outputs;
+  private readonly featureFlags?;
+  private constructor();
+  /** @internal */
+  static [FROM_BUILDER]<Data extends PluginData, Params extends PluginParams, Outputs extends PluginOutputs, Config extends PluginConfig, Versions extends Record<string, unknown> = {}>(options: {
+    name: PluginName;
+    dataFn: (config?: Config) => DataModel<Data>;
+    getDefaultDataFn?: (config?: Config) => DataVersioned<Data>;
+    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K] };
+    featureFlags?: BlockCodeKnownFeatureFlags;
+  }): PluginModelBuilder<Data, Params, Outputs, Config, Versions>;
+  /**
+   * Adds an output to the plugin.
+   *
+   * @param key - Output name
+   * @param fn - Function that computes the output value from plugin context
+   * @returns PluginModel with the new output added
+   *
+   * @example
+   * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))
+   * .output('isReady', (ctx) => ctx.params.columns !== undefined)
+   */
+  output<const Key extends string, T>(key: Key, fn: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => T): PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config, Versions>;
+  /**
+   * Finalizes the plugin definition and returns a PluginFactory.
+   *
+   * @returns Plugin factory that creates named plugin instances via .create()
+   *
+   * @example
+   * const myPlugin = PluginModel.define({ ... })
+   *   .output('value', (ctx) => ctx.data.value)
+   *   .build();
+   *
+   * // Create a named instance:
+   * const table = myPlugin.create({ pluginId: 'mainTable', config: { ... } });
+   */
+  build(): PluginFactory<Data, Params, Outputs, Config, Versions>;
 }
-export {};
+//#endregion
+export { PluginConfig, PluginData, PluginDataModel, PluginDataModelBuilder, PluginFactory, PluginInstance, PluginModel, PluginOutputs, PluginParams };
 //# sourceMappingURL=plugin_model.d.ts.map