@nocobase/flow-engine 2.0.0-alpha.2

package/src/__tests__/viewScopedFlowEngine.test.ts

@@ -0,0 +1,212 @@
+/**
+ * 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.
+ */
+
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { APIClient as SDKApiClient } from '@nocobase/sdk';
+import { FlowEngine } from '../flowEngine';
+import { createViewScopedEngine } from '../ViewScopedFlowEngine';
+import { FlowModel } from '../models';
+
+describe('ViewScopedFlowEngine', () => {
+  it('shares global actions/events and model classes with parent', async () => {
+    const parent = new FlowEngine();
+    parent.registerActions({
+      ping: {
+        name: 'ping',
+        handler: () => 'pong',
+      },
+    });
+    const child = createViewScopedEngine(parent);
+
+    // child can read parent's action
+    expect(child.getAction('ping')).toBeDefined();
+
+    // registering via child should affect parent
+    child.registerActions({ pong: { name: 'pong', handler: () => 'ok' } });
+    expect(parent.getAction('pong')).toBeDefined();
+
+    // model class resolution is proxied
+    class TestModel extends FlowModel {}
+    parent.registerModels({ TestModel });
+    expect(child.getModelClass('TestModel')).toBeDefined();
+  });
+
+  it('isolates model instances map by default', () => {
+    const parent = new FlowEngine();
+    const child = createViewScopedEngine(parent);
+
+    class TestModel extends FlowModel {}
+
+    const uid = 'same-uid';
+    const pm = parent.createModel<TestModel>({ use: TestModel, uid });
+    const cm = child.createModel<TestModel>({ use: TestModel, uid });
+
+    expect(pm).not.toBe(cm);
+    // 默认 getModel 仅在当前作用域查找
+    expect(parent.getModel(uid)).toBe(pm);
+    expect(child.getModel(uid)).toBe(cm);
+  });
+
+  it('isolates auto flow cache across engines with identical model uid', async () => {
+    const parent = new FlowEngine();
+    const child = createViewScopedEngine(parent);
+
+    let count = 0;
+    class CounterModel extends FlowModel {}
+    CounterModel.registerFlow({
+      key: 'autoCounter',
+      steps: {
+        s1: {
+          handler: async () => {
+            count += 1;
+            return count;
+          },
+        },
+      },
+    });
+
+    const uid = 'model-uid-cache';
+    const pm = parent.createModel<CounterModel>({ use: CounterModel, uid });
+    const cm = child.createModel<CounterModel>({ use: CounterModel, uid });
+
+    await pm.applyAutoFlows();
+    expect(count).toBe(1);
+
+    // If cache was shared, the next call would hit cache and not increment.
+    await cm.applyAutoFlows();
+    expect(count).toBe(2);
+  });
+
+  it('creates resources using parent registry but binds to scoped context by default', () => {
+    const parent = new FlowEngine();
+    const child = createViewScopedEngine(parent);
+    // mock minimal api to satisfy ctx.auth and related getters
+    const api = new SDKApiClient({ storageType: 'memory' });
+    api.auth.role = 'guest';
+    api.auth.locale = 'en-US';
+    api.auth.token = 't';
+    parent.context.defineProperty('api', { value: api });
+
+    // use built-in FlowResource class name
+    const res = child.createResource('FlowResource');
+    // resource context is a wrapper that delegates to child context
+    child.context.defineProperty('foo', { value: 123 });
+    expect((res as any).context.foo).toBe(123);
+  });
+
+  it('uses local context and delegates to parent context', () => {
+    const parent = new FlowEngine();
+    const child = createViewScopedEngine(parent);
+    // In runtime, context.api is always provided by host app.
+    // Provide a minimal mock here to avoid incidental getter access (e.g. ctx.auth) from throwing.
+    const api = new SDKApiClient({ storageType: 'memory' });
+    api.auth.role = 'guest';
+    api.auth.locale = 'en-US';
+    api.auth.token = 't';
+    parent.context.defineProperty('api', { value: api });
+    const parentCtx = parent.context;
+    const childCtx = child.context;
+    expect(Object.is(childCtx, parentCtx)).toBe(true);
+    // define a value on parent context
+    parent.context.defineProperty('foo', { value: 42 });
+    // child context should be able to read via delegate chain
+    expect((child.context as any).foo).toBe(42);
+  });
+
+  it('delegates saveModel to parent (concurrency gate sharing)', async () => {
+    const parent = new FlowEngine();
+    const child = createViewScopedEngine(parent);
+    const spy = vi.spyOn(parent, 'saveModel').mockResolvedValueOnce(true);
+    class T extends FlowModel {}
+    const m = child.createModel<T>({ use: T });
+    await child.saveModel(m);
+    expect(spy).toHaveBeenCalledOnce();
+  });
+
+  it('stacks multiple scoped engines on tail (linkAfter attaches to bottom)', () => {
+    const root = new FlowEngine();
+    const c1 = createViewScopedEngine(root);
+    const c2 = createViewScopedEngine(root);
+
+    // child pointers point back correctly
+    expect(c1.previousEngine).toBe(root);
+    expect(c2.previousEngine?.previousEngine).toBe(root);
+
+    // chain length from root is 2 (two scoped engines)
+    let count = 0;
+    let p = root.nextEngine;
+    while (p) {
+      count += 1;
+      p = p.nextEngine;
+    }
+    expect(count).toBe(2);
+  });
+
+  it('supports stacking when anchoring from nested child (still appends to bottom)', () => {
+    const root = new FlowEngine();
+    const c1 = createViewScopedEngine(root);
+    const c2 = createViewScopedEngine(c1); // pass child as anchor
+
+    expect(c1.previousEngine).toBe(root);
+    expect(c2.previousEngine?.previousEngine).toBe(root);
+  });
+
+  it('global model lookup traverses from top to root across stack', () => {
+    const root = new FlowEngine();
+    const c1 = createViewScopedEngine(root);
+    const c2 = createViewScopedEngine(root);
+
+    class TM extends FlowModel {}
+    const uid = 'same-uid-global-lookup';
+    const mRoot = root.createModel<TM>({ use: TM, uid });
+    const m1 = c1.createModel<TM>({ use: TM, uid });
+    const m2 = c2.createModel<TM>({ use: TM, uid });
+
+    // sanity: each scope returns its own when not global
+    expect(root.getModel(uid)).toBe(mRoot);
+    expect(c1.getModel(uid)).toBe(m1);
+    expect(c2.getModel(uid)).toBe(m2);
+
+    // global search from any engine hits the top-most engine's instance first
+    expect(root.getModel(uid, true)).toBe(m2);
+    expect(c1.getModel(uid, true)).toBe(m2);
+    expect(c2.getModel(uid, true)).toBe(m2);
+  });
+
+  it('unlinkFromStack detaches only the top engine', () => {
+    const root = new FlowEngine();
+    const c1 = createViewScopedEngine(root);
+    const c2 = createViewScopedEngine(root);
+
+    class TM extends FlowModel {}
+    const uid = 'unlink-top-only';
+    c1.createModel<TM>({ use: TM, uid });
+    const m2 = c2.createModel<TM>({ use: TM, uid });
+
+    // before unlink: top is c2
+    expect(root.getModel(uid, true)).toBe(m2);
+
+    // unlink the top scoped engine
+    c2.unlinkFromStack();
+
+    // After unlink, root should have only one child (c1). Its next should be undefined.
+    expect(root.nextEngine?.nextEngine).toBeUndefined();
+    expect(root.nextEngine?.previousEngine).toBe(root);
+
+    // global lookup should now resolve to c1's instance
+    const resolved = root.getModel<TM>(uid, true);
+    expect(resolved?.flowEngine.previousEngine).toBe(root);
+  });
+});

