@nocobase/flow-engine 2.1.0-alpha.3 → 2.1.0-alpha.30

package/lib/flowEngine.d.ts

@@ -8,7 +8,7 @@ import { FlowResource } from './resources';
 import { Emitter } from './emitter';
 import ModelOperationScheduler from './scheduler/ModelOperationScheduler';
 import type { ScheduleOptions, ScheduledCancel } from './scheduler/ModelOperationScheduler';
-import type { ActionDefinition, ApplyFlowCacheEntry, CreateModelOptions, EventDefinition, FlowModelOptions, IFlowModelRepository, ModelConstructor, PersistOptions, ResourceType } from './types';
+import type { ActionDefinition, ApplyFlowCacheEntry, CreateModelOptions, EnsureBatchResult, EventDefinition, FlowModelLoaderInputMap, FlowModelOptions, IFlowModelRepository, ModelConstructor, PersistOptions, ResourceType } from './types';
 /**
  * FlowEngine is the core class of the flow engine, responsible for managing flow models, actions, model repository, and more.
  * It provides capabilities for registering, creating, finding, persisting, replacing, and moving models.
@@ -47,6 +47,28 @@ export declare class FlowEngine {
      * @private
      */
     private _modelClasses;
+    /**
+     * Registered model entries.
+     * Key is the model class name, value is the model loader entry.
+     * @private
+     */
+    private _modelLoaders;
+    /**
+     * In-flight model loading promises.
+     * Key is the model class name, value is the loading promise.
+     * @private
+     */
+    private _loadingModelPromises;
+    /**
+     * Whether model-loader preload has completed in this session.
+     * @private
+     */
+    private _modelLoadersPreloaded;
+    /**
+     * In-flight model-loader preload promise.
+     * @private
+     */
+    private _modelLoadersPreloadPromise?;
     /**
      * Created model instances.
      * Key is the model instance UID, value is the model instance object.
@@ -83,6 +105,12 @@ export declare class FlowEngine {
      */
     private _previousEngine?;
     private _nextEngine?;
+    /**
+     * 视图销毁回调。由 useDrawer / useDialog 在创建弹窗视图时注册，
+     * 供外部（如 afterSuccess）通过引擎栈遍历来关闭多层弹窗。
+     * embed 视图（usePage）不注册此回调，因此 destroyView() 会自然跳过。
+     */
+    private _destroyView?;
     private _resources;
     /**
      * Data change registry used to coordinate "refresh on active" across view-scoped engines.
@@ -151,6 +179,18 @@ export declare class FlowEngine {
      * 将当前引擎从栈中移除并修复相邻指针（用于视图关闭时）。
      */
     unlinkFromStack(): void;
+    /**
+     * 注册视图销毁回调（由 useDrawer / useDialog 调用）。
+     */
+    setDestroyView(fn: () => void): void;
+    /**
+     * 关闭当前引擎关联的弹窗视图。
+     * 路由触发的弹窗会先 navigation.back() 清理 URL，再 destroy() 移除元素；
+     * 非路由弹窗直接 destroy()。
+     * embed 视图不注册回调，调用时返回 false 自动跳过。
+     * @returns 是否成功执行
+     */
+    destroyView(): boolean;
     /**
      * Get the flow engine context object.
      * @returns {FlowEngineContext} Flow engine context
@@ -208,6 +248,10 @@ export declare class FlowEngine {
      * Get all registered global events.
      */
     getEvents<TModel extends FlowModel = FlowModel>(): Map<string, EventDefinition<TModel>>;
+    /**
+     * for proxy instance, the #registerModel can't be called.
+     */
+    private _registerModel;
     /**
      * Register multiple model classes.
      * @param {Record<string, ModelConstructor>} models Model class map, key is model name, value is model constructor
@@ -216,6 +260,102 @@ export declare class FlowEngine {
      * flowEngine.registerModels({ UserModel, OrderModel });
      */
     registerModels(models: Record<string, ModelConstructor | typeof FlowModel<any>>): void;
