@nocobase/flow-engine 2.0.0-alpha.63 → 2.0.0-alpha.65

package/src/models/__tests__/dispatchEvent.when.test.ts

@@ -0,0 +1,356 @@
+/**
+ * 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 { describe, test, expect } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { FlowModel } from '../flowModel';
+
+describe('dispatchEvent dynamic event flow phase (scheduleModelOperation integration)', () => {
+  test('default (phase undefined): instance flows run before static flows', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['dynamic', 'static-a']);
+  });
+
+  test("phase='afterAllFlows': instance flow runs after static flows", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go', phase: 'afterAllFlows' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['static-a', 'dynamic']);
+  });
+
+  test("phase='beforeFlow': instance flow runs before the target static flow", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+        b: { handler: async () => void calls.push('static-b') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go', phase: 'beforeFlow', flowKey: 'S' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['dynamic', 'static-a', 'static-b']);
+  });
+
+  test("phase='afterFlow': instance flow runs after the target static flow", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+        b: { handler: async () => void calls.push('static-b') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go', phase: 'afterFlow', flowKey: 'S' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['static-a', 'static-b', 'dynamic']);
+  });
+
+  test("phase='beforeStep': instance flow runs before the target static step", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+        b: { handler: async () => void calls.push('static-b') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go', phase: 'beforeStep', flowKey: 'S', stepKey: 'a' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['dynamic', 'static-a', 'static-b']);
+  });
+
+  test("phase='afterStep': instance flow runs after the target static step", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+        b: { handler: async () => void calls.push('static-b') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go', phase: 'afterStep', flowKey: 'S', stepKey: 'a' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['static-a', 'dynamic', 'static-b']);
+  });
+
+  test("phase='beforeFlow' missing flow: falls back to afterAllFlows", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go', phase: 'beforeFlow', flowKey: 'missing' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['static-a', 'dynamic']);
+  });
+
+  test("phase='beforeStep' missing step: falls back to afterAllFlows", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D', {
+      on: { eventName: 'go', phase: 'beforeStep', flowKey: 'S', stepKey: 'missing' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['static-a', 'dynamic']);
+  });
+
+  test('multiple flows on same anchor: executes by flow.sort asc (stable)', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    model.registerFlow('D5', {
+      sort: 5,
+      on: { eventName: 'go', phase: 'beforeStep', flowKey: 'S', stepKey: 'a' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic-5') } as any,
+      },
+    });
+    model.registerFlow('D0', {
+      sort: 0,
+      on: { eventName: 'go', phase: 'beforeStep', flowKey: 'S', stepKey: 'a' },
+      steps: {
+        d: { handler: async () => void calls.push('dynamic-0') } as any,
+      },
+    });
+
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['dynamic-0', 'dynamic-5', 'static-a']);
+  });
+});
+
+describe('dispatchEvent static flow phase (scheduleModelOperation integration)', () => {
+  test("phase='beforeFlow': static flow runs before the target static flow", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+      },
+    });
+
+    M.registerFlow({
+      key: 'P',
+      on: { eventName: 'go', phase: 'beforeFlow', flowKey: 'S' },
+      steps: {
+        p: { handler: async () => void calls.push('phase') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['phase', 'static-a']);
+  });
+
+  test("phase='afterStep': static flow runs after the target static step", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+        b: { handler: async () => void calls.push('static-b') } as any,
+      },
+    });
+
+    M.registerFlow({
+      key: 'P',
+      on: { eventName: 'go', phase: 'afterStep', flowKey: 'S', stepKey: 'a' },
+      steps: {
+        p: { handler: async () => void calls.push('phase') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['static-a', 'phase', 'static-b']);
+  });
+
+  test("phase='afterAllFlows': static flow runs after static flows", async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      steps: {
+        a: { handler: async () => void calls.push('static-a') } as any,
+      },
+    });
+
+    M.registerFlow({
+      key: 'P',
+      on: { eventName: 'go', phase: 'afterAllFlows' },
+      steps: {
+        p: { handler: async () => void calls.push('phase') } as any,
+      },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+    await model.dispatchEvent('go');
+    expect(calls).toEqual(['static-a', 'phase']);
+  });
+});

package/src/models/__tests__/flowModel.test.ts

@@ -1558,6 +1558,22 @@ describe('FlowModel', () => {
         expect(model.forks.size).toBe(1);
       });
 
+      test('should recreate cached fork after dispose to avoid state leakage', () => {
+        const fork1 = model.createFork({ foo: 'bar' }, 'cacheKey');
+        fork1.hidden = true;
+        fork1.setProps({ disabled: true });
+
+        fork1.dispose();
+
+        expect(model.getFork('cacheKey')).toBeUndefined();
+
+        const fork2 = model.createFork({}, 'cacheKey');
+
+        expect(fork2).not.toBe(fork1);
+        expect(fork2.hidden).toBe(false);
+        expect(fork2.localProps).toEqual({});
+      });
+
       test('should create different instances for different keys', () => {
         const fork1 = model.createFork({}, 'key1');
         const fork2 = model.createFork({}, 'key2');

package/src/provider.tsx

@@ -90,9 +90,10 @@ export const useFlowEngine = ({ throwError = true } = {}): FlowEngine => {
   if (!context && throwError) {
     // This error should ideally not be hit if FlowEngineProvider is used correctly at the root
     // and always supplied with an engine.
-    throw new Error(
+    console.warn(
       'useFlowEngine must be used within a FlowEngineProvider, and FlowEngineProvider must be supplied with an engine.',
     );
+    return;
   }
   return context;
 };

package/src/scheduler/ModelOperationScheduler.ts

@@ -36,6 +36,8 @@ export interface LifecycleEvent {
   error?: any;
   inputArgs?: Record<string, any>;
   result?: any;
+  flowKey?: string;
+  stepKey?: string;
 }
 
 type ScheduledItem = {
@@ -162,37 +164,37 @@ export class ModelOperationScheduler {
     const emitter = this.engine.emitter;
     if (!emitter || typeof emitter.on !== 'function') return;
 
-    const onCreated = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'created' });
+    const onCreated = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'created' });
     };
     emitter.on('model:created', onCreated);
     this.unbindHandlers.push(() => emitter.off('model:created', onCreated));
 
-    const onMounted = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'mounted' });
+    const onMounted = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'mounted' });
     };
     emitter.on('model:mounted', onMounted);
     this.unbindHandlers.push(() => emitter.off('model:mounted', onMounted));
 
-    const onGenericBeforeStart = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:start' });
+    const onGenericBeforeStart = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:start' });
     };
     emitter.on('model:event:beforeRender:start', onGenericBeforeStart);
     this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:start', onGenericBeforeStart));
 
-    const onGenericBeforeEnd = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:end' });
+    const onGenericBeforeEnd = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'event:beforeRender:end' });
     };
     emitter.on('model:event:beforeRender:end', onGenericBeforeEnd);
     this.unbindHandlers.push(() => emitter.off('model:event:beforeRender:end', onGenericBeforeEnd));
 
-    const onUnmounted = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: 'unmounted' });
+    const onUnmounted = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: 'unmounted' });
     };
     emitter.on('model:unmounted', onUnmounted);
     this.unbindHandlers.push(() => emitter.off('model:unmounted', onUnmounted));
 
-    const onDestroyed = (e: LifecycleEvent) => {
+    const onDestroyed = async (e: LifecycleEvent) => {
       const targetBucket = this.itemsByTargetUid.get(e.uid);
       const event = { ...e, type: 'destroyed' as const };
       if (targetBucket && targetBucket.size) {
@@ -201,7 +203,7 @@ export class ModelOperationScheduler {
           const it = this.itemsById.get(id);
           if (!it) continue;
           if (this.shouldTrigger(it.options.when, event)) {
-            void this.tryExecuteOnce(id, event);
+            await this.tryExecuteOnce(id, event);
           } else {
             this.internalCancel(id);
           }
@@ -220,14 +222,14 @@ export class ModelOperationScheduler {
     if (this.subscribedEventNames.has(name)) return;
     this.subscribedEventNames.add(name);
     const emitter = this.engine.emitter;
-    const onStart = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` as const });
+    const onStart = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` as LifecycleType });
     };
-    const onEnd = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` as const });
+    const onEnd = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` as LifecycleType });
     };
-    const onError = (e: LifecycleEvent) => {
-      this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` as const });
+    const onError = async (e: LifecycleEvent) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` as LifecycleType });
     };
     emitter.on(`model:event:${name}:start`, onStart);
     emitter.on(`model:event:${name}:end`, onEnd);
@@ -239,12 +241,12 @@ export class ModelOperationScheduler {
 
   private parseEventWhen(when?: ScheduleWhen): { name: string; phase: 'start' | 'end' | 'error' } | null {
     if (!when || typeof when !== 'string') return null;
-    const m = /^event:([^:]+):(start|end|error)$/.exec(when);
+    const m = /^event:(.+):(start|end|error)$/.exec(when);
     if (!m) return null;
     return { name: m[1], phase: m[2] as 'start' | 'end' | 'error' };
   }
 
-  private processLifecycleEvent(targetUid: string, event: LifecycleEvent) {
+  private async processLifecycleEvent(targetUid: string, event: LifecycleEvent) {
     const targetBucket = this.itemsByTargetUid.get(targetUid);
     if (!targetBucket || targetBucket.size === 0) return;
     const ids = Array.from(targetBucket.keys());
@@ -253,7 +255,7 @@ export class ModelOperationScheduler {
       if (!item) continue;
       const should = this.shouldTrigger(item.options.when, event);
       if (!should) continue;
-      void this.tryExecuteOnce(id, event);
+      await this.tryExecuteOnce(id, event);
     }
   }
 

package/src/types.ts

@@ -213,12 +213,37 @@ export type FlowEventName =
   // fallback to any string for extensibility
   | (string & {});
 
+/**
+ * 事件流的执行时机（phase）。
+ *
+ * 说明：
+ * - 缺省（phase 未配置）表示保持现有行为；
+ * - 当配置了 phase 时，运行时会将其映射为 `scheduleModelOperation` 的 `when` 锚点；
+ * - phase 同时适用于动态事件流（实例级）与静态流（内置）。
+ */
+export type FlowEventPhase =
+  | 'beforeAllFlows'
+  | 'afterAllFlows'
+  | 'beforeFlow'
+  | 'afterFlow'
+  | 'beforeStep'
+  | 'afterStep';
+
 /**
  * Flow 事件类型（供 FlowDefinitionOptions.on 使用）。
  */
 export type FlowEvent<TModel extends FlowModel = FlowModel> =
   | FlowEventName
-  | { eventName: FlowEventName; defaultParams?: Record<string, any> };
+  | {
+      eventName: FlowEventName;
+      defaultParams?: Record<string, any>;
+      /** 动态事件流的执行时机（默认 beforeAllFlows） */
+      phase?: FlowEventPhase;
+      /** phase 为 beforeFlow/afterFlow/beforeStep/afterStep 时使用 */
+      flowKey?: string;
+      /** phase 为 beforeStep/afterStep 时使用 */
+      stepKey?: string;
+    };
 
 /**
  * 事件分发选项。

package/src/views/useDialog.tsx

@@ -164,9 +164,9 @@ export function useDialog() {
             className="nb-dialog-overflow-hidden"
             ref={dialogRef}
             hidden={config.inputArgs?.hidden?.value}
-            {...config}
             footer={currentFooter}
             header={currentHeader}
+            {...config}
             onCancel={() => {
               currentDialog.close(config.result);
             }}