package/src/acl/Acl.tsx

@@ -0,0 +1,109 @@
+/**
+ * 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 { FlowModel } from '../models/flowModel';
+import { FlowEngine } from '../flowEngine';
+
+interface CheckOptions {
+  dataSourceKey: string;
+  resourceName: string;
+  actionName: string;
+  fields?: string[];
+}
+
+export class ACL {
+  private dataSources: Record<string, any> = {};
+  private loaded = false;
+  private loadingPromise: Promise<void> | null = null;
+
+  constructor(private flowEngine: FlowEngine) {}
+
+  async load() {
+    if (this.loaded) return;
+
+    if (!this.loadingPromise) {
+      this.loadingPromise = (async () => {
+        const { data } = await this.flowEngine.context.api.request({
+          url: 'roles:check',
+        });
+        this.dataSources = data || {};
+        this.loaded = true;
+      })();
+    }
+
+    await this.loadingPromise;
+  }
+
+  getActionAlias(actionName: string) {
+    return this.dataSources.data?.actionAlias?.[actionName] || actionName;
+  }
+
+  inResources(resourceName: string) {
+    return this.dataSources.data?.resources?.includes?.(resourceName);
+  }
+  getResourceActionParams(resourceName, actionName) {
+    const actionAlias = this.getActionAlias(actionName);
+    return (
+      this.dataSources.data?.actions?.[`${resourceName}:${actionAlias}`] || this.dataSources.data?.actions?.[actionName]
+    );
+  }
+
+  getStrategyActionParams(actionName: string) {
+    const actionAlias = this.getActionAlias(actionName);
+    const strategyAction = this.dataSources.data?.strategy?.actions?.find((action) => {
+      const [value] = action.split(':');
+      return value === actionAlias;
+    });
+    return strategyAction ? {} : null;
+  }
+
+  parseAction(options: CheckOptions) {
+    const { resourceName, actionName, dataSourceKey = 'main' } = options;
+    const targetResource =
+      resourceName?.includes('.') &&
+      this.flowEngine.context.dataSourceManager
+        .getDataSource(dataSourceKey)
+        .collectionManager.getAssociation(resourceName)?.target;
+
+    if (this.inResources(targetResource)) {
+      return this.getResourceActionParams(targetResource, actionName);
+    }
+    if (this.inResources(resourceName)) {
+      return this.getResourceActionParams(resourceName, actionName);
+    }
+    return this.getStrategyActionParams(actionName);
+  }
+
+  parseField(options: CheckOptions) {
+    const { fields } = options;
+    const params = this.parseAction(options);
+    const whitelist = []
+      .concat(params?.whitelist || [])
+      .concat(params?.fields || [])
+      .concat(params?.appends || []);
+    if (params && !Object.keys(params).length) {
+      return true;
+    }
+    const allowed = whitelist.includes(fields[0]);
+    return allowed;
+  }
+
+  async aclCheck(options: CheckOptions): Promise<boolean> {
+    await this.load();
+    const { data } = this.dataSources;
+    const { allowAll } = data;
+    if (allowAll) {
+      return true;
+    }
+    if (options.fields) {
+      return this.parseField(options);
+    }
+    return this.parseAction(options);
+  }
+}

package/src/acl/__tests__/Acl.test.tsx

@@ -0,0 +1,72 @@
+/**
+ * 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 { FlowEngine } from '../../flowEngine';
+import { ACL } from '../Acl';
+
+describe('ACL', () => {
+  const makeEngine = (payload: any) => {
+    const engine = new FlowEngine();
+    // mock api.request
+    (engine.context as any).api = {
+      request: vi.fn().mockResolvedValue({ data: payload }),
+    } as any;
+    return engine;
+  };
+
+  it('loads data once and checks alias/resources/actions', async () => {
+    const payload = {
+      data: {
+        allowAll: false,
+        actionAlias: { remove: 'destroy' },
+        resources: ['posts'],
+        actions: {
+          'posts:destroy': { whitelist: ['title'] },
+        },
+        strategy: { actions: ['destroy'] },
+      },
+    };
+    const engine = makeEngine(payload);
+    const acl = new ACL(engine);
+    await acl.load();
+    expect(acl.getActionAlias('remove')).toBe('destroy');
+    expect(acl.inResources('posts')).toBe(true);
+    expect(acl.getResourceActionParams('posts', 'remove')).toEqual({ whitelist: ['title'] });
+    expect(acl.getStrategyActionParams('remove')).toEqual({});
+  });
+
+  it('aclCheck uses parseField when fields present and allowAll=false', async () => {
+    const payload = {
+      data: {
+        allowAll: false,
+        actionAlias: {},
+        resources: ['posts'],
+        actions: { 'posts:update': { whitelist: ['title'] } },
+        strategy: { actions: [] },
+      },
+    };
+    const engine = makeEngine(payload);
+    const acl = new ACL(engine);
+    const ok = await acl.aclCheck({
+      dataSourceKey: 'main',
+      resourceName: 'posts',
+      actionName: 'update',
+      fields: ['title'],
+    });
+    expect(ok).toBe(true);
+    const notOk = await acl.aclCheck({
+      dataSourceKey: 'main',
+      resourceName: 'posts',
+      actionName: 'update',
+      fields: ['body'],
+    });
+    expect(notOk).toBe(false);
+  });
+});

package/src/action-registry/BaseActionRegistry.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+
+/**
+ * 通用的 Action 注册表基类（abstract）。
+ * 抽取共享的注册逻辑，具体查询由子类实现。
+ */
+import type { ActionDefinition } from '../types';
+import type { FlowModel } from '../models';
+import type { FlowContext, FlowRuntimeContext } from '../flowContext';
+
+export abstract class BaseActionRegistry<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext> {
+  protected actions: Map<string, ActionDefinition<TModel, TCtx>> = new Map();
+
+  // 子类可覆盖：当动作被注册（含覆盖）时触发，可用于缓存失效等
+  protected onActionRegistered(): void {}
+
+  registerActions(defs: Record<string, ActionDefinition<TModel, TCtx>>): void {
+    for (const [, def] of Object.entries(defs || {})) {
+      this.registerAction(def);
+    }
+  }
+
+  registerAction(def: ActionDefinition<TModel, TCtx>): void {
+    if (!def?.name) throw new Error('Action must have a name.');
+    if (this.actions.has(def.name)) {
+      console.warn(`Action '${def.name}' is already registered. It will be overwritten.`);
+    }
+    this.actions.set(def.name, def);
+    this.onActionRegistered();
+  }
+
+  abstract getAction<T extends FlowModel = FlowModel, CTX extends FlowContext = FlowRuntimeContext<T>>(
+    name: string,
+  ): ActionDefinition<T, CTX> | undefined;
+  abstract getActions<T extends FlowModel = FlowModel, CTX extends FlowContext = FlowRuntimeContext<T>>(): Map<
+    string,
+    ActionDefinition<T, CTX>
+  >;
+}

