@nocobase/flow-engine 2.1.0-beta.15 → 2.1.0-beta.17

package/src/flowEngine.ts

@@ -24,7 +24,11 @@ import type {
   ActionDefinition,
   ApplyFlowCacheEntry,
   CreateModelOptions,
+  EnsureBatchResult,
   EventDefinition,
+  FlowModelLoaderEntry,
+  FlowModelLoaderInputMap,
+  FlowModelLoaderResult,
   FlowModelOptions,
   IFlowModelRepository,
   ModelConstructor,
@@ -75,6 +79,32 @@ export class FlowEngine {
    */
   private _modelClasses: Map<string, ModelConstructor> = observable.shallow(new Map());
 
+  /**
+   * Registered model entries.
+   * Key is the model class name, value is the model loader entry.
+   * @private
+   */
+  private _modelLoaders: Map<string, FlowModelLoaderEntry> = new Map();
+
+  /**
+   * In-flight model loading promises.
+   * Key is the model class name, value is the loading promise.
+   * @private
+   */
+  private _loadingModelPromises: Map<string, Promise<ModelConstructor | null>> = new Map();
+
+  /**
+   * Whether model-loader preload has completed in this session.
+   * @private
+   */
+  private _modelLoadersPreloaded = false;
+
+  /**
+   * In-flight model-loader preload promise.
+   * @private
+   */
+  private _modelLoadersPreloadPromise?: Promise<EnsureBatchResult>;
+
   /**
    * Created model instances.
    * Key is the model instance UID, value is the model instance object.
@@ -424,6 +454,13 @@ export class FlowEngine {
    * @private
    */
   #registerModel(name: string, modelClass: ModelConstructor): void {
+    return this._registerModel(name, modelClass);
+  }
+
+  /**
+   * for proxy instance, the #registerModel can't be called.
+   */
+  private _registerModel(name: string, modelClass: ModelConstructor): void {
     if (this._modelClasses.has(name)) {
       console.warn(`FlowEngine: Model class with name '${name}' is already registered and will be overwritten.`);
     }
@@ -444,6 +481,306 @@ export class FlowEngine {
     }
   }
 
+  /**
+   * 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'),
+   *   },
+   * });
+   */
+  public registerModelLoaders(loaders: FlowModelLoaderInputMap): void {
+    let changed = false;
+    for (const [name, input] of Object.entries(loaders)) {
+      if (this._modelLoaders.has(name)) {
+        console.warn(`FlowEngine: Model loader with name '${name}' is already registered and will be overwritten.`);
+      }
+      const entry: FlowModelLoaderEntry = {
+        loader: input.loader,
+      };
+      if (input.extends != null) {
+        const raw = Array.isArray(input.extends) ? input.extends : [input.extends];
+        entry.extends = raw.map((item) => (typeof item === 'string' ? item : item.name));
+      }
+      this._modelLoaders.set(name, entry);
+      changed = true;
+    }
+    if (changed) {
+      this._modelLoadersPreloaded = false;
+      this._modelLoadersPreloadPromise = undefined;
+    }
+  }
+
+  /**
+   * 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
+   */
+  public async getModelClassAsync(name: string): Promise<ModelConstructor | undefined> {
+    await this.ensureModel(name);
+    return this.getModelClass(name);
+  }
+
+  /**
+   * 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
+   */
+  public async getModelClassesAsync(): Promise<Map<string, ModelConstructor>> {
+    await this.ensureModels(Array.from(this._modelLoaders.keys()));
+    return this.getModelClasses();
+  }
+
+  /**
+   * 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
+   */
+  public async createModelAsync<T extends FlowModel = FlowModel>(
+    options: CreateModelOptions,
+    extra?: { delegateToParent?: boolean; delegate?: FlowContext },
+  ): Promise<T> {
+    await this.resolveModelTree(options);
+    return this.createModel<T>(options, extra);
+  }
+
+  /**
+   * 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(name: string, loaded: FlowModelLoaderResult): ModelConstructor | null {
+    if (typeof loaded === 'function') {
+      return loaded as ModelConstructor;
+    }
+    if (loaded && typeof loaded === 'object') {
+      const defaultExport = loaded.default;
+      if (typeof defaultExport === 'function') {
+        return defaultExport as ModelConstructor;
+      }
+      const namedExport = loaded[name];
+      if (typeof namedExport === 'function') {
+        return namedExport as ModelConstructor;
+      }
+    }
+    console.warn(`FlowEngine: model loader for '${name}' did not resolve to a valid model constructor.`);
+    return null;
+  }
+
+  /**
+   * 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(data: unknown, names: Set<string>): void {
+    if (!data || typeof data !== 'object') {
+      return;
+    }
+    if (Array.isArray(data)) {
+      data.forEach((item) => this.collectModelNamesFromTree(item, names));
+      return;
+    }
+
+    const tree = data as Record<string, any>;
+    if (typeof tree.use === 'string') {
+      names.add(tree.use);
+    }
+
+    const subModels = tree.subModels;
+    if (!subModels || typeof subModels !== 'object') {
+      return;
+    }
+
+    Object.values(subModels).forEach((value) => {
+      this.collectModelNamesFromTree(value, names);
+    });
+  }
+
+  /**
+   * 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(modelClass: ModelConstructor, names: Set<string>): void {
+    const metaCreate = (modelClass as typeof FlowModel).meta?.createModelOptions;
+    if (metaCreate && typeof metaCreate === 'object') {
+      this.collectModelNamesFromTree(metaCreate, names);
+    }
+  }
+
+  /**
+   * 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 async ensureModel(name: string): Promise<ModelConstructor | null> {
+    const existing = this._modelClasses.get(name);
+    if (existing) {
+      return existing;
+    }
+
+    const inflight = this._loadingModelPromises.get(name);
+    if (inflight) {
+      return inflight;
+    }
+
+    const entry = this._modelLoaders.get(name);
+    if (!entry) {
+      console.warn(`FlowEngine: Model entry '${name}' not found. Falling back to ErrorFlowModel when needed.`);
+      return null;
+    }
+
+    const promise = (async () => {
+      try {
+        const loaded = await entry.loader();
+        const modelClass = this.normalizeModelLoaderResult(name, loaded);
+        if (!modelClass) {
+          return null;
+        }
+        // 这里拿到的 this 是 Proxy(FlowEngine) 而不是原始的 FlowEngine，无法直接调用 #registerModel
+        this._registerModel(name, modelClass);
+        return modelClass;
+      } catch (error) {
+        console.warn(`FlowEngine: Failed to load model '${name}'. Falling back to ErrorFlowModel when needed.`, error);
+        return null;
+      } finally {
+        this._loadingModelPromises.delete(name);
+      }
+    })();
+
+    this._loadingModelPromises.set(name, promise);
+    return promise;
+  }
+
+  /**
+   * Ensure multiple model classes are available.
+   * @param {string[]} names Model class names
+   * @returns {Promise<EnsureBatchResult>} Batch ensure result
+   * @private
+   */
+  private async ensureModels(names: string[]): Promise<EnsureBatchResult> {
+    const requested = Array.from(new Set(names.filter((name): name is string => !!name)));
+    const loaded: string[] = [];
+    const failed: EnsureBatchResult['failed'] = [];
+
+    const results = await Promise.all(
+      requested.map(async (name) => {
+        const modelClass = await this.ensureModel(name);
+        return { name, modelClass };
+      }),
+    );
+
+    results.forEach(({ name, modelClass }) => {
+      if (modelClass) {
+        loaded.push(name);
+      } else {
+        failed.push({ name });
+      }
+    });
+
+    return { requested, loaded, failed };
+  }
+
+  /**
+   * 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
+   */
+  public async resolveModelTree(data: unknown): Promise<EnsureBatchResult> {
+    const requested = new Set<string>();
+    const loaded = new Set<string>();
+    const failed = new Map<string, { name: string; error?: unknown }>();
+    const processed = new Set<string>();
+    const pending = new Set<string>();
+
+    this.collectModelNamesFromTree(data, pending);
+
+    while (pending.size > 0) {
+      const batch = Array.from(pending).filter((name) => !processed.has(name));
+      pending.clear();
+      if (batch.length === 0) {
+        break;
+      }
+
+      batch.forEach((name) => requested.add(name));
+      const result = await this.ensureModels(batch);
+
+      result.loaded.forEach((name) => {
+        processed.add(name);
+        loaded.add(name);
+        const modelClass = this.getModelClass(name);
+        if (modelClass) {
+          const discovered = new Set<string>();
+          this.collectModelNamesFromMetaDefaults(modelClass, discovered);
+          discovered.forEach((discoveredName) => {
+            if (!processed.has(discoveredName)) {
+              pending.add(discoveredName);
+            }
+          });
+        }
+      });
+
+      result.failed.forEach((item) => {
+        processed.add(item.name);
+        failed.set(item.name, item);
+      });
+    }
+
+    return {
+      requested: Array.from(requested),
+      loaded: Array.from(loaded),
+      failed: Array.from(failed.values()),
+    };
+  }
+
+  /**
+   * 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
+   */
+  public async preloadModelLoaders(): Promise<EnsureBatchResult> {
+    const unresolved = Array.from(this._modelLoaders.keys()).filter((name) => !this._modelClasses.has(name));
+    if (unresolved.length === 0) {
+      this._modelLoadersPreloaded = true;
+      return { requested: [], loaded: [], failed: [] };
+    }
+    if (this._modelLoadersPreloadPromise) {
+      return this._modelLoadersPreloadPromise;
+    }
+
+    this._modelLoadersPreloadPromise = (async () => {
+      const result = await this.ensureModels(unresolved);
+      this._modelLoadersPreloaded = result.failed.length === 0;
+      this._modelLoadersPreloadPromise = undefined;
+      return result;
+    })();
+
+    return this._modelLoadersPreloadPromise;
+  }
+
   registerResources(resources: Record<string, any>) {
     for (const [name, resourceClass] of Object.entries(resources)) {
       this._resources.set(name, resourceClass);
@@ -518,6 +855,70 @@ export class FlowEngine {
     return result;
   }
 
+  /**
+   * 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
+   */
+  public async getSubclassesOfAsync(
+    baseClass: string | ModelConstructor,
+    filter?: (ModelClass: ModelConstructor, className: string) => boolean,
+  ): Promise<Map<string, ModelConstructor>> {
+    const baseClassName = typeof baseClass === 'string' ? baseClass : baseClass.name;
+
+    // If baseClass is a string and not yet loaded, try to resolve it first
+    let parentModelClass: ModelConstructor | undefined;
+    if (typeof baseClass === 'string') {
+      if (!this.getModelClass(baseClass)) {
+        await this.ensureModel(baseClass);
+      }
+      parentModelClass = this.getModelClass(baseClass);
+    } else {
+      parentModelClass = baseClass;
+    }
+
+    if (!parentModelClass) {
+      return new Map();
+    }
+
+    // Step 1: Collect already-loaded subclasses from _modelClasses
+    const result = this.getSubclassesOf(parentModelClass, filter);
+
+    // Step 2: Find unloaded loaders whose extends includes baseClassName
+    const loaderCandidates: string[] = [];
+    for (const [name, entry] of this._modelLoaders) {
+      if (result.has(name) || this._modelClasses.has(name)) continue;
+      if (entry.extends?.includes(baseClassName)) {
+        loaderCandidates.push(name);
+      }
+    }
+
+    // Step 3: Resolve all matching loaders
+    if (loaderCandidates.length > 0) {
+      await this.ensureModels(loaderCandidates);
+    }
+
+    // Step 4: Validate resolved classes and add to result
+    for (const name of loaderCandidates) {
+      const ModelClass = this._modelClasses.get(name);
+      if (!ModelClass) continue;
+      if (!isInheritedFrom(ModelClass, parentModelClass)) {
+        console.warn(
+          `FlowEngine: Model '${name}' declares extends '${baseClassName}' but does not actually inherit from it. Skipping.`,
+        );
+        continue;
+      }
+      if (!filter || filter(ModelClass, name)) {
+        result.set(name, ModelClass);
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Create and register a model instance.
    * If an instance with the same UID exists, returns the existing instance.
@@ -865,10 +1266,10 @@ export class FlowEngine {
    * Hydrate a model into current engine from an already-existing model instance in previous engines.
    * - Avoids repository requests when the model tree is already present in memory.
    */
-  private hydrateModelFromPreviousEngines<T extends FlowModel = FlowModel>(
+  private async hydrateModelFromPreviousEngines<T extends FlowModel = FlowModel>(
     options: any,
     extra?: { delegateToParent?: boolean; delegate?: FlowContext },
-  ): T | null {
+  ): Promise<T | null> {
     const uid = options?.uid;
     const parentId = options?.parentId;
     const subKey = options?.subKey;
@@ -882,7 +1283,7 @@ export class FlowEngine {
       }
       if (existing) {
         const data = existing.serialize();
-        return this.createModel<T>(data as any, extra);
+        return this.createModelAsync<T>(data as any, extra);
       }
     }
 
@@ -897,11 +1298,11 @@ export class FlowEngine {
       if (!localParent) {
         const parentData = parentFromPrev.serialize();
         delete (parentData as any).subModels;
-        localParent = this.createModel<FlowModel>(parentData as any, extra);
+        localParent = await this.createModelAsync<FlowModel>(parentData as any, extra);
       }
       // Create (or reuse) the sub-model instance in current engine.
       const modelData = modelFromPrev.serialize();
-      const localModel = this.createModel<T>(modelData as any, extra);
+      const localModel = await this.createModelAsync<T>(modelData as any, extra);
 
       // Mount under local parent if not mounted yet (so later lookups by parentId/subKey won't hit repo).
       const mounted = (localParent.subModels as any)?.[subKey];
@@ -942,20 +1343,21 @@ export class FlowEngine {
       if (model) {
         return model as T;
       }
-      const hydrated = this.hydrateModelFromPreviousEngines<T>(options);
+      const hydrated = await this.hydrateModelFromPreviousEngines<T>(options);
       if (hydrated) {
         return hydrated as T;
       }
     }
     const data = await this._modelRepository.findOne(options);
     if (!data?.uid) return null;
+    await this.resolveModelTree(data);
     if (refresh) {
       const existing = this.getModel(data.uid);
       if (existing) {
         this.removeModelWithSubModels(existing.uid);
       }
     }
-    return this.createModel<T>(data as any);
+    return this.createModelAsync<T>(data as any);
   }
 
   /**
@@ -1003,7 +1405,7 @@ export class FlowEngine {
       return m;
     }
 
-    const hydrated = this.hydrateModelFromPreviousEngines<T>(options, extra);
+    const hydrated = await this.hydrateModelFromPreviousEngines<T>(options, extra);
     if (hydrated) {
       return hydrated;
     }
@@ -1011,9 +1413,9 @@ export class FlowEngine {
     const data = await this._modelRepository.findOne(options);
     let model: T | null = null;
     if (data?.uid) {
-      model = this.createModel<T>(data as any, extra);
+      model = await this.createModelAsync<T>(data as any, extra);
     } else {
-      model = this.createModel<T>(options, extra);
+      model = await this.createModelAsync<T>(options, extra);
       if (!extra?.skipSave) {
         await model.save();
       }

package/src/flowSettings.ts

@@ -35,6 +35,7 @@ import {
 import { FlowExitAllException } from './utils/exceptions';
 import { FlowStepContext } from './hooks/useFlowStep';
 import { GLOBAL_EMBED_CONTAINER_ID, EMBED_REPLACING_DATA_KEY } from './views';
+import { lazy } from './lazy-helper';
 
 const Panel = Collapse.Panel;
 
@@ -114,16 +115,23 @@ export interface FlowSettingsOpenOptions {
   onSaved?: () => void | Promise<void>;
 }
 
+export type FlowSettingsComponent = React.ComponentType<any>;
+export type FlowSettingsComponentModule = { default?: FlowSettingsComponent } | Record<string, FlowSettingsComponent>;
+export type FlowSettingsComponentLoader = () => Promise<FlowSettingsComponentModule | FlowSettingsComponent>;
+export type FlowSettingsComponentLoaderMap = Record<string, FlowSettingsComponentLoader>;
+
 export class FlowSettings {
   public components: Record<string, any> = {};
   public scopes: Record<string, any> = {};
   private antdComponentsLoaded = false;
   public enabled: boolean;
+  private engine: FlowEngine;
   #forceEnabled = false; // 强制启用状态，主要用于设计模式下的强制启用
   public toolbarItems: ToolbarItemConfig[] = [];
   #emitter: Emitter = new Emitter();
 
   constructor(engine: FlowEngine) {
+    this.engine = engine;
     // 初始默认为 false，由 SchemaComponentProvider 根据实际设计模式状态同步设置
     this.enabled = false;
     engine.context.defineProperty('flowSettingsEnabled', {
@@ -291,6 +299,30 @@ export class FlowSettings {
     });
   }
 
+  public registerComponentLoaders(loaders: FlowSettingsComponentLoaderMap): void {
+    Object.entries(loaders).forEach(([name, loader]) => {
+      if (this.components[name]) {
+        console.warn(`FlowSettings: Component with name '${name}' is already registered and will be overwritten.`);
+      }
+      this.components[name] = lazy(async () => {
+        const loaded = await loader();
+        if (typeof loaded === 'function') {
+          return { default: loaded };
+        }
+        if (loaded?.default && typeof loaded.default === 'function') {
+          return { default: loaded.default };
+        }
+        const namedComponent = loaded?.[name];
+        if (typeof namedComponent === 'function') {
+          return { default: namedComponent };
+        }
+        throw new Error(
+          `FlowSettings: component loader for '${name}' must resolve to a React component or a module exporting it.`,
+        );
+      });
+    });
+  }
+
   /**
    * 添加作用域到 FlowSettings 的作用域注册表中。
    * 这些作用域可以在 flow step 的 uiSchema 中使用。
@@ -311,13 +343,15 @@ export class FlowSettings {
   /**
    * 启用流程设置组件的显示
    * @example
-   * flowSettings.enable();
+   * await flowSettings.enable();
    */
-  public enable(): void {
+  public async enable(): Promise<void> {
+    await this.engine.preloadModelLoaders();
     this.enabled = true;
   }
 
-  public forceEnable() {
+  public async forceEnable(): Promise<void> {
+    await this.engine.preloadModelLoaders();
     this.#forceEnabled = true;
     this.enabled = true;
   }
@@ -325,16 +359,16 @@ export class FlowSettings {
   /**
    * 禁用流程设置组件的显示
    * @example
-   * flowSettings.disable();
+   * await flowSettings.disable();
    */
-  public disable(): void {
+  public async disable(): Promise<void> {
     if (this.#forceEnabled) {
       return;
     }
     this.enabled = false;
   }
 
-  public forceDisable() {
+  public async forceDisable(): Promise<void> {
     this.#forceEnabled = false;
     this.enabled = false;
   }

package/src/lazy-helper.tsx

@@ -0,0 +1,57 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import React, { lazy as reactLazy } from 'react';
+
+type LazyComponentType<M extends Record<string, any>, K extends keyof M> = {
+  [P in K]: M[P];
+};
+
+export function lazy<M extends Record<'default', any>>(factory: () => Promise<M>): M['default'];
+
+export function lazy<M extends Record<string, any>, K extends keyof M = keyof M>(
+  factory: () => Promise<M>,
+  ...componentNames: K[]
+): LazyComponentType<M, K>;
+
+export function lazy<M extends Record<string, any>, K extends keyof M>(
+  factory: () => Promise<M>,
+  ...componentNames: K[]
+) {
+  if (componentNames.length === 0) {
+    const LazyComponent = reactLazy(() =>
+      factory().then((module) => ({
+        default: module.default,
+      })),
+    );
+    const Component = (props) => (
+      <React.Suspense fallback={null}>
+        <LazyComponent {...props} />
+      </React.Suspense>
+    );
+    return Component;
+  }
+
+  return componentNames.reduce(
+    (acc, name) => {
+      const LazyComponent = reactLazy(() =>
+        factory().then((module) => ({
+          default: module[name],
+        })),
+      );
+      acc[name] = ((props) => (
+        <React.Suspense fallback={null}>
+          <LazyComponent {...props} />
+        </React.Suspense>
+      )) as M[K];
+      return acc;
+    },
+    {} as LazyComponentType<M, K>,
+  );
+}