@nocobase/flow-engine 2.0.0-alpha.2

package/src/data-source/jioToJoiSchema.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 Joi from 'joi';
+
+type JioType = 'string' | 'number' | 'array' | 'boolean' | 'any';
+
+interface JioRule {
+  name: string;
+  args?: any;
+}
+
+export function jioToJoiSchema<T extends JioType>(jioConfig: {
+  type: T;
+  rules?: JioRule[];
+}): T extends 'string'
+  ? Joi.StringSchema
+  : T extends 'number'
+    ? Joi.NumberSchema
+    : T extends 'array'
+      ? Joi.ArraySchema
+      : T extends 'boolean'
+        ? Joi.BooleanSchema
+        : Joi.AnySchema {
+  let schema: any;
+
+  // 1️⃣ 创建基础 schema
+  switch (jioConfig.type) {
+    case 'string':
+      schema = Joi.string();
+      break;
+    case 'number':
+      schema = Joi.number();
+      break;
+    case 'array':
+      schema = Joi.array();
+      break;
+    case 'boolean':
+      schema = Joi.boolean();
+      break;
+    default:
+      schema = Joi.any();
+      break;
+  }
+  const getArgs = (ruleName: string, args: any) => {
+    if (!args || Object.keys(args).length === 0) return [];
+
+    if (Array.isArray(args)) return args;
+
+    if (ruleName === 'email') {
+      const emailArgs = { ...args };
+      if (emailArgs.tlds?.allow === true) {
+        emailArgs.tlds.allow = false;
+      } else if (!emailArgs.tlds) {
+        emailArgs.tlds = { allow: false };
+      }
+      return [emailArgs];
+    }
+    if (['length', 'min', 'max'].includes(ruleName)) {
+      return [args.limit];
+    }
+    if (ruleName === 'pattern') {
+      const regex = args?.regex;
+      if (regex instanceof RegExp) {
+        return [regex];
+      } else {
+        return [new RegExp(regex)];
+      }
+    }
+    const values = Object.values(args);
+    return values.length ? values : [];
+  };
+
+  let hasRequired = false;
+
+  // 3️⃣ 遍历规则并动态调用 Joi 方法
+  jioConfig.rules?.forEach((rule) => {
+    const { name, args } = rule;
+    if (name === 'required') hasRequired = true;
+    if (typeof schema[name] === 'function') {
+      try {
+        schema = schema[name](...getArgs(name, args));
+      } catch (err) {
+        console.warn(`调用 Joi 方法 ${name} 失败:`, err);
+      }
+    } else {
+      console.warn(`Joi schema 上不存在方法: ${name}`);
+    }
+  });
+
+  // 4️⃣ 如果没有 required，默认可选并允许空字符串
+  if (!hasRequired) {
+    schema = schema.optional().allow('');
+  }
+
+  return schema;
+}

package/src/decorators/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+export { largeField } from './largeField';

package/src/decorators/largeField.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+export function largeField() {
+  return function (target: any) {
+    target.isLargeField = true;
+  };
+}

package/src/emitter.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+
+export class Emitter {
+  private events: Record<string, Array<(...args: any[]) => void>> = {};
+  private paused = false;
+
+  // TODO: this was used only by replaceModel, better find a new approach and remove this
+  setPaused(paused: boolean) {
+    this.paused = paused;
+  }
+
+  on(event: string, callback: (...args: any[]) => void) {
+    (this.events[event] ||= []).push(callback);
+  }
+
+  off(event: string, callback: (...args: any[]) => void) {
+    this.events[event] = (this.events[event] || []).filter((fn) => fn !== callback);
+  }
+
+  emit(event: string, ...args: any[]) {
+    if (this.paused) {
+      return;
+    }
+    (this.events[event] || []).forEach((fn) => fn(...args));
+  }
+}

package/src/event-registry/BaseEventRegistry.ts

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

package/src/event-registry/EngineEventRegistry.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+
+/**
+ * 全局事件注册表（EngineEventRegistry）。
+ * 负责全局（FlowEngine 维度）事件的注册与查询。
+ */
+import type { FlowModel } from '../models';
+import type { EventDefinition } from '../types';
+import { BaseEventRegistry } from './BaseEventRegistry';
+
+export class EngineEventRegistry extends BaseEventRegistry {
+  getEvent<TModel extends FlowModel = FlowModel>(name: string): EventDefinition<TModel> | undefined {
+    return this.events.get(name) as EventDefinition<TModel> | undefined;
+  }
+
+  getEvents<TModel extends FlowModel = FlowModel>(): Map<string, EventDefinition<TModel>> {
+    return new Map(this.events);
+  }
+}

