@nocobase/flow-engine 2.1.0-alpha.13 → 2.1.0-alpha.15

package/src/flowEngine.ts

@@ -27,7 +27,7 @@ import type {
   EnsureBatchResult,
   EventDefinition,
   FlowModelLoaderEntry,
-  FlowModelLoaderMap,
+  FlowModelLoaderInputMap,
   FlowModelLoaderResult,
   FlowModelOptions,
   IFlowModelRepository,
@@ -483,21 +483,31 @@ export class FlowEngine {
 
   /**
    * Register multiple model loader entries.
-   * @param {FlowModelLoaderMap} loaders Model loader entry map, key is model name, value is the model loader entry
+   * 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: FlowModelLoaderMap): void {
+  public registerModelLoaders(loaders: FlowModelLoaderInputMap): void {
     let changed = false;
-    for (const [name, entry] of Object.entries(loaders)) {
+    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;
     }
@@ -845,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.
@@ -1336,13 +1410,7 @@ export class FlowEngine {
       return hydrated;
     }
 
-    const shouldUseEnsure = !extra?.skipSave && !uid && !!parentId && !!subKey && options?.subType === 'object';
-    const data = shouldUseEnsure
-      ? (await this._modelRepository.ensure(options, {
-          includeAsyncNode: !!(options?.includeAsyncNode || options?.async),
-        })) ?? (await this._modelRepository.findOne(options))
-      : await this._modelRepository.findOne(options);
-
+    const data = await this._modelRepository.findOne(options);
     let model: T | null = null;
     if (data?.uid) {
       model = await this.createModelAsync<T>(data as any, extra);

package/src/locale/en-US.json

@@ -34,6 +34,7 @@
   "Failed to destroy model after creation error": "Failed to destroy model after creation error",
   "Failed to get action {{action}}": "Failed to get action {{action}}",
   "Failed to get configurable flows for model {{model}}": "Failed to get configurable flows for model {{model}}",
+  "Attributes are unavailable before selecting a record": "Attributes are unavailable before selecting a record",
   "Failed to import FormDialog": "Failed to import FormDialog",
   "Failed to import FormDialog or FormStep": "Failed to import FormDialog or FormStep",
   "Failed to import Formily components": "Failed to import Formily components",

package/src/locale/zh-CN.json

@@ -31,6 +31,7 @@
   "Failed to destroy model after creation error": "创建错误后销毁模型失败",
   "Failed to get action {{action}}": "获取 action '{{action}}' 失败",
   "Failed to get configurable flows for model {{model}}": "获取模型 '{{model}}' 的可配置 flows 失败",
+  "Attributes are unavailable before selecting a record": "选择记录之前，当前项属性不可用",
   "Failed to import FormDialog": "导入 FormDialog 失败",
   "Failed to import FormDialog or FormStep": "导入 FormDialog 或 FormStep 失败",
   "Failed to import Formily components": "导入 Formily 组件失败",

package/src/reactive/__tests__/observer.test.tsx

@@ -208,4 +208,86 @@ describe('observer', () => {
     expect(screen.getByText('Count: 0')).toBeInTheDocument();
     expect(screen.queryByText('Count: 1')).not.toBeInTheDocument();
   });
+
+  it('should flush pending update without TDZ error when context becomes active before timer callback runs', async () => {
+    vi.useFakeTimers();
+
+    try {
+      const model = observable({ count: 0 });
+      const pageActive = observable.ref(false);
+      const tabActive = observable.ref(true);
+
+      const context = {
+        pageActive,
+        tabActive,
+      };
+
+      (useFlowContext as any).mockReturnValue(context);
+
+      const Component = observer(() => <div>Count: {model.count}</div>);
+
+      render(<Component />);
+
+      expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+      act(() => {
+        model.count++;
+        pageActive.value = true;
+      });
+
+      await act(async () => {
+        await vi.runAllTimersAsync();
+      });
+
+      expect(screen.getByText('Count: 1')).toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('should cleanup pending timer and listener on unmount', async () => {
+    vi.useFakeTimers();
+
+    try {
+      const model = observable({ count: 0 });
+      const pageActive = observable.ref(false);
+      const tabActive = observable.ref(true);
+      const renderSpy = vi.fn();
+
+      const context = {
+        pageActive,
+        tabActive,
+      };
+
+      (useFlowContext as any).mockReturnValue(context);
+
+      const Component = observer(() => {
+        renderSpy(model.count);
+        return <div>Count: {model.count}</div>;
+      });
+
+      const { unmount } = render(<Component />);
+
+      expect(renderSpy).toHaveBeenCalledTimes(1);
+      expect(screen.getByText('Count: 0')).toBeInTheDocument();
+
+      act(() => {
+        model.count++;
+      });
+
+      unmount();
+
+      act(() => {
+        pageActive.value = true;
+      });
+
+      await act(async () => {
+        await vi.runAllTimersAsync();
+      });
+
+      expect(renderSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

package/src/reactive/observer.tsx

@@ -10,7 +10,7 @@
 import { observer as originalObserver, IObserverOptions, ReactFC } from '@formily/reactive-react';
 import React, { useMemo, useEffect, useRef } from 'react';
 import { useFlowContext } from '../FlowContextProvider';
-import { autorun } from '@formily/reactive';
+import { reaction } from '@formily/reactive';
 import { FlowEngineContext } from '..';
 
 type ObserverComponentProps<P, Options extends IObserverOptions> = Options extends {
@@ -30,12 +30,67 @@ export const observer = <P, Options extends IObserverOptions = IObserverOptions>
     const ctxRef = useRef(ctx);
     ctxRef.current = ctx;
 
-    // Store the pending disposer to avoid creating multiple listeners
+    // 保存延迟更新的监听器，避免重复创建监听。
     const pendingDisposerRef = useRef<(() => void) | null>(null);
+    // 保存延迟创建监听器的定时器，避免组件卸载后仍继续调度。
+    const pendingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-    // Cleanup on unmount
+    /**
+     * 清理挂起的可见性监听器。
+     *
+     * @example
+     * ```typescript
+     * clearPendingDisposer();
+     * ```
+     */
+    const clearPendingDisposer = () => {
+      if (pendingDisposerRef.current) {
+        pendingDisposerRef.current();
+        pendingDisposerRef.current = null;
+      }
+    };
+
+    /**
+     * 清理挂起的定时器。
+     *
+     * @example
+     * ```typescript
+     * clearPendingTimer();
+     * ```
+     */
+    const clearPendingTimer = () => {
+      if (pendingTimerRef.current) {
+        clearTimeout(pendingTimerRef.current);
+        pendingTimerRef.current = null;
+      }
+    };
+
+    /**
+     * 判断当前页面与标签页是否允许立即更新。
+     *
+     * @returns 当前上下文是否处于可更新状态。
+     * @example
+     * ```typescript
+     * if (isContextActive()) {
+     *   updater();
+     * }
+     * ```
+     */
+    const isContextActive = () => {
+      const pageActive = getPageActive(ctxRef.current);
+      const tabActive = ctxRef.current?.tabActive?.value;
+
+      return pageActive !== false && tabActive !== false;
+    };
+
+    // 组件卸载时统一清理所有挂起任务，避免异步回调在卸载后继续运行。
     useEffect(() => {
       return () => {
+        if (pendingTimerRef.current) {
+          clearTimeout(pendingTimerRef.current);
+          pendingTimerRef.current = null;
+        }
+
         if (pendingDisposerRef.current) {
           pendingDisposerRef.current();
           pendingDisposerRef.current = null;
@@ -47,38 +102,45 @@ export const observer = <P, Options extends IObserverOptions = IObserverOptions>
       () =>
         originalObserver(Component, {
           scheduler(updater) {
-            const pageActive = getPageActive(ctxRef.current);
-            const tabActive = ctxRef.current?.tabActive?.value;
+            if (!isContextActive()) {
+              if (pendingTimerRef.current || pendingDisposerRef.current) {
+                return;
+              }
+
+              // 通过异步任务打断同步调度，避免连续触发时形成递归更新。
+              pendingTimerRef.current = setTimeout(() => {
+                pendingTimerRef.current = null;
 
-            if (pageActive === false || tabActive === false) {
-              // Avoid stack overflow
-              setTimeout(() => {
-                // If there is already a pending updater, do nothing
                 if (pendingDisposerRef.current) {
                   return;
                 }
 
-                // Delay the update until the page and tab become active
-                const disposer = autorun(() => {
-                  if (
-                    ctxRef.current?.pageActive?.value &&
-                    (ctxRef.current?.tabActive?.value === true || ctxRef.current?.tabActive?.value === undefined)
-                  ) {
+                if (isContextActive()) {
+                  updater();
+                  return;
+                }
+
+                // 只监听组合后的“是否可更新”状态，条件恢复后执行一次并立即销毁。
+                pendingDisposerRef.current = reaction(
+                  () => isContextActive(),
+                  (active) => {
+                    if (!active) {
+                      return;
+                    }
+
+                    clearPendingDisposer();
                     updater();
-                    disposer?.();
-                    pendingDisposerRef.current = null;
-                  }
-                });
-                pendingDisposerRef.current = disposer;
+                  },
+                  {
+                    name: 'FlowObserverPendingUpdate',
+                  },
+                );
               });
               return;
             }
 
-            // If we are updating immediately, clear any pending disposer
-            if (pendingDisposerRef.current) {
-              pendingDisposerRef.current();
-              pendingDisposerRef.current = null;
-            }
+            clearPendingTimer();
+            clearPendingDisposer();
 
             updater();
           },

package/src/runjs-context/snippets/scene/detail/set-field-style.snippet.ts

@@ -11,18 +11,18 @@ import type { SnippetModule } from '../../types';
 const snippet: SnippetModule = {
   contexts: ['*'],
   scenes: ['detailFieldEvent', 'formFieldEvent'],
-  prefix: 'sn-field-style',
-  label: 'Set field style',
-  description: 'Customize form and detail field styles',
+  prefix: 'sn-item-style',
+  label: 'Set form item/details item style',
+  description: 'Customize form item and details item container styles',
   locales: {
     'zh-CN': {
-      label: '表单、详情字段样式设置',
-      description: '自定义表单字段和详情字段的样式',
+      label: '设置表单项/详情项样式',
+      description: '自定义表单项和详情项容器样式',
     },
   },
   content: `
-ctx.model.subModels.field.props.style = {
-  fontWeight: 900,
+ctx.model.props.style = {
+  background: 'red',
 };
 `,
 };

package/src/runjs-context/snippets/scene/table/set-cell-style.snippet.ts

@@ -24,7 +24,7 @@ const snippet: SnippetModule = {
 ctx.model.props.onCell = (record, rowIndex) => {
   return {
     style: {
-      fontWeight: 900,
+      background: 'red',
     },
   };
 };

package/src/types.ts

@@ -407,22 +407,34 @@ export type FlowModelLoaderResult =
 export type FlowModelLoader = () => Promise<FlowModelLoaderResult>;
 
 /**
- * FlowModel loader entry.
- * Future contribution-style fields are intentionally kept as commented placeholders in phase A
- * and are not consumed by current runtime logic.
+ * FlowModel loader entry (normalized internal form).
  */
 export interface FlowModelLoaderEntry {
   loader: FlowModelLoader;
-  // extends?: string;
+  extends?: string[];
   // meta?: Partial<FlowModelMeta>;
   // scenes?: string[];
 }
 
 /**
- * FlowModel loader entry map.
+ * FlowModel loader input (user-facing form for registerModelLoaders).
+ * The `extends` field accepts flexible formats that will be normalized to `string[]` at registration time.
+ */
+export interface FlowModelLoaderInput {
+  loader: FlowModelLoader;
+  extends?: string | ModelConstructor | (string | ModelConstructor)[];
+}
+
+/**
+ * FlowModel loader entry map (normalized internal form).
  */
 export type FlowModelLoaderMap = Record<string, FlowModelLoaderEntry>;
 
+/**
+ * FlowModel loader input map (user-facing form for registerModelLoaders).
+ */
+export type FlowModelLoaderInputMap = Record<string, FlowModelLoaderInput>;
+
 /**
  * Batch ensure result.
  */
@@ -437,17 +449,6 @@ export interface EnsureBatchResult {
 
 export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
   findOne(query: Record<string, any>): Promise<Record<string, any> | null>;
-  /**
-   * Ensure a model exists (create if missing) in a single request.
-   */
-  ensure: (
-    values: Record<string, any>,
-    options?: { includeAsyncNode?: boolean },
-  ) => Promise<Record<string, any> | null>;
-  /**
-   * Optional: run multiple ops in a single transaction (server capability).
-   */
-  mutate?: (values: Record<string, any>, options?: { includeAsyncNode?: boolean }) => Promise<Record<string, any>>;
   save(model: T, options?: { onlyStepParams?: boolean }): Promise<Record<string, any>>;
   destroy(uid: string): Promise<boolean>;
   move(sourceId: string, targetId: string, position: 'before' | 'after'): Promise<void>;