+    /**
+     * Register multiple model loader entries.
+     * The `extends` field declares parent class(es) for async subclass discovery via `getSubclassesOfAsync`.
+     * It accepts `string | ModelConstructor | (string | ModelConstructor)[]` and is normalized to `string[]` internally.
+     * @param {FlowModelLoaderInputMap} loaders Model loader input map
+     * @returns {void}
+     * @example
+     * flowEngine.registerModelLoaders({
+     *   DemoModel: {
+     *     extends: 'BaseModel',
+     *     loader: () => import('./models/DemoModel'),
+     *   },
+     * });
+     */
+    registerModelLoaders(loaders: FlowModelLoaderInputMap): void;
+    /**
+     * Get a registered model class (constructor) asynchronously.
+     * This will first ensure the model loader entry is resolved.
+     * @param {string} name Model class name
+     * @returns {Promise<ModelConstructor | undefined>} Model constructor, or undefined if not found
+     */
+    getModelClassAsync(name: string): Promise<ModelConstructor | undefined>;
+    /**
+     * Get all registered model classes asynchronously.
+     * This will first ensure all registered model loader entries are resolved.
+     * @returns {Promise<Map<string, ModelConstructor>>} Model class map
+     */
+    getModelClassesAsync(): Promise<Map<string, ModelConstructor>>;
+    /**
+     * Create and register a model instance asynchronously.
+     * This will first ensure all string-based model references in the model tree are resolved.
+     * @template T FlowModel subclass type, defaults to FlowModel.
+     * @param {CreateModelOptions} options Model creation options
+     * @returns {Promise<T>} Created model instance
+     */
+    createModelAsync<T extends FlowModel = FlowModel>(options: CreateModelOptions, extra?: {
+        delegateToParent?: boolean;
+        delegate?: FlowContext;
+    }): Promise<T>;
+    /**
+     * Normalize a loader result into a model constructor.
+     * @param {string} name Model class name
+     * @param {FlowModelLoaderResult} loaded Loader result
+     * @returns {ModelConstructor | null} Normalized model constructor
+     * @private
+     */
+    private normalizeModelLoaderResult;
+    /**
+     * Collect string-based model names from a model tree.
+     * @param {unknown} data Model tree data
+     * @param {Set<string>} names Model name set
+     * @private
+     */
+    private collectModelNamesFromTree;
+    /**
+     * Collect additional model names from object-form meta.createModelOptions defaults.
+     * @param {ModelConstructor} modelClass Model class constructor
+     * @param {Set<string>} names Model name set
+     * @private
+     */
+    private collectModelNamesFromMetaDefaults;
+    /**
+     * Ensure a single model class is available.
+     * @param {string} name Model class name
+     * @returns {Promise<ModelConstructor | null>} Model constructor or null when resolution fails
+     * @private
+     */
+    private ensureModel;
+    /**
+     * Ensure multiple model classes are available.
+     * @param {string[]} names Model class names
+     * @returns {Promise<EnsureBatchResult>} Batch ensure result
+     * @private
+     */
+    private ensureModels;
+    /**
+     * Resolve all unresolved string-based model references in a model tree before synchronous creation begins.
+     *
+     * Use this when you already have a model tree object, such as repository-returned data or resolved
+     * `createModelOptions`, and you need to ensure every string `use` in that tree has been loaded and
+     * registered into `_modelClasses` before calling `createModel()`.
+     *
+     * @param {unknown} data Model tree data
+     * @returns {Promise<EnsureBatchResult>} Batch ensure result
+     */
+    resolveModelTree(data: unknown): Promise<EnsureBatchResult>;
+    /**
+     * Preload all currently registered unresolved model loaders.
+     *
+     * This method is intended for flow-settings/discovery style entry points that need registered model
+     * classes to exist before UI is rendered, without requiring callers to know which specific models
+     * will be touched next.
+     *
+     * @returns {Promise<EnsureBatchResult>} Batch ensure result
+     */
+    preloadModelLoaders(): Promise<EnsureBatchResult>;
     registerResources(resources: Record<string, any>): void;
     createResource<T = FlowResource>(resourceType: ResourceType<T>, options?: {
         context?: FlowContext;
@@ -244,6 +384,15 @@ export declare class FlowEngine {
      * @returns {Map<string, ModelConstructor>} Model classes inherited from base class and passed the filter
      */
     getSubclassesOf(baseClass: string | ModelConstructor, filter?: (ModelClass: ModelConstructor, className: string) => boolean): Map<string, ModelConstructor>;
+    /**
+     * Asynchronously get all subclasses of a base class, including those registered via model loaders.
+     * Merges results from already-loaded classes (_modelClasses) and async loader entries with matching `extends` declarations.
+     * Loader-resolved classes are validated with `isInheritedFrom`; mismatches are warned and excluded.
+     * @param {string | ModelConstructor} baseClass Base class name or constructor
+     * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+     * @returns {Promise<Map<string, ModelConstructor>>} Model classes that are subclasses of the base class
+     */
+    getSubclassesOfAsync(baseClass: string | ModelConstructor, filter?: (ModelClass: ModelConstructor, className: string) => boolean): Promise<Map<string, ModelConstructor>>;
     /**
      * Create and register a model instance.
      * If an instance with the same UID exists, returns the existing instance.
@@ -333,6 +482,7 @@ export declare class FlowEngine {
      * @returns {Promise<T | null>} Model instance or null
      */
     loadOrCreateModel<T extends FlowModel = FlowModel>(options: any, extra?: {
+        skipSave?: boolean;
         delegateToParent?: boolean;
         delegate?: FlowContext;
     }): Promise<T | null>;