package/src/event-registry/ModelEventRegistry.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { EventDefinition } from '../types';
+import type { FlowModel } from '../models';
+import { BaseEventRegistry } from './BaseEventRegistry';
+
+export class ModelEventRegistry extends BaseEventRegistry {
+  private readonly modelClass: typeof FlowModel;
+  private readonly parentRegistry: ModelEventRegistry | null;
+  // 本类变更标记（变更即更新引用，用于缓存命中判断）
+  private changeMarker: object = {};
+  // 合并缓存：父类合并快照引用 + 本类标记 + 合并后的 Map
+  private mergedCache?: {
+    parentSnapshot?: Map<string, EventDefinition>;
+    localMarker: object;
+    mergedMap: Map<string, EventDefinition>;
+  };
+
+  constructor(modelClass: typeof FlowModel, parentRegistry?: ModelEventRegistry | null) {
+    super();
+    this.modelClass = modelClass;
+    this.parentRegistry = parentRegistry ?? null;
+  }
+
+  // 标记本类有变更（用于缓存命中判断）
+  protected onEventRegistered() {
+    this.changeMarker = {};
+  }
+
+  /**
+   * 获取“包含继承”的合并事件（父 → 子），内部带缓存。
+   */
+  getEvents<TModel extends FlowModel = FlowModel>(): Map<string, EventDefinition<TModel>> {
+    const parentMap = this.parentRegistry?.getEvents<TModel>();
+    if (
+      this.mergedCache &&
+      this.mergedCache.parentSnapshot === parentMap &&
+      this.mergedCache.localMarker === this.changeMarker
+    ) {
+      return this.mergedCache.mergedMap as Map<string, EventDefinition<TModel>>;
+    }
+    const mergedMap = new Map<string, EventDefinition>(parentMap ?? []);
+    for (const [k, v] of this.events) mergedMap.set(k, v);
+    this.mergedCache = { parentSnapshot: parentMap, localMarker: this.changeMarker, mergedMap };
+    return mergedMap as Map<string, EventDefinition<TModel>>;
+  }
+
+  /**
+   * 解析指定名称的事件（优先本类，未命中递归父类）。
+   */
+  getEvent<TModel extends FlowModel = FlowModel>(name: string): EventDefinition<TModel> | undefined {
+    const own = this.events.get(name) as EventDefinition<TModel> | undefined;
+    if (own) return own;
+    return this.parentRegistry?.getEvent(name);
+  }
+}

package/src/event-registry/__tests__/engineEventRegistry.test.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+import { describe, expect, it } from 'vitest';
+import { EngineEventRegistry } from '../../event-registry/EngineEventRegistry';
+
+describe('EngineEventRegistry', () => {
+  it('registerEvent/getEvent and duplicate detection', () => {
+    const reg = new EngineEventRegistry();
+
+    reg.registerEvents({
+      e1: {
+        name: 'e1',
+        title: 'E1',
+        handler: (ctx, params) => {},
+      },
+      dup: {
+        name: 'dup',
+        title: 'v1',
+        handler: (ctx, params) => {},
+      },
+    });
+
+    // duplicate overrides
+    reg.registerEvent({
+      name: 'dup',
+      title: 'v2',
+      handler: (ctx, params) => {},
+    });
+
+    const all = reg.getEvents();
+    expect(all.has('e1')).toBe(true);
+    expect(all.get('e1')?.title).toBe('E1');
+    expect(all.get('dup')?.title).toBe('v2');
+
+    const one = reg.getEvent('dup');
+    expect(one?.title).toBe('v2');
+  });
+});

package/src/executor/FlowExecutor.ts

