@nocobase/flow-engine 2.0.0-alpha.7 → 2.0.0-alpha.71

package/src/executor/__tests__/ctx-defs-injection.test.ts

@@ -0,0 +1,197 @@
+/**
+ * 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, it, expect, vi, beforeEach } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { FlowModel } from '../../models';
+import type { FlowDefinitionOptions, FlowModelOptions } from '../../types';
+
+describe('defineProperties/defineMethods injection', () => {
+  let engine: FlowEngine;
+
+  beforeEach(() => {
+    engine = new FlowEngine();
+    vi.restoreAllMocks();
+    vi.clearAllMocks();
+  });
+
+  it('engine.context.runAction applies defs before defaultParams and handler', async () => {
+    const handler = vi.fn((_ctx, params) => params);
+    engine.registerActions({
+      test: {
+        name: 'test',
+        defineProperties: { foo: { value: 5 } },
+        defineMethods: { add: (x: number) => x + 1 },
+        defaultParams: (ctx) => ({ a: (ctx as any).foo, b: (ctx as any).add(2) }),
+        handler,
+      },
+    });
+
+    const result = await (engine.context as any).runAction('test');
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({ a: 5, b: 3 });
+  });
+
+  it('model.context.runAction applies defs before defaultParams and handler', async () => {
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+    const h = vi.fn((_ctx, params) => ({ ...params, y: (_ctx as any).mul(3) }));
+    M.registerAction({
+      name: 'mAction',
+      defineProperties: async () => ({ al: { value: 7 } }),
+      defineMethods: async () => ({ mul: (x: number) => x * 2 }),
+      defaultParams: (ctx) => ({ a: (ctx as any).al }),
+      handler: h,
+    });
+    const m = engine.createModel<M>({ use: 'M' });
+    const res = await (m.context as any).runAction('mAction', { x: 3 });
+    expect(h).toHaveBeenCalledTimes(1);
+    expect(res).toEqual({ a: 7, x: 3, y: 6 });
+  });
+
+  function createModelWithFlows(uid: string, flows: Record<string, Omit<FlowDefinitionOptions, 'key'>>) {
+    const model = new FlowModel({
+      uid,
+      flowEngine: engine,
+      stepParams: {},
+      subModels: {},
+      flowRegistry: flows,
+    } as FlowModelOptions);
+    return model;
+  }
+
+  it('FlowExecutor: action-based step injects defs before defaultParams/handler', async () => {
+    const stepHandler = vi.fn((_ctx, params) => params);
+    engine.registerActions({
+      act: {
+        name: 'act',
+        defineProperties: { base: { value: 10 } },
+        defineMethods: { inc: (x: number) => x + 1 },
+        handler: stepHandler,
+      },
+    });
+
+    const flows = {
+      f: {
+        steps: {
+          s: {
+            use: 'act',
+            defaultParams: (ctx) => ({ p: (ctx as any).base, q: (ctx as any).inc(4) }),
+          },
+        },
+      },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const m = createModelWithFlows('m1', flows);
+    const res = await engine.executor.runFlow(m, 'f');
+    expect(stepHandler).toHaveBeenCalledTimes(1);
+    const [, received] = stepHandler.mock.calls[0];
+    expect(received).toEqual({ p: 10, q: 5 });
+    expect(res.s).toEqual({ p: 10, q: 5 });
+  });
+
+  it('FlowExecutor: inline step injects defs before defaultParams/handler', async () => {
+    const stepHandler = vi.fn((_ctx, params) => ({ ...params, v: (_ctx as any).twice(5) }));
+    const flows = {
+      f: {
+        steps: {
+          s: {
+            defineProperties: { k: { value: 8 } },
+            defineMethods: { twice: (x: number) => 2 * x },
+            defaultParams: (ctx) => ({ m: (ctx as any).k }),
+            handler: stepHandler,
+          },
+        },
+      },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const m = createModelWithFlows('m2', flows);
+    const res = await engine.executor.runFlow(m, 'f');
+    expect(stepHandler).toHaveBeenCalledTimes(1);
+    const [, received] = stepHandler.mock.calls[0];
+    // params 仅包含 defaultParams 合并后的值；v 是 handler 计算的返回值
+    expect(received).toEqual({ m: 8 });
+    expect(res.s).toEqual({ m: 8, v: 10 });
+  });
+
+  it('FlowExecutor: step defs are isolated per step', async () => {
+    const flows = {
+      f: {
+        steps: {
+          a: {
+            defineMethods: { only: (x: number) => x + 1 },
+            handler: (_ctx, _params) => ({ ok: true }),
+          },
+          b: {
+            // 这里期望无法访问到上一步注入的方法，从而抛出错误
+            defaultParams: (ctx) => ({ v: (ctx as any).only(1) }),
+            handler: (_ctx, params) => params,
+          },
+        },
+      },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+    const m = createModelWithFlows('m-isolation', flows);
+    const res = await engine.executor.runFlow(m, 'f');
+    // a 正常执行，b 无法访问到 a 注入的方法，defaultParams 出错被 resolveDefaultParams 捕获后为空对象
+    expect(res).toEqual({ a: { ok: true }, b: {} });
+  });
+
+  it('FlowExecutor: step defs override action defs when same key', async () => {
+    const stepHandler = vi.fn((_ctx, params) => params);
+    engine.registerActions({
+      act: {
+        name: 'act',
+        defineProperties: { foo: { value: 1 } },
+        defineMethods: { id: (x: number) => x },
+        handler: stepHandler,
+      },
+    });
+    const flows = {
+      f: {
+        steps: {
+          s: {
+            use: 'act',
+            defineProperties: { foo: { value: 2 } },
+            defineMethods: { id: (x: number) => x + 100 },
+            defaultParams: (ctx) => ({ a: (ctx as any).foo, b: (ctx as any).id(1) }),
+          },
+        },
+      },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+    const m = createModelWithFlows('m3', flows);
+    await engine.executor.runFlow(m, 'f');
+    const [, received] = stepHandler.mock.calls[0];
+    expect(received).toEqual({ a: 2, b: 101 });
+  });
+
+  it('FlowExecutor: subsequent defineProperty/defineMethod write to parent context (not scoped)', async () => {
+    const flows = {
+      f: {
+        steps: {
+          a: {
+            handler: (ctx) => {
+              (ctx as any).defineProperty('mark', { value: 7 });
+              (ctx as any).defineMethod('inc', (x: number) => x + 1);
+              return { ok: true };
+            },
+          },
+          b: {
+            // 无注入，直接读取上一步通过 defineProperty/defineMethod 挂在到父级的能力
+            defaultParams: (ctx) => ({ v: (ctx as any).mark, w: (ctx as any).inc(2) }),
+            handler: (_ctx, params) => params,
+          },
+        },
+      },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const m = engine.createModel<FlowModel>({ use: FlowModel.name, flowRegistry: flows });
+    const res = await engine.executor.runFlow(m, 'f');
+    expect(res).toEqual({ a: { ok: true }, b: { v: 7, w: 3 } });
+  });
+});

package/src/executor/__tests__/flowExecutor.test.ts

@@ -81,7 +81,7 @@ describe('FlowExecutor', () => {
     expect(result.step2).toBe('step2-ok');
   });
 
-  it('runAutoFlows executes only auto flows in sort order and caches result', async () => {
+  it("dispatchEvent('beforeRender') executes flows in sort order and caches result (when options specify)", async () => {
     const calls: string[] = [];
     const mkFlow = (key: string, sort: number) => ({
       sort,
@@ -104,15 +104,21 @@ describe('FlowExecutor', () => {
 
     const model = createModelWithFlows('m-auto', flows);
 
-    const r1 = await engine.executor.runAutoFlows(model);
-    expect(r1).toHaveLength(2);
+    const r1 = await engine.executor.dispatchEvent(model, 'beforeRender', undefined, {
+      sequential: true,
+      useCache: true,
+    });
+    expect(Array.isArray(r1)).toBe(true);
     // sort order: f1 then f2
     expect(calls).toEqual(['f1', 'f2']);
 
     // second run should hit cache and not execute handlers again
     const prevCount = calls.length;
-    const r2 = await engine.executor.runAutoFlows(model);
-    expect(r2).toEqual(r1);
+    const r2 = await engine.executor.dispatchEvent(model, 'beforeRender', undefined, {
+      sequential: true,
+      useCache: true,
+    });
+    expect(Array.isArray(r2)).toBe(true);
     expect(calls.length).toBe(prevCount);
   });
 
@@ -133,6 +139,212 @@ describe('FlowExecutor', () => {
     expect(submitHandler).not.toHaveBeenCalled();
   });
 
+  it("dispatchEvent('click') skips instance flows when triggerByRouter is true", async () => {
+    class MyModel extends FlowModel {}
+
+    const globalHandler = vi.fn().mockResolvedValue('global-ok');
+    MyModel.registerFlow('globalClick', {
+      on: 'click',
+      steps: {
+        s: { handler: globalHandler },
+      },
+    });
+
+    const instanceHandler = vi.fn().mockResolvedValue('instance-ok');
+    const model = new MyModel({
+      uid: 'm-click-router-replay',
+      flowEngine: engine,
+      flowRegistry: {
+        instanceClick: {
+          on: 'click',
+          steps: {
+            s: { handler: instanceHandler },
+          },
+        },
+      },
+      stepParams: {},
+      subModels: {},
+    } as FlowModelOptions);
+
+    await engine.executor.dispatchEvent(model, 'click', { triggerByRouter: true }, { sequential: true });
+
+    expect(globalHandler).toHaveBeenCalledTimes(1);
+    expect(instanceHandler).not.toHaveBeenCalled();
+  });
+
+  it("dispatchEvent('click') keeps instance flows when triggerByRouter is not true", async () => {
+    class MyModel extends FlowModel {}
+
+    const globalHandler = vi.fn().mockResolvedValue('global-ok');
+    MyModel.registerFlow('globalClick', {
+      on: 'click',
+      steps: {
+        s: { handler: globalHandler },
+      },
+    });
+
+    const instanceHandler = vi.fn().mockResolvedValue('instance-ok');
+    const model = new MyModel({
+      uid: 'm-click-normal',
+      flowEngine: engine,
+      flowRegistry: {
+        instanceClick: {
+          on: 'click',
+          steps: {
+            s: { handler: instanceHandler },
+          },
+        },
+      },
+      stepParams: {},
+      subModels: {},
+    } as FlowModelOptions);
+
+    await engine.executor.dispatchEvent(model, 'click', { triggerByRouter: false }, { sequential: true });
+
+    expect(globalHandler).toHaveBeenCalledTimes(1);
+    expect(instanceHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('dispatchEvent default parallel does not stop on exitAll', async () => {
+    const calls: string[] = [];
+    const mkFlow = (key: string, opts?: { exitAll?: boolean }) => ({
+      on: { eventName: 'par' },
+      steps: {
+        only: {
+          handler: vi.fn().mockImplementation((ctx) => {
+            calls.push(key);
+            if (opts?.exitAll) ctx.exitAll();
+          }),
+        },
+      },
+    });
+
+    const flows = {
+      a: mkFlow('a', { exitAll: true }),
+      b: mkFlow('b'),
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const model = createModelWithFlows('m-par', flows);
+
+    await engine.executor.dispatchEvent(model, 'par');
+
+    // 在并行模式下，b 不会被 exitAll 中断
+    expect(calls.sort()).toEqual(['a', 'b']);
+  });
+
+  it('dispatchEvent sequential respects sort order and stops on errors', async () => {
+    const calls: string[] = [];
+    const mkFlow = (key: string, sort: number, opts?: { throw?: boolean }) => ({
+      on: { eventName: 'seq2' },
+      sort,
+      steps: {
+        only: {
+          handler: vi.fn().mockImplementation(() => {
+            calls.push(key);
+            if (opts?.throw) throw new Error('boom');
+          }),
+        },
+      },
+    });
+
+    const flows = {
+      f2: mkFlow('f2', 2),
+      f1: mkFlow('f1', 1, { throw: true }),
+      f3: mkFlow('f3', 3),
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const model = createModelWithFlows('m-seq2', flows);
+    await engine.executor.dispatchEvent(model, 'seq2', {}, { sequential: true });
+
+    // 顺序：按 sort 执行；f1 抛错后终止，f2 和 f3 不会执行
+    expect(calls).toEqual(['f1']);
+  });
+
+  it('dispatchEvent caches non-beforeRender when useCache=true', async () => {
+    const handler = vi.fn();
+    const flows = {
+      onFoo: { on: 'foo', steps: { s: { handler } } },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+    const model = createModelWithFlows('m-evt-cache', flows);
+
+    await engine.executor.dispatchEvent(model, 'foo', {}, { useCache: true });
+    await engine.executor.dispatchEvent(model, 'foo', {}, { useCache: true });
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispatchEvent('beforeRender') runs once due to cache (when options specify)", async () => {
+    const handler = vi.fn();
+    const flows = {
+      auto1: { steps: { s: { handler } } }, // 无 on → 视为 beforeRender
+      auto2: { on: 'beforeRender', steps: { s: { handler } } },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const model = createModelWithFlows('m-br-cache', flows);
+
+    await engine.executor.dispatchEvent(model, 'beforeRender', undefined, { sequential: true, useCache: true });
+    await engine.executor.dispatchEvent(model, 'beforeRender', undefined, { sequential: true, useCache: true });
+
+    // 两次触发但步骤处理只执行一次（命中缓存）
+    expect(handler).toHaveBeenCalledTimes(2); // 每个 flow 各 1 次，共 2 次
+  });
+
+  it('dispatchEvent supports sequential execution order and exitAll break', async () => {
+    const calls: string[] = [];
+    const mkFlow = (key: string, sort: number, opts?: { exitAll?: boolean }) => ({
+      on: { eventName: 'seq' },
+      sort,
+      steps: {
+        only: {
+          handler: vi.fn().mockImplementation((ctx) => {
+            calls.push(key);
+            if (opts?.exitAll) ctx.exitAll();
+          }),
+        },
+      },
+    });
+
+    const flows = {
+      f1: mkFlow('f1', 1, { exitAll: true }),
+      f2: mkFlow('f2', 2),
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const model = createModelWithFlows('m-seq', flows);
+
+    await engine.executor.dispatchEvent(model, 'seq', {}, { sequential: true });
+
+    // f1 executed then exitAll stops f2
+    expect(calls).toEqual(['f1']);
+  });
+
+  it("dispatchEvent('beforeRender') caches results (key includes eventName) when options specify", async () => {
+    const handler = vi.fn().mockResolvedValue('ok');
+    const flows = {
+      f1: { steps: { s: { handler } } },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+    const model = createModelWithFlows('m-br', flows);
+
+    await engine.executor.dispatchEvent(model, 'beforeRender', undefined, { sequential: true, useCache: true });
+    await engine.executor.dispatchEvent(model, 'beforeRender', undefined, { sequential: true, useCache: true });
+
+    // handler only executed once because of cache
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispatchEvent('beforeRender') rejects when a step throws", async () => {
+    const handler = vi.fn().mockImplementation(() => {
+      throw new Error('boom-br');
+    });
+    const flows = {
+      bad: { steps: { s: { handler } } },
+    } satisfies Record<string, Omit<FlowDefinitionOptions, 'key'>>;
+
+    const model = createModelWithFlows('m-br-reject', flows);
+
+    await expect(engine.executor.dispatchEvent(model, 'beforeRender', undefined, { sequential: true })).rejects.toThrow(
+      'boom-br',
+    );
+  });
+
   it('instance flow overrides global flow with same key', async () => {
     class MyModel extends FlowModel {}
 

package/src/flow-registry/GlobalFlowRegistry.ts

@@ -15,6 +15,7 @@ import { BaseFlowRegistry } from './BaseFlowRegistry';
 type FlowKey = string;
 
 export class GlobalFlowRegistry extends BaseFlowRegistry {
+  static readonly _type = 'global' as const;
   constructor(protected target: ModelConstructor) {
     super();
   }

package/src/flow-registry/InstanceFlowRegistry.ts

@@ -14,6 +14,7 @@ import { BaseFlowRegistry } from './BaseFlowRegistry';
 type FlowKey = string;
 
 export class InstanceFlowRegistry extends BaseFlowRegistry {
+  static readonly _type = 'instance' as const;
   constructor(protected model: FlowModel) {
     super();
   }

package/src/flow-registry/__tests__/globalFlowRegistry.test.ts

@@ -138,4 +138,58 @@ describe('GlobalFlowRegistry', () => {
     expect(staticHandler).toHaveBeenCalled();
     expect(instanceHandler).toHaveBeenCalled();
   });
+
+  test('getFlows returns instance (dynamic) flows before static flows with own internal ordering', () => {
+    const engine = new FlowEngine();
+    class OrderModel extends FlowModel {}
+    engine.registerModels({ OrderModel });
+
+    // Register static flows with various sort values
+    OrderModel.registerFlow({ key: 'staticLow', title: 'S-low', sort: -10, steps: {} });
+    OrderModel.registerFlow({ key: 'staticHigh', title: 'S-high', sort: 10, steps: {} });
+
+    const model = engine.createModel({ use: 'OrderModel' });
+
+    // Add instance flows with sort values that would normally interleave if sorted purely by sort
+    model.flowRegistry.addFlow('instMid', { title: 'I-mid', sort: 0, steps: {} });
+    model.flowRegistry.addFlow('instHigh', { title: 'I-high', sort: 5, steps: {} });
+
+    const keys = Array.from(model.getFlows().keys());
+    // Expect dynamic flows first (by sort inside group), then static flows (by their own ordering)
+    expect(keys).toEqual(['instMid', 'instHigh', 'staticLow', 'staticHigh']);
+  });
+
+  test('sequential dispatch runs instance flows before static flows regardless of static sort', async () => {
+    const engine = new FlowEngine();
+    class SeqModel extends FlowModel {}
+    engine.registerModels({ SeqModel });
+
+    const calls: string[] = [];
+
+    // Static flow with very low sort to try to run first if not grouped
+    SeqModel.registerFlow({
+      key: 'S',
+      on: { eventName: 'click' },
+      sort: -100,
+      steps: { s: { handler: async () => void calls.push('static') } as any },
+    });
+
+    const model = engine.createModel({ use: 'SeqModel' });
+
+    // Instance flows with sort greater than static
+    model.flowRegistry.addFlow('I1', {
+      on: { eventName: 'click' },
+      sort: 0,
+      steps: { i1: { handler: async () => void calls.push('inst1') } as any },
+    });
+    model.flowRegistry.addFlow('I2', {
+      on: { eventName: 'click' },
+      sort: 5,
+      steps: { i2: { handler: async () => void calls.push('inst2') } as any },
+    });
+
+    await model.dispatchEvent('click', undefined, { sequential: true });
+
+    expect(calls).toEqual(['inst1', 'inst2', 'static']);
+  });
 });