@nocobase/flow-engine 2.0.0-alpha.10

package/src/__tests__/flowRunJSContextDefine.test.ts

@@ -0,0 +1,508 @@
+/**
+ * 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, beforeEach } from 'vitest';
+import { FlowRunJSContext } from '../flowContext';
+
+describe('FlowRunJSContext.define() and getDoc() deep tests', () => {
+  // Create test classes for inheritance testing
+  class TestBaseContext extends FlowRunJSContext {}
+  class TestChildContext extends TestBaseContext {}
+  class TestGrandchildContext extends TestChildContext {}
+
+  beforeEach(() => {
+    // Clear all caches to ensure clean state for each test
+    // @ts-ignore - accessing private WeakMap for testing
+    const cache = (FlowRunJSContext as any).__runjsDocCache;
+    if (cache) {
+      // WeakMaps can't be cleared directly, but we can create new test classes
+    }
+  });
+
+  describe('Deep merging', () => {
+    it('should deep merge nested object properties', () => {
+      class MergeTestContext extends FlowRunJSContext {}
+
+      MergeTestContext.define({
+        properties: {
+          api: {
+            description: 'API client',
+            properties: {
+              request: { description: 'Request method' },
+              auth: { description: 'Auth info' },
+            },
+          },
+        },
+      });
+
+      MergeTestContext.define({
+        properties: {
+          api: {
+            properties: {
+              request: { description: 'Updated request method' },
+              query: { description: 'Query method' },
+            },
+          },
+        },
+      });
+
+      const doc = MergeTestContext.getDoc();
+      expect(doc.properties?.api).toBeTruthy();
+      const apiProp: any = doc.properties?.api;
+      expect(apiProp.description).toBe('API client');
+      expect(apiProp.properties?.request?.description).toBe('Updated request method');
+      expect(apiProp.properties?.query?.description).toBe('Query method');
+      expect(apiProp.properties?.auth?.description).toBe('Auth info');
+    });
+
+    it('should deep merge method documentation', () => {
+      class MethodMergeContext extends FlowRunJSContext {}
+
+      MethodMergeContext.define({
+        methods: {
+          runAction: {
+            description: 'Run an action',
+            completion: { insertText: 'ctx.runAction()' },
+          },
+        },
+      });
+
+      MethodMergeContext.define({
+        methods: {
+          runAction: {
+            description: 'Execute a data action',
+            examples: ['ctx.runAction("create", {})'],
+          },
+        },
+      });
+
+      const doc = MethodMergeContext.getDoc();
+      const method: any = doc.methods?.runAction;
+      expect(method?.description).toBe('Execute a data action');
+      expect(method?.completion?.insertText).toBe('ctx.runAction()');
+      expect(method?.examples).toEqual(['ctx.runAction("create", {})']);
+    });
+  });
+
+  describe('Null value property deletion', () => {
+    it('should remove property when defined with null', () => {
+      class NullTestContext extends FlowRunJSContext {}
+
+      NullTestContext.define({
+        properties: {
+          foo: 'Foo property',
+          bar: 'Bar property',
+        },
+      });
+
+      NullTestContext.define({
+        properties: {
+          foo: null as any,
+        },
+      });
+
+      const doc = NullTestContext.getDoc();
+      expect(doc.properties?.foo).toBeUndefined();
+      expect(doc.properties?.bar).toBe('Bar property');
+    });
+
+    it('should remove nested property when defined with null', () => {
+      class NestedNullContext extends FlowRunJSContext {}
+
+      NestedNullContext.define({
+        properties: {
+          api: {
+            description: 'API client',
+            properties: {
+              request: { description: 'Request' },
+              query: { description: 'Query' },
+            },
+          },
+        },
+      });
+
+      NestedNullContext.define({
+        properties: {
+          api: {
+            properties: {
+              query: null as any,
+            },
+          },
+        },
+      });
+
+      const doc = NestedNullContext.getDoc();
+      const apiProp: any = doc.properties?.api;
+      expect(apiProp.properties?.request?.description).toBe('Request');
+      expect(apiProp.properties?.query).toBeUndefined();
+    });
+
+    it('should remove method when defined with null', () => {
+      class MethodNullContext extends FlowRunJSContext {}
+
+      MethodNullContext.define({
+        methods: {
+          foo: 'Foo method',
+          bar: 'Bar method',
+        },
+      });
+
+      MethodNullContext.define({
+        methods: {
+          foo: null as any,
+        },
+      });
+
+      const doc = MethodNullContext.getDoc();
+      expect(doc.methods?.foo).toBeUndefined();
+      expect(doc.methods?.bar).toBe('Bar method');
+    });
+  });
+
+  describe('Inheritance chain merging', () => {
+    it('should merge metadata from parent class', () => {
+      class InheritBaseContext extends FlowRunJSContext {}
+      class InheritChildContext extends InheritBaseContext {}
+
+      InheritBaseContext.define({
+        label: 'Base Context',
+        properties: {
+          baseProp: 'Base property',
+        },
+      });
+
+      InheritChildContext.define({
+        label: 'Child Context',
+        properties: {
+          childProp: 'Child property',
+        },
+      });
+
+      const doc = InheritChildContext.getDoc();
+      expect(doc.label).toBe('Child Context');
+      expect(doc.properties?.baseProp).toBe('Base property');
+      expect(doc.properties?.childProp).toBe('Child property');
+    });
+
+    it('should merge metadata from entire inheritance chain', () => {
+      class ChainBase extends FlowRunJSContext {}
+      class ChainMiddle extends ChainBase {}
+      class ChainLeaf extends ChainMiddle {}
+
+      ChainBase.define({
+        properties: { base: 'base' },
+        methods: { baseMethod: 'base method' },
+      });
+
+      ChainMiddle.define({
+        properties: { middle: 'middle' },
+        methods: { middleMethod: 'middle method' },
+      });
+
+      ChainLeaf.define({
+        properties: { leaf: 'leaf' },
+        methods: { leafMethod: 'leaf method' },
+      });
+
+      const doc = ChainLeaf.getDoc();
+      expect(doc.properties?.base).toBe('base');
+      expect(doc.properties?.middle).toBe('middle');
+      expect(doc.properties?.leaf).toBe('leaf');
+      expect(doc.methods?.baseMethod).toBe('base method');
+      expect(doc.methods?.middleMethod).toBe('middle method');
+      expect(doc.methods?.leafMethod).toBe('leaf method');
+    });
+
+    it('should allow child to override parent properties', () => {
+      class OverrideBase extends FlowRunJSContext {}
+      class OverrideChild extends OverrideBase {}
+
+      OverrideBase.define({
+        properties: {
+          shared: 'Base version',
+        },
+      });
+
+      OverrideChild.define({
+        properties: {
+          shared: 'Child version',
+        },
+      });
+
+      const doc = OverrideChild.getDoc();
+      expect(doc.properties?.shared).toBe('Child version');
+    });
+
+    it('should allow child to remove parent properties with null', () => {
+      class RemoveBase extends FlowRunJSContext {}
+      class RemoveChild extends RemoveBase {}
+
+      RemoveBase.define({
+        properties: {
+          toRemove: 'To be removed',
+          toKeep: 'To keep',
+        },
+      });
+
+      RemoveChild.define({
+        properties: {
+          toRemove: null as any,
+        },
+      });
+
+      const doc = RemoveChild.getDoc();
+      expect(doc.properties?.toRemove).toBeUndefined();
+      expect(doc.properties?.toKeep).toBe('To keep');
+    });
+  });
+
+  describe('Locale-specific metadata', () => {
+    it('should support multiple locales', () => {
+      class LocaleContext extends FlowRunJSContext {}
+
+      LocaleContext.define({
+        label: 'Default Label',
+        properties: { message: 'Default message' },
+      });
+
+      LocaleContext.define(
+        {
+          label: 'Chinese Label',
+          properties: { message: '中文消息' },
+        },
+        { locale: 'zh-CN' },
+      );
+
+      LocaleContext.define(
+        {
+          label: 'Japanese Label',
+          properties: { message: '日本語メッセージ' },
+        },
+        { locale: 'ja-JP' },
+      );
+
+      const defaultDoc = LocaleContext.getDoc();
+      expect(defaultDoc.label).toBe('Default Label');
+      expect(defaultDoc.properties?.message).toBe('Default message');
+
+      const zhDoc = LocaleContext.getDoc('zh-CN');
+      expect(zhDoc.label).toBe('Chinese Label');
+      expect(zhDoc.properties?.message).toBe('中文消息');
+
+      const jaDoc = LocaleContext.getDoc('ja-JP');
+      expect(jaDoc.label).toBe('Japanese Label');
+      expect(jaDoc.properties?.message).toBe('日本語メッセージ');
+    });
+
+    it('should merge locale-specific metadata with default', () => {
+      class LocaleMergeContext extends FlowRunJSContext {}
+
+      LocaleMergeContext.define({
+        properties: {
+          api: 'API client',
+          message: 'Message',
+        },
+      });
+
+      LocaleMergeContext.define(
+        {
+          properties: {
+            message: '消息',
+          },
+        },
+        { locale: 'zh-CN' },
+      );
+
+      const zhDoc = LocaleMergeContext.getDoc('zh-CN');
+      expect(zhDoc.properties?.api).toBe('API client');
+      expect(zhDoc.properties?.message).toBe('消息');
+    });
+
+    it('should support locale inheritance', () => {
+      class LocaleInheritBase extends FlowRunJSContext {}
+      class LocaleInheritChild extends LocaleInheritBase {}
+
+      LocaleInheritBase.define({ properties: { base: 'base' } });
+      LocaleInheritBase.define({ properties: { base: '基础' } }, { locale: 'zh-CN' });
+
+      LocaleInheritChild.define({ properties: { child: 'child' } });
+      LocaleInheritChild.define({ properties: { child: '子级' } }, { locale: 'zh-CN' });
+
+      const zhDoc = LocaleInheritChild.getDoc('zh-CN');
+      expect(zhDoc.properties?.base).toBe('基础');
+      expect(zhDoc.properties?.child).toBe('子级');
+    });
+  });
+
+  describe('Cache behavior', () => {
+    it('should cache getDoc results', () => {
+      class CacheContext extends FlowRunJSContext {}
+
+      CacheContext.define({
+        properties: { foo: 'bar' },
+      });
+
+      const doc1 = CacheContext.getDoc();
+      const doc2 = CacheContext.getDoc();
+
+      // Should return the same cached object
+      expect(doc1).toBe(doc2);
+    });
+
+    it('should invalidate cache when define is called', () => {
+      class InvalidateContext extends FlowRunJSContext {}
+
+      InvalidateContext.define({
+        properties: { foo: 'initial' },
+      });
+
+      const doc1 = InvalidateContext.getDoc();
+      expect(doc1.properties?.foo).toBe('initial');
+
+      InvalidateContext.define({
+        properties: { foo: 'updated' },
+      });
+
+      const doc2 = InvalidateContext.getDoc();
+      expect(doc2.properties?.foo).toBe('updated');
+
+      // Should be different objects after invalidation
+      expect(doc1).not.toBe(doc2);
+    });
+
+    it('should cache different locales separately', () => {
+      class LocaleCacheContext extends FlowRunJSContext {}
+
+      LocaleCacheContext.define({ properties: { msg: 'English' } });
+      LocaleCacheContext.define({ properties: { msg: '中文' } }, { locale: 'zh-CN' });
+
+      const enDoc1 = LocaleCacheContext.getDoc();
+      const zhDoc1 = LocaleCacheContext.getDoc('zh-CN');
+      const enDoc2 = LocaleCacheContext.getDoc();
+      const zhDoc2 = LocaleCacheContext.getDoc('zh-CN');
+
+      expect(enDoc1).toBe(enDoc2);
+      expect(zhDoc1).toBe(zhDoc2);
+      expect(enDoc1).not.toBe(zhDoc1);
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle empty define calls', () => {
+      class EmptyContext extends FlowRunJSContext {}
+
+      EmptyContext.define({});
+      const doc = EmptyContext.getDoc();
+
+      expect(doc).toBeTruthy();
+      expect(typeof doc).toBe('object');
+    });
+
+    it('should handle undefined values gracefully', () => {
+      class UndefinedContext extends FlowRunJSContext {}
+
+      UndefinedContext.define({
+        properties: {
+          foo: undefined as any,
+        },
+      });
+
+      const doc = UndefinedContext.getDoc();
+      expect(doc.properties?.foo).toBeUndefined();
+    });
+
+    it('should handle arrays in properties', () => {
+      class ArrayContext extends FlowRunJSContext {}
+
+      ArrayContext.define({
+        properties: {
+          examples: ['example1', 'example2'] as any,
+        },
+      });
+
+      const doc = ArrayContext.getDoc();
+      expect(doc.properties?.examples).toEqual(['example1', 'example2']);
+    });
+
+    it('should not merge arrays, replace them instead', () => {
+      class ArrayReplaceContext extends FlowRunJSContext {}
+
+      ArrayReplaceContext.define({
+        properties: {
+          items: ['a', 'b'] as any,
+        },
+      });
+
+      ArrayReplaceContext.define({
+        properties: {
+          items: ['c', 'd'] as any,
+        },
+      });
+
+      const doc = ArrayReplaceContext.getDoc();
+      expect(doc.properties?.items).toEqual(['c', 'd']);
+    });
+  });
+
+  describe('Multiple define calls', () => {
+    it('should accumulate metadata from multiple define calls', () => {
+      class MultiDefineContext extends FlowRunJSContext {}
+
+      MultiDefineContext.define({
+        properties: { prop1: 'value1' },
+      });
+
+      MultiDefineContext.define({
+        properties: { prop2: 'value2' },
+      });
+
+      MultiDefineContext.define({
+        methods: { method1: 'desc1' },
+      });
+
+      const doc = MultiDefineContext.getDoc();
+      expect(doc.properties?.prop1).toBe('value1');
+      expect(doc.properties?.prop2).toBe('value2');
+      expect(doc.methods?.method1).toBe('desc1');
+    });
+
+    it('should allow incremental updates to nested structures', () => {
+      class IncrementalContext extends FlowRunJSContext {}
+
+      IncrementalContext.define({
+        properties: {
+          api: {
+            description: 'API client',
+            properties: {
+              request: { description: 'Request method' },
+            },
+          },
+        },
+      });
+
+      IncrementalContext.define({
+        properties: {
+          api: {
+            detail: 'APIClient instance',
+            properties: {
+              query: { description: 'Query method' },
+            },
+          },
+        },
+      });
+
+      const doc = IncrementalContext.getDoc();
+      const apiProp: any = doc.properties?.api;
+      expect(apiProp.description).toBe('API client');
+      expect(apiProp.detail).toBe('APIClient instance');
+      expect(apiProp.properties?.request?.description).toBe('Request method');
+      expect(apiProp.properties?.query?.description).toBe('Query method');
+    });
+  });
+});

package/src/__tests__/flowRuntimeContext.test.ts

@@ -0,0 +1,187 @@
+/**
+ * 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 { ContextPathProxy } from '../ContextPathProxy';
+import { FlowRuntimeContext } from '../flowContext';
+import { FlowEngine } from '../flowEngine';
+import { FlowModel } from '../models/flowModel';
+
+describe('FlowRuntimeContext', () => {
+  let engine: FlowEngine;
+  let model: FlowModel;
+
+  beforeEach(() => {
+    engine = new FlowEngine();
+    model = engine.createModel({ use: 'FlowModel' });
+  });
+
+  it('should support nested property access in runtime mode', () => {
+    const ctx = new FlowRuntimeContext(model, 'flow1');
+    ctx.defineProperty('steps', { value: { step1: { result: 42 } } });
+    ctx.defineProperty('runId', { value: 'abc123' });
+
+    expect(ctx.steps.step1.result).toBe(42);
+    expect(ctx.runId).toBe('abc123');
+    expect(ctx.steps.step2).toBeUndefined();
+    expect(ctx.steps.step1.notExist).toBeUndefined();
+    expect(ctx.notFound).toBeUndefined();
+  });
+
+  it('should return string template in settings mode', () => {
+    const ctx = new FlowRuntimeContext(model, 'flow1', 'settings');
+    ctx.defineProperty('runId', { value: 'mock' });
+    ctx.defineProperty('steps', { value: {} });
+    expect(ctx.runId.toString()).toBe('{{ctx.runId}}');
+    expect(`${ctx.runId}`).toBe('{{ctx.runId}}');
+    expect(ctx.runId).instanceOf(ContextPathProxy);
+    expect(ctx.notFound).toBeUndefined();
+    expect(`${ctx.steps.step1.result}`).toBe('{{ctx.steps.step1.result}}');
+  });
+
+  it('should throw on exit()', () => {
+    const ctx = new FlowRuntimeContext(model, 'flow1', 'runtime');
+    expect(() => ctx.exit()).toThrow();
+  });
+});
+
+describe('FlowRuntimeContext.runAction', () => {
+  let engine: FlowEngine;
+  let model: FlowModel;
+  let ctx: FlowRuntimeContext;
+
+  beforeEach(() => {
+    engine = new FlowEngine();
+    model = engine.createModel({ use: 'FlowModel' });
+    ctx = new FlowRuntimeContext(model, 'unitFlow');
+  });
+
+  it('executes a registered action by name and returns result', async () => {
+    engine.registerActions({
+      hello: {
+        name: 'hello',
+        handler: (_ctx, params) => ({ ok: true, params }),
+      },
+    });
+
+    const res = await ctx.runAction('hello', { x: 1 });
+    expect(res).toEqual({ ok: true, params: { x: 1 } });
+  });
+
+  it('merges defaultParams and resolves expressions when useRawParams is falsy', async () => {
+    engine.registerActions({
+      combine: {
+        name: 'combine',
+        defaultParams: {
+          a: 1,
+          uidFromDefault: '{{ ctx.model.uid }}',
+        },
+        handler: (_ctx, params) => params,
+      },
+    });
+
+    const res = await ctx.runAction('combine', {
+      b: 2,
+      uidFromParam: '{{ ctx.model.uid }}',
+    });
+
+    expect(res).toEqual({
+      a: 1,
+      b: 2,
+      uidFromDefault: model.uid,
+      uidFromParam: model.uid,
+    });
+  });
+
+  it('does not resolve expressions when useRawParams=true', async () => {
+    engine.registerActions({
+      raw: {
+        name: 'raw',
+        defaultParams: {
+          fromDefault: '{{ ctx.model.uid }}',
+        },
+        useRawParams: true,
+        handler: (_ctx, params) => params,
+      },
+    });
+
+    const res = await ctx.runAction('raw', {
+      fromParam: '{{ ctx.model.uid }}',
+      n: 123,
+    });
+    expect(res).toEqual({
+      fromDefault: '{{ ctx.model.uid }}',
+      fromParam: '{{ ctx.model.uid }}',
+      n: 123,
+    });
+  });
+
+  it('supports useRawParams as function', async () => {
+    engine.registerActions({
+      decide: {
+        name: 'decide',
+        defaultParams: { d: '{{ ctx.model.uid }}' },
+        useRawParams: () => Promise.resolve(true),
+        handler: (_ctx, params) => params,
+      },
+    });
+
+    const res = await ctx.runAction('decide', { p: '{{ ctx.model.uid }}' });
+    expect(res).toEqual({ d: '{{ ctx.model.uid }}', p: '{{ ctx.model.uid }}' });
+  });
+
+  it('throws if action not found', async () => {
+    await expect(ctx.runAction('no-such-action')).rejects.toThrow(/not found/i);
+  });
+});
+
+describe('Flow run with step that triggers another action', () => {
+  it('step action calls ctx.runAction to invoke another action', async () => {
+    const engine = new FlowEngine();
+    const model = engine.createModel({ use: 'FlowModel' });
+
+    // second action: merges defaults and resolves expressions
+    engine.registerActions({
+      second: {
+        name: 'second',
+        defaultParams: { a: 1, uidDefault: '{{ ctx.model.uid }}' },
+        handler: (_ctx, params) => ({ from: 'second', ...params }),
+      },
+    });
+
+    // first action: triggers second via ctx.runAction
+    engine.registerActions({
+      first: {
+        name: 'first',
+        handler: async (ctx) => {
+          return await ctx.runAction('second', {
+            b: 2,
+            uidFromFirst: '{{ ctx.model.uid }}',
+          });
+        },
+      },
+    });
+
+    // Define a flow with a single step using 'first'
+    model.flowRegistry.addFlow('chainFlow', {
+      title: 'Chain Flow',
+      steps: {
+        s1: { use: 'first' },
+      },
+    });
+
+    const res = await engine.executor.runFlow(model, 'chainFlow');
+    expect(res.s1).toEqual({
+      from: 'second',
+      a: 1,
+      b: 2,
+      uidDefault: model.uid,
+      uidFromFirst: model.uid,
+    });
+  });
+});