@nocobase/flow-engine 2.0.0-alpha.10

package/src/JSRunner.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 'ses';
+
+export interface JSRunnerOptions {
+  timeoutMs?: number;
+  globals?: Record<string, any>;
+  version?: string;
+}
+
+export class JSRunner {
+  private globals: Record<string, any>;
+  private timeoutMs: number;
+
+  constructor(options: JSRunnerOptions = {}) {
+    const bindWindowFn = (key: 'setTimeout' | 'clearTimeout' | 'setInterval' | 'clearInterval') => {
+      if (typeof window !== 'undefined' && typeof window[key] === 'function') {
+        return window[key].bind(window);
+      }
+      const fn = globalThis[key];
+      return typeof fn === 'function' ? fn.bind(globalThis) : fn;
+    };
+
+    this.globals = {
+      console,
+      setTimeout: bindWindowFn('setTimeout'),
+      clearTimeout: bindWindowFn('clearTimeout'),
+      setInterval: bindWindowFn('setInterval'),
+      clearInterval: bindWindowFn('clearInterval'),
+      ...(options.globals || {}),
+    };
+    this.timeoutMs = options.timeoutMs ?? 5000; // 默认 5 秒超时
+  }
+
+  /**
+   * 注册单个变量或函数
+   */
+  register(name: string, value: any): void {
+    this.globals[name] = value;
+  }
+
+  /**
+   * 异步运行代码，带错误处理和超时机制
+   */
+  async run(code: string): Promise<{
+    success: boolean;
+    value?: any;
+    error?: any;
+    timeout?: boolean;
+  }> {
+    const wrapped = `(async () => {
+      try {
+        ${code};
+      } catch (e) {
+        throw e;
+      }
+    })()`;
+
+    const compartment = new Compartment(this.globals);
+
+    try {
+      const task = compartment.evaluate(wrapped);
+      const timeoutPromise = new Promise((_resolve, reject) =>
+        setTimeout(() => reject(new Error('Execution timed out')), this.timeoutMs),
+      );
+      const result = await Promise.race([task, timeoutPromise]);
+      return { success: true, value: result };
+    } catch (err) {
+      console.error(err);
+      return {
+        success: false,
+        error: err,
+        timeout: err.message === 'Execution timed out',
+      };
+    }
+  }
+}

package/src/ReactView.tsx