package/src/action-registry/EngineActionRegistry.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+
+/**
+ * 全局 action 注册表（EngineActionRegistry）。
+ * 负责全局（FlowEngine 维度）动作的注册与查询。
+ */
+import type { FlowModel } from '../models';
+import type { ActionDefinition } from '../types';
+import type { FlowContext, FlowRuntimeContext } from '../flowContext';
+import { BaseActionRegistry } from './BaseActionRegistry';
+
+export class EngineActionRegistry extends BaseActionRegistry {
+  getAction<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowRuntimeContext<TModel>>(
+    name: string,
+  ): ActionDefinition<TModel, TCtx> | undefined {
+    return this.actions.get(name);
+  }
+
+  getActions<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowRuntimeContext<TModel>>(): Map<
+    string,
+    ActionDefinition<TModel, TCtx>
+  > {
+    return new Map(this.actions) as Map<string, ActionDefinition<TModel, TCtx>>;
+  }
+}

package/src/action-registry/ModelActionRegistry.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.
+ */
+
+/**
+ * 模型类级动作注册表（每个 FlowModel 子类一个）。
+ * - 仅维护“当前类自有”的动作；
+ * - 通过父类注册表实现继承合并，并在本类内部做缓存；
+ * - 内部有查询缓存，避免重复计算。
+ */
+import type { ActionDefinition } from '../types';
+import type { FlowModel } from '../models';
+import type { FlowContext } from '../flowContext';
+import { BaseActionRegistry } from './BaseActionRegistry';
+
+export class ModelActionRegistry extends BaseActionRegistry<FlowModel, FlowContext> {
+  private readonly modelClass: typeof FlowModel;
+  private readonly parentRegistry: ModelActionRegistry | null;
+  // 本类变更标记（变更即更新引用，用于缓存命中判断）
+  private changeMarker: object = {};
+  // 合并缓存：父类合并快照引用 + 本类标记 + 合并后的 Map
+  private mergedCache?: {
+    parentSnapshot?: Map<string, ActionDefinition>;
+    localMarker: object;
+    mergedMap: Map<string, ActionDefinition>;
+  };
+
+  constructor(modelClass: typeof FlowModel, parentRegistry?: ModelActionRegistry | null) {
+    super();
+    this.modelClass = modelClass;
+    this.parentRegistry = parentRegistry ?? null;
+  }
+
+  // 标记本类有变更（用于缓存命中判断）
+  onActionRegistered() {
+    this.changeMarker = {};
+  }
+
+  /**
+   * 获取“包含继承”的合并动作（父 → 子），内部带缓存。
+   */
+  getActions<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>(): Map<
+    string,
+    ActionDefinition<TModel, TCtx>
+  > {
+    const parentMap = this.parentRegistry?.getActions<TModel>();
+    if (
+      this.mergedCache &&
+      this.mergedCache.parentSnapshot === parentMap &&
+      this.mergedCache.localMarker === this.changeMarker
+    ) {
+      return this.mergedCache.mergedMap as Map<string, ActionDefinition<TModel, TCtx>>;
+    }
+    const mergedMap = new Map<string, ActionDefinition>(parentMap ?? []);
+    for (const [k, v] of this.actions) mergedMap.set(k, v);
+    this.mergedCache = { parentSnapshot: parentMap, localMarker: this.changeMarker, mergedMap };
+    return mergedMap as Map<string, ActionDefinition<TModel, TCtx>>;
+  }
+
+  /**
+   * 解析指定名称的动作（优先本类，未命中递归父类）。
+   */
+  getAction<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext>(
+    name: string,
+  ): ActionDefinition<TModel, TCtx> | undefined {
+    const own = this.actions.get(name);
+    if (own) return own as ActionDefinition<TModel, TCtx>;
+    return this.parentRegistry?.getAction(name) as ActionDefinition<TModel, TCtx> | undefined;
+  }
+}

