@nocobase/flow-engine 2.0.0-alpha.2

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');
+    });
+  });
+});