@nocobase/flow-engine 2.0.0-alpha.2

package/src/__tests__/metaTreeNodeCache.test.ts

@@ -0,0 +1,234 @@
+/**
+ * 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, it, vi } from 'vitest';
+import { FlowContext } from '../flowContext';
+
+describe('MetaTreeNode Cache Mechanism', () => {
+  describe('Node-level Caching', () => {
+    it('should return the same MetaTreeNode instance for the same property', () => {
+      const ctx = new FlowContext();
+
+      ctx.defineProperty('user', {
+        meta: {
+          type: 'object',
+          title: 'User',
+          properties: {
+            name: { type: 'string', title: 'Name' },
+          },
+        },
+      });
+
+      // 获取两次相同的 meta tree
+      const tree1 = ctx.getPropertyMetaTree();
+      const tree2 = ctx.getPropertyMetaTree();
+
+      // 应该返回相同的实例
+      expect(tree1[0]).toBe(tree2[0]);
+      expect(tree1[0].children?.[0]).toBe(tree2[0].children?.[0]);
+    });
+
+    it('should return the same MetaTreeNode for same meta objects', () => {
+      const ctx = new FlowContext();
+
+      // 创建可复用的 meta 对象
+      const profileMeta = {
+        type: 'object',
+        title: 'Profile',
+        properties: {
+          bio: { type: 'string', title: 'Bio' },
+        },
+      };
+
+      ctx.defineProperty('user', {
+        meta: {
+          type: 'object',
+          title: 'User',
+          properties: {
+            profile: profileMeta,
+          },
+        },
+      });
+
+      ctx.defineProperty('admin', {
+        meta: {
+          type: 'object',
+          title: 'Admin',
+          properties: {
+            profile: profileMeta, // 复用同一个 meta 对象
+          },
+        },
+      });
+
+      const tree = ctx.getPropertyMetaTree();
+
+      // 找到 user.profile 和 admin.profile 节点
+      const userProfileNode = (tree[0].children as any)?.[0];
+      const adminProfileNode = (tree[1].children as any)?.[0];
+
+      // 应该是同一个实例（因为使用相同的 meta 对象）
+      expect(userProfileNode).toBe(adminProfileNode);
+      expect(userProfileNode.title).toBe('Profile');
+    });
+  });
+
+  describe('Async Meta Upgrade', () => {
+    it('should upgrade async meta node in-place', async () => {
+      const ctx = new FlowContext();
+
+      const asyncMeta = vi.fn(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        return {
+          type: 'object',
+          title: 'Loaded User',
+          properties: {
+            name: { type: 'string', title: 'User Name' },
+            email: { type: 'string', title: 'Email' },
+          },
+        };
+      });
+
+      ctx.defineProperty('user', { meta: asyncMeta });
+
+      const tree = ctx.getPropertyMetaTree();
+      const userNode = tree[0];
+
+      // 初始状态：使用默认值
+      expect(userNode.title).toBe('user'); // 默认使用 name
+      expect(userNode.type).toBe('object');
+      expect(typeof userNode.children).toBe('function');
+
+      // 异步加载
+      const children = await (userNode.children as () => Promise<any>)();
+
+      // 验证原地更新：节点本身的属性被更新了
+      expect(userNode.title).toBe('Loaded User'); // 已被更新
+      expect(userNode.type).toBe('object');
+      expect(userNode.children).toEqual(children); // children 被替换为实际结果
+
+      // 验证子节点
+      expect(children).toHaveLength(2);
+      expect(children[0].name).toBe('name');
+      expect(children[1].name).toBe('email');
+
+      // 再次获取应该返回相同实例
+      const tree2 = ctx.getPropertyMetaTree();
+      expect(tree2[0]).toBe(userNode);
+    });
+
+    it('should handle async meta loading errors gracefully', async () => {
+      const ctx = new FlowContext();
+
+      const errorMeta = vi.fn(async () => {
+        throw new Error('Meta loading failed');
+      });
+
+      ctx.defineProperty('errorProp', { meta: errorMeta });
+
+      const tree = ctx.getPropertyMetaTree();
+      const errorNode = tree[0];
+
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      // 异步加载应该返回空数组
+      const children = await (errorNode.children as () => Promise<any>)();
+      expect(children).toEqual([]);
+      expect(consoleSpy).toHaveBeenCalledWith('Failed to load meta for errorProp:', expect.any(Error));
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('Cache Invalidation', () => {
+    it('should clear cache when property is redefined', () => {
+      const ctx = new FlowContext();
+
+      ctx.defineProperty('user', {
+        meta: { type: 'string', title: 'User String' },
+      });
+
+      const tree1 = ctx.getPropertyMetaTree();
+      expect(tree1[0].title).toBe('User String');
+
+      // 重新定义属性
+      ctx.defineProperty('user', {
+        meta: { type: 'object', title: 'User Object' },
+      });
+
+      const tree2 = ctx.getPropertyMetaTree();
+      expect(tree2[0].title).toBe('User Object');
+
+      // 应该是不同的实例（缓存已清除）
+      expect(tree1[0]).not.toBe(tree2[0]);
+    });
+
+    it('should preserve cache when delegate is added/removed', () => {
+      const ctx1 = new FlowContext();
+      const ctx2 = new FlowContext();
+
+      ctx2.defineProperty('shared', {
+        meta: { type: 'string', title: 'Shared Property' },
+      });
+
+      ctx1.defineProperty('own', {
+        meta: { type: 'string', title: 'Own Property' },
+      });
+
+      const tree1 = ctx1.getPropertyMetaTree();
+      expect(tree1).toHaveLength(1); // only 'own'
+      const ownNode1 = tree1.find((n) => n.name === 'own');
+
+      // 添加委托
+      ctx1.addDelegate(ctx2);
+
+      const tree2 = ctx1.getPropertyMetaTree();
+      expect(tree2).toHaveLength(2); // 'own' + 'shared'
+
+      // 验证缓存被保留了（'own' 是同一个实例）
+      const ownNode2 = tree2.find((n) => n.name === 'own');
+      expect(ownNode1).toBe(ownNode2);
+
+      // 新的 'shared' 节点是首次创建
+      const sharedNode = tree2.find((n) => n.name === 'shared');
+      expect(sharedNode).toBeDefined();
+      expect(sharedNode?.title).toBe('Shared Property');
+    });
+  });
+
+  describe('Reference Stability', () => {
+    it('should maintain reference stability across multiple calls', () => {
+      const ctx = new FlowContext();
+
+      ctx.defineProperty('stable', {
+        meta: {
+          type: 'object',
+          title: 'Stable Node',
+          properties: {
+            child: { type: 'string', title: 'Child' },
+          },
+        },
+      });
+
+      // 多次调用应返回相同引用
+      const calls = Array.from({ length: 5 }, () => ctx.getPropertyMetaTree());
+
+      // 所有调用应返回相同的根节点实例
+      const rootNodes = calls.map((tree) => tree[0]);
+      rootNodes.forEach((node) => {
+        expect(node).toBe(rootNodes[0]);
+      });
+
+      // 子节点也应该稳定
+      const childNodes = calls.map((tree) => (tree[0].children as any)?.[0]);
+      childNodes.forEach((node) => {
+        expect(node).toBe(childNodes[0]);
+      });
+    });
+  });
+});

package/src/__tests__/path-aggregation.test.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 } from 'vitest';
+import { FlowEngine } from '../flowEngine';
+
+describe('resolveJsonTemplate: dot-only path aggregation', () => {
+  it('aggregates across arrays with dot-only path', async () => {
+    const engine = new FlowEngine();
+    engine.context.defineProperty('a', {
+      value: {
+        b: [
+          { c: 1, d: [1, 2] },
+          { c: 2, d: [3] },
+        ],
+      },
+    });
+
+    const out = await (engine.context as any).resolveJsonTemplate('{{ ctx.a.b.d }}');
+    expect(out).toEqual([1, 2, 3]);
+  });
+
+  it('replaces inside template strings and stringifies arrays', async () => {
+    const engine = new FlowEngine();
+    engine.context.defineProperty('a', {
+      value: { b: [{ d: [1, 2] }, { d: [3] }] },
+    });
+
+    const out = await (engine.context as any).resolveJsonTemplate('x={{ ctx.a.b.d }};');
+    expect(out).toBe('x=[1,2,3];');
+  });
+
+  it('returns scalar for non-array dot-only path', async () => {
+    const engine = new FlowEngine();
+    engine.context.defineProperty('a', {
+      value: { title: 'hello' },
+    });
+    const out = await (engine.context as any).resolveJsonTemplate('{{ ctx.a.title }}');
+    expect(out).toBe('hello');
+  });
+
+  it('returns undefined if path not found', async () => {
+    const engine = new FlowEngine();
+    engine.context.defineProperty('a', {
+      value: { b: [{ d: [1, 2] }, { d: [3] }] },
+    });
+    const out = await (engine.context as any).resolveJsonTemplate({ x: '{{ ctx.a.missing.path }}' });
+    expect(out).toEqual({ x: undefined });
+  });
+
+  it('deep nested arrays keep nested structure (no final deep flatten)', async () => {
+    const engine = new FlowEngine();
+    engine.context.defineProperty('a', {
+      value: {
+        b: [{ e: [{ d: [1] }, { d: [2] }] }, { e: [{ d: [3, [4]] }, { d: null }] }, { e: [] }],
+      },
+    });
+    const out = await (engine.context as any).resolveJsonTemplate('{{ ctx.a.b.e.d }}');
+    expect(out).toEqual([1, 2, 3, [4]]);
+  });
+
+  it('missing branch values are ignored during aggregation', async () => {
+    const engine = new FlowEngine();
+    engine.context.defineProperty('a', {
+      value: {
+        b: [{ d: [1] }, { x: 0 }, { d: [3] }, {}],
+      },
+    });
+    const out = await (engine.context as any).resolveJsonTemplate('{{ ctx.a.b.d }}');
+    expect(out).toEqual([1, 3]);
+  });
+
+  it('non dot-only expressions remain unaffected alongside aggregation', async () => {
+    const engine = new FlowEngine();
+    engine.context.defineProperty('a', { value: { b: [{ d: [1] }, { d: [2] }] } });
+    const out = await (engine.context as any).resolveJsonTemplate('sum={{ 1 + 2 }}, arr={{ ctx.a.b.d }}');
+    expect(out).toBe('sum=3, arr=[1,2]');
+  });
+});

package/src/__tests__/provider.test.tsx

@@ -0,0 +1,28 @@
+/**
+ * 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 React from 'react';
+import { describe, expect, it } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { FlowEngine } from '../flowEngine';
+import { FlowEngineProvider, useFlowEngine } from '../provider';
+
+describe('FlowEngineProvider/useFlowEngine', () => {
+  it('throws without provider', () => {
+    const run = () => renderHook(() => useFlowEngine());
+    expect(run).toThrow(/FlowEngineProvider/);
+  });
+
+  it('returns engine within provider', () => {
+    const engine = new FlowEngine();
+    const wrapper = ({ children }: any) => <FlowEngineProvider engine={engine}>{children}</FlowEngineProvider>;
+    const { result } = renderHook(() => useFlowEngine(), { wrapper });
+    expect(result.current).toBe(engine);
+  });
+});

package/src/__tests__/renderHiddenInConfig.test.tsx

@@ -0,0 +1,91 @@
+/**
+ * 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 } from 'vitest';
+import React from 'react';
+import { render, screen, cleanup } from '@testing-library/react';
+import { FlowEngine } from '../flowEngine';
+import { FlowModel, ModelRenderMode } from '../models/flowModel';
+
+describe('FlowModel.renderHiddenInConfig', () => {
+  it('renders via renderHiddenInConfig when hidden and config enabled (React element mode, mounted)', () => {
+    class ElemModel extends FlowModel {
+      render() {
+        return <div data-testid="content">Content</div>;
+      }
+      protected renderHiddenInConfig(): React.ReactNode | undefined {
+        return <div data-testid="hidden">HiddenViaAPI</div>;
+      }
+    }
+
+    const engine = new FlowEngine();
+    const model = new ElemModel({ uid: 'elem-1', flowEngine: engine });
+
+    // runtime hidden => mounted result should be empty (no content/hidden)
+    engine.flowSettings.disable();
+    model.setHidden(true);
+    const { container, unmount, rerender } = render(model.render() as React.ReactElement);
+    expect(screen.queryByTestId('content')).toBeNull();
+    expect(screen.queryByTestId('hidden')).toBeNull();
+
+    // config enabled + hidden => should show renderHiddenInConfig result
+    engine.flowSettings.enable();
+    rerender(model.render() as React.ReactElement);
+    expect(screen.getByTestId('hidden').textContent).toBe('HiddenViaAPI');
+
+    // visible => show original render
+    model.setHidden(false);
+    rerender(model.render() as React.ReactElement);
+    expect(screen.getByTestId('content').textContent).toBe('Content');
+    unmount();
+    cleanup();
+  });
+  it('returns a render function when hidden and config enabled (RenderFunction mode)', () => {
+    class FuncModel extends FlowModel {
+      static override renderMode = ModelRenderMode.RenderFunction;
+      render() {
+        return () => <span>Cell</span>;
+      }
+      protected renderHiddenInConfig(): React.ReactNode | undefined {
+        // return a cell renderer
+        return <span>No permission</span>;
+      }
+    }
+
+    const engine = new FlowEngine();
+    engine.registerModels({ FuncModel: FuncModel });
+    const model = engine.createModel({ use: 'FuncModel' }) as FuncModel;
+
+    // runtime hidden => null
+    engine.flowSettings.disable();
+    model.setHidden(true);
+    const runtimeHidden = model.render();
+    expect(runtimeHidden).toBeNull();
+
+    // config enabled + hidden => renderHiddenInConfig (function)
+    engine.flowSettings.enable();
+    const cfgHidden = model.render();
+    expect(typeof cfgHidden).toBe('function');
+    const cellNode = (cfgHidden as any)();
+    // Allow either a React element or a plain string depending on environment/mocks
+    if (typeof cellNode === 'string') {
+      expect(cellNode).toBe('No permission');
+    } else {
+      expect(cellNode && typeof cellNode === 'object').toBe(true);
+      expect((cellNode as any).props?.children).toBe('No permission');
+    }
+
+    // visible => original render (function)
+    model.setHidden(false);
+    const visible = model.render();
+    expect(typeof visible).toBe('function');
+    const visibleNode = (visible as any)();
+    expect(visibleNode.props.children).toBe('Cell');
+  });
+});

package/src/__tests__/runjsContext.test.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 } from 'vitest';
+import {
+  RunJSContextRegistry,
+  registerDefaultMappings,
+  getRunJSDocFor,
+  createJSRunnerWithVersion,
+  FlowRunJSContext,
+} from '../runjs-context';
+import { JSRunner } from '../JSRunner';
+import type { FlowContext } from '../flowContext';
+
+describe('flowRunJSContext registry and doc', () => {
+  it('registerDefaultMappings should register v1 mapping', () => {
+    registerDefaultMappings();
+    expect(RunJSContextRegistry['resolve']('v1' as any, '*')).toBeTruthy();
+  });
+
+  it('getRunJSDocFor should pick subclass by model class name', () => {
+    const ctx: any = { model: { constructor: { name: 'JSBlockModel' } } };
+    const doc = getRunJSDocFor(ctx as any, { version: 'v1' });
+    expect(doc?.label).toMatch(/JSBlock RunJS/);
+  });
+
+  it('createJSRunnerWithVersion returns a JSRunner', async () => {
+    const stubCtx: any = {
+      model: { constructor: { name: 'JSFieldModel' } },
+      createProxy() {
+        return this;
+      },
+    };
+    const runner = createJSRunnerWithVersion.call(stubCtx, { version: 'v1' });
+    expect(runner).toBeInstanceOf(JSRunner);
+    const result = await runner.run('return 1 + 1');
+    expect(result?.success).toBe(true);
+    expect(result?.value).toBe(2);
+  });
+
+  it('default globals (window/document) should be injected for field/block contexts', async () => {
+    const stubCtx: any = {
+      model: { constructor: { name: 'JSFieldModel' } },
+      createProxy() {
+        return this;
+      },
+    };
+    const runner = createJSRunnerWithVersion.call(stubCtx, { version: 'v1' });
+    const r = await runner.run('return typeof window !== "undefined" && typeof document !== "undefined"');
+    expect(r.success && r.value).toBe(true);
+  });
+
+  // Linkage kind via __runjsKind removed; linkage scripts now run in the host model context.
+});