package/src/action-registry/__tests__/engineActionRegistry.test.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 { EngineActionRegistry } from '../EngineActionRegistry';
+
+describe('EngineActionRegistry', () => {
+  it('registerAction/getAction and duplicate detection', () => {
+    const reg = new EngineActionRegistry();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const handler1 = vi.fn();
+    const handler2 = vi.fn();
+
+    reg.registerActions({
+      a: { name: 'a', handler: handler1 },
+    });
+    expect(reg.getAction('a')?.name).toBe('a');
+    expect(reg.getAction('a')?.handler).toBe(handler1);
+
+    // Registering duplicate action should warn and override
+    reg.registerActions({ a: { name: 'a', handler: handler2 } });
+    expect(warnSpy).toHaveBeenCalledWith("Action 'a' is already registered. It will be overwritten.");
+    expect(reg.getAction('a')?.handler).toBe(handler2);
+
+    warnSpy.mockRestore();
+  });
+
+  it('getActions returns a copy (not affecting registry)', () => {
+    const reg = new EngineActionRegistry();
+    reg.registerActions({ base: { name: 'base', handler: () => {} } });
+    const map = reg.getActions();
+    map.set('hijack', { name: 'hijack', handler: () => {} });
+    expect(reg.getAction('hijack')).toBeUndefined();
+    expect(reg.getAction('base')).toBeDefined();
+  });
+});