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

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

@@ -0,0 +1,169 @@
+/**
+ * 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 '../../models/flowModel';
+
+describe('dispatchEvent behavior (defaults, parallel, errors)', () => {
+  test('non-beforeRender defaults to sequential execution and respects getEventFlows order', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    // Static flow with higher sort
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      sort: 10,
+      steps: { s: { handler: async () => void calls.push('static') } as any },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+
+    // Instance flows
+    model.registerFlow('I1', {
+      on: { eventName: 'go' },
+      sort: 0,
+      steps: { i1: { handler: async () => void calls.push('inst1') } as any },
+    });
+    model.registerFlow('I2', {
+      on: { eventName: 'go' },
+      sort: 5,
+      steps: { i2: { handler: async () => void calls.push('inst2') } as any },
+    });
+
+    // No options provided -> should default to sequential execution
+    await model.dispatchEvent('go');
+
+    // Expected order should match getEventFlows('go') order
+    const expected = model.getEventFlows('go').map((f) => f.key);
+    expect(calls).toEqual(expected.map((k) => (k === 'I1' ? 'inst1' : k === 'I2' ? 'inst2' : 'static')));
+  });
+
+  test('parallel mode (sequential=false) runs all and tolerates non-beforeRender errors', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+
+    M.registerFlow({
+      key: 'S',
+      on: { eventName: 'go' },
+      sort: 1,
+      steps: { s: { handler: async () => 'static-ok' } as any },
+    });
+
+    const model = engine.createModel({ use: 'M' });
+
+    model.registerFlow('I1', {
+      on: { eventName: 'go' },
+      sort: 0,
+      steps: { i1: { handler: async () => (calls.push('inst1'), 'i1-ok') } as any },
+    });
+    model.registerFlow('I2', {
+      on: { eventName: 'go' },
+      sort: 2,
+      steps: { i2: { handler: async () => (calls.push('inst2'), 'i2-ok') } as any },
+    });
+    model.registerFlow('ERR', {
+      on: { eventName: 'go' },
+      sort: 3,
+      steps: {
+        e: {
+          handler: async () => {
+            calls.push('err');
+            throw new Error('boom');
+          },
+        } as any,
+      },
+    });
+
+    const results = await model.dispatchEvent('go', undefined, { sequential: false });
+
+    // All handlers ran; order is not guaranteed in parallel mode
+    expect(new Set(calls)).toEqual(new Set(['inst1', 'inst2', 'err']));
+    // The error flow returns undefined and is filtered out; others return stepResults objects
+    // Expect one result object per successful flow with its step key
+    expect(Array.isArray(results)).toBe(true);
+    const keys = (results as any[]).flatMap((o) => Object.keys(o));
+    expect(new Set(keys)).toEqual(new Set(['i1', 'i2', 's']));
+    const byKey = Object.assign({}, ...(results as any[]));
+    expect(byKey['i1']).toBe('i1-ok');
+    expect(byKey['i2']).toBe('i2-ok');
+    expect(byKey['s']).toBe('static-ok');
+  });
+
+  test('sequential non-beforeRender: stops subsequent flows on error', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+    const model = engine.createModel({ use: 'M' });
+
+    model.registerFlow('I1', {
+      on: { eventName: 'go' },
+      sort: 0,
+      steps: { i1: { handler: async () => void calls.push('i1') } as any },
+    });
+    model.registerFlow('ERR', {
+      on: { eventName: 'go' },
+      sort: 1,
+      steps: {
+        e: {
+          handler: async () => {
+            throw new Error('X');
+          },
+        } as any,
+      },
+    });
+    model.registerFlow('I2', {
+      on: { eventName: 'go' },
+      sort: 2,
+      steps: { i2: { handler: async () => void calls.push('i2') } as any },
+    });
+
+    await model.dispatchEvent('go', undefined, { sequential: true }).catch(() => undefined);
+    // 只应执行第一个 flow，后续被中止
+    expect(calls).toEqual(['i1']);
+  });
+
+  test('beforeRender errors are thrown (sequential default)', async () => {
+    const engine = new FlowEngine();
+    class M extends FlowModel {}
+    engine.registerModels({ M });
+
+    const calls: string[] = [];
+    const model = engine.createModel({ use: 'M' });
+
+    model.registerFlow('F1', {
+      on: 'beforeRender',
+      sort: 0,
+      steps: {
+        a: {
+          handler: async () => {
+            throw new Error('BR');
+          },
+        } as any,
+      },
+    });
+    model.registerFlow('F2', {
+      on: 'beforeRender',
+      sort: 1,
+      steps: { b: { handler: async () => void calls.push('b') } as any },
+    });
+
+    await expect(model.dispatchEvent('beforeRender', undefined, { useCache: false })).rejects.toThrow('BR');
+    expect(calls).toEqual([]);
+  });
+});

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__/flowEngine.resolveUse.test.ts

@@ -0,0 +1,170 @@
+/**
+ * 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, expect, test, vi, beforeEach, afterEach } from 'vitest';
+import { FlowEngine } from '../../flowEngine';
+import { ErrorFlowModel, FlowModel } from '../flowModel';
+
+describe('FlowEngine.createModel resolveUse hook', () => {
+  let engine: FlowEngine;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    engine = new FlowEngine();
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test('should use resolveUse returning registered name', () => {
+    class DynamicTarget extends FlowModel {}
+    class DynamicEntry extends FlowModel {
+      static resolveUse() {
+        return 'DynamicTarget';
+      }
+    }
+
+    engine.registerModels({ DynamicEntry, DynamicTarget });
+
+    const model = engine.createModel({ use: 'DynamicEntry', uid: 'dynamic-entry', flowEngine: engine });
+
+    expect(model).toBeInstanceOf(DynamicTarget);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test('should chain resolveUse until final constructor', () => {
+    class ChainLeaf extends FlowModel {}
+    class ChainMid extends FlowModel {
+      static resolveUse() {
+        return ChainLeaf;
+      }
+    }
+    class ChainStart extends FlowModel {
+      static resolveUse() {
+        return 'ChainMid';
+      }
+    }
+
+    engine.registerModels({ ChainLeaf, ChainMid, ChainStart });
+
+    const model = engine.createModel({ use: 'ChainStart', uid: 'chain-start', flowEngine: engine });
+
+    expect(model).toBeInstanceOf(ChainLeaf);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test('should break resolveUse on circular reference and warn', () => {
+    class LoopModel extends FlowModel {
+      static resolveUse() {
+        return 'LoopModel';
+      }
+    }
+
+    engine.registerModels({ LoopModel });
+
+    const model = engine.createModel({ use: 'LoopModel', uid: 'loop-model', flowEngine: engine });
+
+    expect(model).toBeInstanceOf(LoopModel);
+    expect(warnSpy).toHaveBeenCalled();
+  });
+
+  test('should fall back to ErrorFlowModel when resolveUse returns unregistered name', () => {
+    class MissingTargetEntry extends FlowModel {
+      static resolveUse() {
+        return 'NoSuchModel';
+      }
+    }
+
+    engine.registerModels({ MissingTargetEntry });
+
+    const model = engine.createModel({ use: 'MissingTargetEntry', uid: 'missing-target', flowEngine: engine });
+
+    expect(model).toBeInstanceOf(ErrorFlowModel);
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("resolveUse returned 'NoSuchModel' but no model is registered under that name."),
+    );
+  });
+
+  test('should keep original use in serialized data after resolveUse', () => {
+    class DynamicTarget extends FlowModel {}
+    class DynamicEntry extends FlowModel {
+      static resolveUse() {
+        return DynamicTarget;
+      }
+    }
+
+    engine.registerModels({ DynamicEntry, DynamicTarget });
+
+    const model = engine.createModel({ use: 'DynamicEntry', uid: 'dynamic-entry', flowEngine: engine });
+    const serialized = model.serialize();
+
+    expect(model).toBeInstanceOf(DynamicTarget);
+    expect(serialized.use).toBe('DynamicEntry');
+  });
+
+  test('should receive parent model in resolveUse for sub-model decision', () => {
+    class ChildA extends FlowModel {}
+    class ChildB extends FlowModel {}
+    class Parent extends FlowModel {}
+    class ChildEntry extends FlowModel {
+      static resolveUse(options, _engine, parent?: FlowModel) {
+        return parent?.props?.variant === 'B' ? 'ChildB' : 'ChildA';
+      }
+    }
+
+    engine.registerModels({ Parent, ChildEntry, ChildA, ChildB });
+
+    const parentA = engine.createModel({ use: 'Parent', uid: 'p-a', flowEngine: engine, props: { variant: 'A' } });
+    const childA = engine.createModel({
+      use: 'ChildEntry',
+      uid: 'c-a',
+      flowEngine: engine,
+      parentId: parentA.uid,
+      subKey: 'child',
+    });
+    expect(childA).toBeInstanceOf(ChildA);
+
+    const parentB = engine.createModel({ use: 'Parent', uid: 'p-b', flowEngine: engine, props: { variant: 'B' } });
+    const childB = engine.createModel({
+      use: 'ChildEntry',
+      uid: 'c-b',
+      flowEngine: engine,
+      parentId: parentB.uid,
+      subKey: 'child',
+    });
+    expect(childB).toBeInstanceOf(ChildB);
+  });
+
+  test('should stop resolveUse chain when stop flag is true', () => {
+    const leafSpy = vi.fn();
+
+    class Leaf extends FlowModel {
+      static resolveUse = leafSpy;
+    }
+    class Mid extends FlowModel {
+      static resolveUse() {
+        return 'Leaf';
+      }
+    }
+    class Entry extends FlowModel {
+      static resolveUse() {
+        return { use: 'Mid', stop: true };
+      }
+    }
+
+    engine.registerModels({ Entry, Mid, Leaf });
+
+    const model = engine.createModel({ use: 'Entry', uid: 'stop-flag', flowEngine: engine });
+
+    expect(model).toBeInstanceOf(Mid);
+    expect(leafSpy).not.toHaveBeenCalled();
+  });
+});