@@ -0,0 +1,104 @@
+/**
+ * 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 { App, ConfigProvider } from 'antd';
+import React from 'react';
+import { Root, RootOptions, createRoot } from 'react-dom/client';
+import { FlowEngine } from './flowEngine';
+import { FlowEngineProvider } from './provider';
+
+function Provider({ config, engine, children }) {
+  return (
+    <FlowEngineProvider engine={engine}>
+      <ConfigProvider {...config}>
+        <App>{children}</App>
+      </ConfigProvider>
+    </FlowEngineProvider>
+  );
+}
+
+export class ReactView {
+  private refreshCallback: (() => void) | null = null;
+
+  constructor(private flowEngine: FlowEngine) {}
+
+  createRoot(container: HTMLElement, options: RootOptions = {}): Root {
+    const root = createRoot(container, options);
+    let currentChildren: React.ReactNode;
+
+    const doRender = () => {
+      root.render(
+        <Provider engine={this.flowEngine} config={this.flowEngine.context.antdConfig}>
+          {currentChildren}
+        </Provider>,
+      );
+    };
+
+    const flowRoot = {
+      render: (children: React.ReactNode) => {
+        currentChildren = children;
+        this.refreshCallback = doRender;
+        doRender();
+      },
+      unmount: () => {
+        this.refreshCallback = null;
+        currentChildren = null;
+        root.unmount();
+      },
+    };
+
+    return flowRoot;
+  }
+
+  // 重新渲染当前根
+  refresh() {
+    if (this.refreshCallback) {
+      this.refreshCallback();
+    }
+  }
+
+  render(children: React.ReactNode | ((root: Root) => React.ReactNode), options: any = {}) {
+    const container = document.createElement('span');
+    const { onRendered } = options;
+    let root: Root;
+
+    const renderContent = (root: Root) => {
+      const content = typeof children === 'function' ? (children as (root: Root) => React.ReactNode)(root) : children;
+      return (
+        <Provider engine={this.flowEngine} config={this.flowEngine.context.antdConfig}>
+          {content}
+        </Provider>
+      );
+    };
+
+    if (onRendered) {
+      onRendered(() => {
+        root = createRoot(container);
+        root.render(renderContent(root));
+      });
+    } else {
+      root = createRoot(container);
+      root.render(renderContent(root));
+    }
+
+    (container as any)._reactRoot = root;
+
+    return container;
+  }
+
+  onRefReady<T extends HTMLElement>(ref: React.RefObject<T>, cb: (el: T) => void, timeout = 10000) {
+    const start = Date.now();
+    function check() {
+      if (ref.current) return cb(ref.current);
+      if (Date.now() - start > timeout) return;
+      setTimeout(check, 30);
+    }
+    check();
+  }
+}

package/src/ViewScopedFlowEngine.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { FlowEngine } from './flowEngine';
+
+/**
+ * ViewScopedFlowEngine（视图作用域引擎）
+ *
+ * 设计目标：
+ * - 仅在视图（dialog/drawer/embed）作用域内隔离“模型实例表”和“事件缓存”；
+ * - 其余能力（动作/事件/模型类/资源/仓库/设置/日志/翻译等）全部直接代理到父引擎；
+ * - 使用 Proxy 实现“最小代理”，保持与父引擎的全局一致性。
+ *
+ * 注意：
+ * - 本地化的字段仅有：`_modelInstances`、`_applyFlowCache`、`executor`、`context`；
+ * - 其它字段/方法均通过 Proxy 转发到父引擎；
+ * - 这满足“同一 uid 在不同视图中互不污染（实例/缓存隔离）”与“共享全局注册/仓库”的诉求。
+ */
+export function createViewScopedEngine(parent: FlowEngine): FlowEngine {
+  const local = new FlowEngine();
+  if (parent.modelRepository) {
+    local.setModelRepository(parent.modelRepository);
+  }
+  local.context.addDelegate(parent.context);
+
+  // 默认全部代理到父引擎，只有少数字段（实例/缓存/执行器/上下文/链表指针）使用本地值
+  const localOnly = new Set<keyof FlowEngine | string>([
+    '_modelInstances',
+    '_applyFlowCache',
+    'executor',
+    'context',
+    'previousEngine',
+    'nextEngine',
+    // 栈指针维护方法需要在本地执行，而非代理到父引擎
+    'unlinkFromStack',
+    'linkAfter',
+    '_previousEngine',
+    '_nextEngine',
+  ]);
+
+  const handler: ProxyHandler<FlowEngine> = {
+    get(target, prop: string, receiver) {
+      // 本地化字段（实例/缓存/执行器/上下文）
+      if (localOnly.has(prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      // 其它一律代理到父引擎
+      const value = Reflect.get(parent, prop, receiver);
+      // 某些依赖 this 的方法需要绑定到父引擎实例
+      if (prop === 'registerModels' && typeof value === 'function') {
+        return value.bind(parent);
+      }
+      return value;
+    },
+    set(target, prop: string, value: unknown) {
+      if (localOnly.has(prop)) {
+        return Reflect.set(target, prop, value);
+      }
+      return Reflect.set(parent, prop, value);
+    },
+    has(target, prop: string) {
+      return prop in target || prop in parent;
+    },
+  };
+
+  // 建立 previous/next 链表指针，表示视图栈关系
+  local.linkAfter(parent);
+  return new Proxy(local, handler) as FlowEngine;
+}

package/src/__tests__/ElementProxy.test.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 } from 'vitest';
+import { ElementProxy } from '../ElementProxy';
+
+describe('ElementProxy', () => {
+  it('proxies element methods and properties', () => {
+    const el = document.createElement('div');
+    const proxy: any = new ElementProxy(el);
+
+    proxy.setAttribute('data-x', '1');
+    expect(el.getAttribute('data-x')).toBe('1');
+
+    proxy.id = 'abc';
+    expect(el.id).toBe('abc');
+    expect(proxy.id).toBe('abc');
+  });
+
+  it('sanitizes innerHTML/outerHTML setters', () => {
+    const el = document.createElement('div');
+    const proxy: any = new ElementProxy(el);
+
+    proxy.innerHTML = '<img src=x onerror=alert(1)><span>ok</span>';
+    expect(proxy.innerHTML).toContain('<span>ok</span>');
+    expect(proxy.innerHTML).not.toContain('onerror');
+
+    const container = document.createElement('div');
+    container.appendChild(el);
+    proxy.outerHTML = '<div onload=1>unsafe</div>';
+    expect(container.innerHTML).toContain('unsafe');
+    expect(container.innerHTML).not.toContain('onload');
+  });
+
+  it('appendChild accepts string or HTMLElement', () => {
+    const el = document.createElement('div');
+    const proxy: any = new ElementProxy(el);
+    proxy.appendChild('hello');
+    const span = document.createElement('span');
+    span.textContent = 'world';
+    proxy.appendChild(span);
+    expect(el.textContent).toContain('hello');
+    expect(el.querySelector('span')?.textContent).toBe('world');
+  });
+});

package/src/__tests__/JSRunner.test.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 { JSRunner } from '../JSRunner';
+
+describe('JSRunner', () => {
+  it('should run simple code successfully', async () => {
+    const runner = new JSRunner();
+    const result = await runner.run(`
+      const x = 10;
+      return x + 5;    
+    `);
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(15);
+  });
+
+  it('should handle syntax errors in the code', async () => {
+    const runner = new JSRunner();
+    const result = await runner.run('const x = 10 x + 5;'); // Syntax error
+    expect(result.success).toBe(false);
+    expect(result.error).toBeInstanceOf(SyntaxError);
+  });
+
+  it('should handle runtime errors in the code', async () => {
+    const runner = new JSRunner();
+    const result = await runner.run(`
+      const x = 10;
+      throw new Error('Test error');
+    `);
+    expect(result.success).toBe(false);
+    expect(result.error).toBeInstanceOf(Error);
+    expect(result.error.message).toBe('Test error');
+  });
+
+  it('should handle timeout errors', async () => {
+    const runner = new JSRunner({ timeoutMs: 100 }); // Set a short timeout
+    const result = await runner.run(`
+      await new Promise(resolve => setTimeout(resolve, 500)); // Exceeds timeout
+      return 'Done';
+    `);
+    console.log(result);
+    expect(result.success).toBe(false);
+    expect(result.timeout).toBe(true);
+    expect(result.error.message).toBe('Execution timed out');
+  });
+
+  it('should use registered globals', async () => {
+    const runner = new JSRunner();
+    runner.register('globalVar', 42);
+    const result = await runner.run(`
+      return globalVar + 8;
+    `);
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(50);
+  });
+
+  it('should handle code with async/await', async () => {
+    const runner = new JSRunner();
+    const result = await runner.run(`
+      const fetchData = async () => {
+        return new Promise(resolve => setTimeout(() => resolve(100), 50));
+      };
+      const data = await fetchData();
+      return data + 50;
+    `);
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(150);
+  });
+
+  it('should handle empty code', async () => {
+    const runner = new JSRunner();
+    const result = await runner.run('');
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(undefined);
+  });
+
+  it('should handle code returning undefined explicitly', async () => {
+    const runner = new JSRunner();
+    const result = await runner.run(`
+      const x = 10;
+      return undefined;
+    `);
+    expect(result.success).toBe(true);
+    expect(result.value).toBe(undefined);
+  });
+});

package/src/__tests__/ReactView.test.tsx

@@ -0,0 +1,63 @@
+/**
+ * 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 { ReactView } from '../ReactView';
+import { FlowEngine } from '../flowEngine';
+
+describe('ReactView', () => {
+  it('createRoot returns object with render/unmount and refresh re-renders', () => {
+    const engine = new FlowEngine();
+    const view = new ReactView(engine);
+    const container = document.createElement('div');
+    const root = view.createRoot(container);
+    expect(typeof root.render).toBe('function');
+    expect(typeof root.unmount).toBe('function');
+    root.render(<div id="x">A</div>);
+    // refresh should not throw
+    view.refresh();
+    root.unmount();
+  });
+
+  it('render returns a DOM node with _reactRoot and supports onRendered hook', () => {
+    const engine = new FlowEngine();
+    const view = new ReactView(engine);
+    let ready: any;
+    const node = view.render(<span>Hi</span>, {
+      onRendered: (cb: any) => {
+        ready = cb;
+      },
+    });
+    expect(ready).toBeTypeOf('function');
+    // run the deferred render
+    ready();
+    // do not assert internal implementation detail (_reactRoot)
+    // just ensure the callback can be invoked without errors
+  });
+
+  it('onRefReady calls callback when ref becomes available', async () => {
+    const engine = new FlowEngine();
+    const view = new ReactView(engine);
+    const ref = { current: null } as any;
+    let called = false;
+    setTimeout(() => (ref.current = document.createElement('div')));
+    await new Promise<void>((resolve) => {
+      view.onRefReady(
+        ref,
+        () => {
+          called = true;
+          resolve();
+        },
+        200,
+      );
+    });
+    expect(called).toBe(true);
+  });
+});

package/src/__tests__/context-path-proxy.test.ts

@@ -0,0 +1,35 @@
+/**
+ * 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';
+
+describe('createContextProxy', () => {
+  it('should return correct string template for root', () => {
+    const ctx = ContextPathProxy.create();
+    expect(ctx.toString()).toBe('{{ctx}}');
+    expect(`${ctx}`).toBe('{{ctx}}');
+  });
+
+  it('should support nested property access and string template', () => {
+    const ctx = ContextPathProxy.create();
+    expect(`${ctx.steps}`).toBe('{{ctx.steps}}');
+    expect(`${ctx.steps.step1}`).toBe('{{ctx.steps.step1}}');
+    expect(`${ctx.steps.step1.result}`).toBe('{{ctx.steps.step1.result}}');
+  });
+
+  it('should support valueOf for implicit conversion', () => {
+    const ctx = ContextPathProxy.create();
+    expect(ctx.steps.step1.result == '{{ctx.steps.step1.result}}').toBe(true);
+  });
+
+  it('should return undefined for symbol property', () => {
+    const ctx = ContextPathProxy.create();
+    expect((ctx as any)[Symbol.toPrimitive]).toBeUndefined();
+  });
+});

package/src/__tests__/flow-engine.test.ts

@@ -0,0 +1,189 @@
+/**
+ * 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 { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FlowEngine } from '../flowEngine';
+import { FlowModel } from '../models';
+import type { IFlowModelRepository } from '../types';
+
+class BaseModel extends FlowModel {}
+class SubModelA extends BaseModel {}
+class SubModelB extends BaseModel {}
+class SubModelC extends SubModelA {}
+
+describe('FlowEngine', () => {
+  let engine: FlowEngine;
+
+  beforeEach(() => {
+    engine = new FlowEngine();
+    engine.registerModels({
+      BaseModel,
+      SubModelA,
+      SubModelB,
+      SubModelC,
+    });
+  });
+
+  it('getModelClass should return correct class', () => {
+    expect(engine.getModelClass('BaseModel')).toBe(BaseModel);
+    expect(engine.getModelClass('SubModelA')).toBe(SubModelA);
+    expect(engine.getModelClass('NotExist')).toBeUndefined();
+  });
+
+  it('getSubclassesOf should return all subclasses', () => {
+    const result = engine.getSubclassesOf(BaseModel);
+    expect(result.has('BaseModel')).toBe(false);
+    expect(result.has('SubModelA')).toBe(true);
+    expect(result.has('SubModelB')).toBe(true);
+    expect(result.has('SubModelC')).toBe(true);
+  });
+
+  it('getSubclassesOf should support filter', () => {
+    const result = engine.getSubclassesOf(BaseModel, (ModelClass, name) => name.startsWith('SubModel'));
+    expect(result.has('BaseModel')).toBe(false);
+    expect(result.has('SubModelA')).toBe(true);
+    expect(result.has('SubModelB')).toBe(true);
+    expect(result.has('SubModelC')).toBe(true);
+  });
+
+  it('findModelClass should find by predicate', () => {
+    const found = engine.findModelClass((name) => name === 'SubModelB');
+    expect(found).toBeDefined();
+    expect(found?.[0]).toBe('SubModelB');
+    expect(found?.[1]).toBe(SubModelB);
+  });
+
+  it('filterModelClassByParent should return correct subclasses', () => {
+    const result = engine.filterModelClassByParent(SubModelA);
+    expect(result.has('SubModelA')).toBe(false);
+    expect(result.has('SubModelC')).toBe(true);
+    expect(result.has('BaseModel')).toBe(false);
+    expect(result.has('SubModelB')).toBe(false);
+  });
+
+  it('registerAction/getAction should work', () => {
+    engine.registerActions({
+      testAction: {
+        name: 'testAction',
+        handler: vi.fn(),
+      },
+    });
+    const action = engine.getAction('testAction');
+    expect(action).toBeDefined();
+    expect(action?.name).toBe('testAction');
+  });
+
+  it('registerModels should overwrite existing model', () => {
+    class NewBaseModel extends FlowModel {}
+    engine.registerModels({ BaseModel: NewBaseModel });
+    expect(engine.getModelClass('BaseModel')).toBe(NewBaseModel);
+  });
+
+  describe('loadOrCreateModel', () => {
+    class MockFlowModelRepository implements IFlowModelRepository {
+      // 使用可配置返回值，便于不同用例控制 findOne 行为
+      findOneResult: any = null;
+      save = vi.fn(async (model: FlowModel) => ({ success: true, uid: model.uid }));
+      async findOne() {
+        // 返回深拷贝，避免被测试过程修改
+        return this.findOneResult ? JSON.parse(JSON.stringify(this.findOneResult)) : null;
+      }
+      async destroy() {
+        return true;
+      }
+      async move() {}
+    }
+
+    let repo: MockFlowModelRepository;
+
+    beforeEach(() => {
+      repo = new MockFlowModelRepository();
+      engine.setModelRepository(repo);
+    });
+
+    it('should set as object subModel when subType=object even if subKey="array" (regression for subType check)', async () => {
+      // 父模型
+      const parent = engine.createModel({ uid: 'p1', use: 'FlowModel' });
+
+      // 仓库返回数据：subKey 恰好为 'array'，但 subType 是 'object'
+      repo.findOneResult = {
+        uid: 'c1',
+        use: 'FlowModel',
+        parentId: parent.uid,
+        subKey: 'array',
+        subType: 'object',
+      };
+
+      const child = await engine.loadOrCreateModel({
+        uid: 'c1',
+        use: 'FlowModel',
+        parentId: parent.uid,
+        subKey: 'array',
+        subType: 'object',
+      });
+
+      expect(child).toBeTruthy();
+      // 关键断言：应按 object 模式挂载，而不是数组
+      const mounted = (parent.subModels as any)['array'];
+      expect(Array.isArray(mounted)).toBe(false);
+      expect(mounted?.uid).toBe('c1');
+      expect(mounted).toBe(child);
+    });
+
+    it('should add to array subModels when subType=array', async () => {
+      const parent = engine.createModel({ uid: 'p2', use: 'FlowModel' });
+
+      repo.findOneResult = {
+        uid: 'c2',
+        use: 'FlowModel',
+        parentId: parent.uid,
+        subKey: 'items',
+        subType: 'array',
+      };
+
+      const child = await engine.loadOrCreateModel({
+        uid: 'c2',
+        use: 'FlowModel',
+        parentId: parent.uid,
+        subKey: 'items',
+        subType: 'array',
+      });
+
+      expect(child).toBeTruthy();
+      const arr = (parent.subModels as any)['items'];
+      expect(Array.isArray(arr)).toBe(true);
+      expect(arr.length).toBe(1);
+      expect(arr[0].uid).toBe('c2');
+    });
+
+    it('should create and save when repo has no data, then mount under parent accordingly (object case)', async () => {
+      const parent = engine.createModel({ uid: 'p3', use: 'FlowModel' });
+
+      // 仓库查无数据
+      repo.findOneResult = null;
+
+      const child = await engine.loadOrCreateModel({
+        uid: 'c3',
+        use: 'FlowModel',
+        parentId: parent.uid,
+        subKey: 'info',
+        subType: 'object',
+      });
+
+      expect(child).toBeTruthy();
+      // 应触发一次保存（create 后会调用 save）
+      expect(repo.save).toHaveBeenCalledTimes(1);
+
+      // 正确以对象形式挂载
+      const mounted = (parent.subModels as any)['info'];
+      expect(Array.isArray(mounted)).toBe(false);
+      expect(mounted?.uid).toBe('c3');
+    });
+  });
+});