@@ -0,0 +1,256 @@
+/**
+ * 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 _ from 'lodash';
+import { FlowRuntimeContext } from '../flowContext';
+import { FlowEngine } from '../flowEngine';
+import type { FlowModel } from '../models';
+import type { ActionDefinition, ApplyFlowCacheEntry, StepDefinition } from '../types';
+import { FlowExitException, resolveDefaultParams } from '../utils';
+import { FlowExitAllException } from '../utils/exceptions';
+import { setupRuntimeContextSteps } from '../utils/setupRuntimeContextSteps';
+
+export class FlowExecutor {
+  constructor(private readonly engine: FlowEngine) {}
+
+  /**
+   * Execute a single flow on model.
+   */
+  async runFlow(model: FlowModel, flowKey: string, inputArgs?: Record<string, any>, runId?: string): Promise<any> {
+    const flow = model.getFlow(flowKey);
+
+    if (!flow) {
+      model.context.logger.error(`BaseModel.applyFlow: Flow with key '${flowKey}' not found.`);
+      return Promise.reject(new Error(`Flow '${flowKey}' not found.`));
+    }
+
+    const flowContext = new FlowRuntimeContext(model, flowKey);
+
+    flowContext.defineProperty('reactView', {
+      value: model.reactView,
+    });
+    flowContext.defineProperty('inputArgs', {
+      value: {
+        ...inputArgs,
+      },
+    });
+    flowContext.defineProperty('runId', {
+      value: runId || `run-${Date.now()}`,
+    });
+
+    let lastResult: any;
+    const stepResults: Record<string, any> = flowContext.stepResults;
+    let eventStep = model.getEvent(typeof flow.on === 'string' ? flow.on : (flow.on as any)?.eventName);
+    if (eventStep) {
+      eventStep = { ...eventStep }; // clone to avoid side effects
+      eventStep.defaultParams = { ..._.get(flow, 'on.defaultParams', {}), ...eventStep.defaultParams };
+    }
+    // Execute the event step first since it's usually the trigger condition - if the condition is not met, subsequent steps don't need to execute
+    const stepDefs = eventStep ? { eventStep, ...flow.steps } : flow.steps; // Record<string, StepDefinition>
+
+    // Setup steps meta and runtime mapping
+    setupRuntimeContextSteps(flowContext, stepDefs, model, flowKey);
+    const stepsRuntime = flowContext.steps as Record<string, { params: any; uiSchema?: any; result?: any }>;
+
+    for (const stepKey in stepDefs) {
+      if (!Object.prototype.hasOwnProperty.call(stepDefs, stepKey)) continue;
+      const step: StepDefinition = stepDefs[stepKey];
+      let handler: ActionDefinition['handler'] | undefined;
+      let combinedParams: Record<string, any> = {};
+      let actionDefinition: ActionDefinition | undefined;
+      let useRawParams: StepDefinition['useRawParams'] = step.useRawParams;
+
+      if (step.use) {
+        // Step references a registered action
+        actionDefinition = model.getAction(step.use);
+        if (!actionDefinition) {
+          flowContext.logger.error(
+            `BaseModel.applyFlow: Action '${step.use}' not found for step '${stepKey}' in flow '${flowKey}'. Skipping.`,
+          );
+          continue;
+        }
+        handler = step.handler || actionDefinition.handler;
+        useRawParams = useRawParams ?? actionDefinition.useRawParams;
+        const actionDefaultParams = await resolveDefaultParams(actionDefinition.defaultParams, flowContext);
+        const stepDefaultParams = await resolveDefaultParams(step.defaultParams, flowContext);
+        combinedParams = { ...actionDefaultParams, ...stepDefaultParams };
+      } else if (step.handler) {
+        handler = step.handler;
+        const stepDefaultParams = await resolveDefaultParams(step.defaultParams, flowContext);
+        combinedParams = { ...stepDefaultParams };
+      } else {
+        flowContext.logger.error(
+          `BaseModel.applyFlow: Step '${stepKey}' in flow '${flowKey}' has neither 'use' nor 'handler'. Skipping.`,
+        );
+        continue;
+      }
+
+      const modelStepParams = model.getStepParams(flowKey, stepKey);
+      if (modelStepParams !== undefined) {
+        combinedParams = { ...combinedParams, ...modelStepParams };
+      }
+      if (typeof useRawParams === 'function') {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        useRawParams = await useRawParams(flowContext);
+      }
+      if (!useRawParams) {
+        combinedParams = await flowContext.resolveJsonTemplate(combinedParams);
+      }
+
+      try {
+        if (!handler) {
+          flowContext.logger.error(
+            `BaseModel.applyFlow: No handler available for step '${stepKey}' in flow '${flowKey}'. Skipping.`,
+          );
+          continue;
+        }
+        const currentStepResult = handler(flowContext, combinedParams);
+        const isAwait = step.isAwait !== false;
+        lastResult = isAwait ? await currentStepResult : currentStepResult;
+
+        // Store step result
+        stepResults[stepKey] = lastResult;
+        // update the context
+        stepsRuntime[stepKey].result = stepResults[stepKey];
+      } catch (error) {
+        if (error instanceof FlowExitException) {
+          flowContext.logger.info(`[FlowEngine] ${error.message}`);
+          return Promise.resolve(stepResults);
+        }
+        if (error instanceof FlowExitAllException) {
+          flowContext.logger.info(`[FlowEngine] ${error.message}`);
+          // 传递特殊控制信号，让上层可中止后续流程
+          return Promise.resolve(error);
+        }
+        flowContext.logger.error(
+          { err: error },
+          `BaseModel.applyFlow: Error executing step '${stepKey}' in flow '${flowKey}':`,
+        );
+        return Promise.reject(error);
+      }
+    }
+    return Promise.resolve(stepResults);
+  }
+
+  /**
+   * Execute all auto-apply flows for model.
+   */
+  async runAutoFlows(model: FlowModel, inputArgs?: Record<string, any>, useCache = true): Promise<any[]> {
+    const autoApplyFlows = model.getAutoFlows();
+
+    if (autoApplyFlows.length === 0) {
+      model.context.logger.warn(`FlowModel: No auto-apply flows found for model '${model.uid}'`);
+      return [];
+    }
+
+    const cacheKey = useCache
+      ? FlowEngine.generateApplyFlowCacheKey(model.getAutoFlowCacheScope(), 'all', model.uid)
+      : null;
+
+    if (cacheKey && this.engine) {
+      const cachedEntry = this.engine.applyFlowCache.get(cacheKey);
+      if (cachedEntry) {
+        if (cachedEntry.status === 'resolved') {
+          model.context.logger.debug(`[FlowEngine.applyAutoFlows] Using cached result for model: ${model.uid}`);
+          return cachedEntry.data;
+        }
+        if (cachedEntry.status === 'rejected') throw cachedEntry.error;
+        if (cachedEntry.status === 'pending') return await cachedEntry.promise;
+      }
+    }
+
+    const executeAutoFlows = async (): Promise<any[]> => {
+      const results: any[] = [];
+      const runId = `${model.uid}-autoFlow-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+      const logger = model.context.logger.child({ module: 'flow-engine', component: 'FlowExecutor', runId });
+      logger.debug(
+        `[FlowExecutor] runAutoFlows: uid=${model.uid}, isFork=${
+          (model as any)?.isFork === true
+        }, useCache=${useCache}, runId=${runId}, flows=${autoApplyFlows.map((f) => f.key).join(',')}`,
+      );
+      try {
+        if (autoApplyFlows.length === 0) {
+          logger.warn(`FlowModel: No auto-apply flows found for model '${model.uid}'`);
+        } else {
+          for (const flow of autoApplyFlows) {
+            try {
+              logger.debug(`[FlowExecutor] runFlow: uid=${model.uid}, flowKey=${flow.key}`);
+              const result = await this.runFlow(model, flow.key, inputArgs, runId);
+              if (result instanceof FlowExitAllException) {
+                logger.debug(`[FlowEngine.applyAutoFlows] ${result.message}`);
+                break; // 终止后续流程执行
+              }
+              results.push(result);
+            } catch (error) {
+              logger.error({ err: error }, `FlowModel.applyAutoFlows: Error executing auto-apply flow '${flow.key}':`);
+              throw error;
+            }
+          }
+        }
+        return results;
+      } catch (error) {
+        if (error instanceof FlowExitException) {
+          logger.debug(`[FlowEngine.applyAutoFlows] ${error.message}`);
+          return results;
+        }
+        throw error;
+      }
+    };
+
+    if (!cacheKey || !this.engine) {
+      return await executeAutoFlows();
+    }
+
+    const promise = executeAutoFlows()
+      .then((result) => {
+        this.engine.applyFlowCache.set(cacheKey, {
+          status: 'resolved',
+          data: result,
+          promise: Promise.resolve(result),
+        } as ApplyFlowCacheEntry);
+        return result;
+      })
+      .catch((err) => {
+        this.engine.applyFlowCache.set(cacheKey, {
+          status: 'rejected',
+          error: err,
+          promise: Promise.reject(err),
+        } as ApplyFlowCacheEntry);
+        throw err;
+      });
+
+    this.engine.applyFlowCache.set(cacheKey, { status: 'pending', promise } as ApplyFlowCacheEntry);
+    return await promise;
+  }
+
+  /**
+   * Dispatch an event to flows bound via flow.on and execute them.
+   */
+  async dispatchEvent(model: FlowModel, eventName: string, inputArgs?: Record<string, any>): Promise<void> {
+    const flows = Array.from(model.getFlows().values()).filter((flow) => {
+      const on = flow.on;
+      if (!on) return false;
+      if (typeof on === 'string') return on === eventName;
+      if (typeof on === 'object') return on.eventName === eventName;
+      return false;
+    });
+    const runId = `${model.uid}-${eventName}-${Date.now()}`;
+    const logger = model.context.logger;
+    const promises = flows.map((flow) => {
+      logger.debug(`BaseModel '${model.uid}' dispatching event '${eventName}' to flow '${flow.key}'.`);
+      return this.runFlow(model, flow.key, inputArgs, runId).catch((error) => {
+        logger.error(
+          { err: error },
+          `BaseModel.dispatchEvent: Error executing event-triggered flow '${flow.key}' for event '${eventName}':`,
+        );
+      });
+    });
+    await Promise.all(promises);
+  }
+}