@nocobase/flow-engine 2.0.0-alpha.2

package/lib/flowEngine.js

@@ -0,0 +1,781 @@
+/**
+ * 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.
+ */
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+var flowEngine_exports = {};
+__export(flowEngine_exports, {
+  FlowEngine: () => FlowEngine
+});
+module.exports = __toCommonJS(flowEngine_exports);
+var import_reactive = require("@formily/reactive");
+var import_lodash = __toESM(require("lodash"));
+var import_pino = __toESM(require("pino"));
+var import_EngineActionRegistry = require("./action-registry/EngineActionRegistry");
+var import_EngineEventRegistry = require("./event-registry/EngineEventRegistry");
+var import_FlowExecutor = require("./executor/FlowExecutor");
+var import_flowContext = require("./flowContext");
+var import_flowSettings = require("./flowSettings");
+var import_models = require("./models");
+var import_ReactView = require("./ReactView");
+var import_resources = require("./resources");
+var import_utils = require("./utils");
+var _FlowEngine_instances, registerModel_fn;
+const _FlowEngine = class _FlowEngine {
+  /**
+   * Constructor. Initializes React view, registers default model and form scopes.
+   */
+  constructor() {
+    __privateAdd(this, _FlowEngine_instances);
+    /**
+     * Global action registry
+     */
+    __publicField(this, "_actionRegistry", new import_EngineActionRegistry.EngineActionRegistry());
+    /**
+     * Global event registry
+     */
+    __publicField(this, "_eventRegistry", new import_EngineEventRegistry.EngineEventRegistry());
+    /**
+     * Registered model classes.
+     * Key is the model class name, value is the model class constructor.
+     * @private
+     */
+    __publicField(this, "_modelClasses", import_reactive.observable.shallow(/* @__PURE__ */ new Map()));
+    /**
+     * Created model instances.
+     * Key is the model instance UID, value is the model instance object.
+     * @private
+     */
+    __publicField(this, "_modelInstances", /* @__PURE__ */ new Map());
+    /**
+     * The current model repository instance, implements IFlowModelRepository.
+     * Used for model persistence and queries.
+     * @private
+     */
+    __publicField(this, "_modelRepository", null);
+    /**
+     * Flow application cache.
+     * Key is the cache key, value is ApplyFlowCacheEntry.
+     * @private
+     */
+    __publicField(this, "_applyFlowCache", /* @__PURE__ */ new Map());
+    /**
+     * Model saving state tracking.
+     * Key is the model UID, value is the save promise.
+     * @private
+     */
+    __publicField(this, "_savingModels", /* @__PURE__ */ new Map());
+    /**
+     * Flow engine context object.
+     * @private
+     */
+    __publicField(this, "_flowContext");
+    /**
+     * 视图作用域引擎的栈式链表指针。
+     * - previousEngine：打开当前视图的上一个引擎
+     * - nextEngine：在当前之上的下一个引擎
+     */
+    __publicField(this, "_previousEngine");
+    __publicField(this, "_nextEngine");
+    __publicField(this, "_resources", /* @__PURE__ */ new Map());
+    __publicField(this, "logger");
+    /**
+     * Flow settings, including components and form scopes.
+     * @public
+     */
+    __publicField(this, "flowSettings");
+    /**
+     * Experimental API: Integrates React view rendering capability into FlowEngine.
+     * This property may change or be removed in the future. Use with caution.
+     * @experimental
+     * @public
+     */
+    __publicField(this, "reactView");
+    /**
+     * Flow executor that runs flows and auto-flows.
+     */
+    __publicField(this, "executor");
+    this.reactView = new import_ReactView.ReactView(this);
+    this.flowSettings = new import_flowSettings.FlowSettings(this);
+    this.flowSettings.registerScopes({ t: this.translate.bind(this) });
+    this.registerModels({ FlowModel: import_models.FlowModel });
+    this.registerResources({
+      FlowResource: import_resources.FlowResource,
+      SQLResource: import_resources.SQLResource,
+      APIResource: import_resources.APIResource,
+      SingleRecordResource: import_resources.SingleRecordResource,
+      MultiRecordResource: import_resources.MultiRecordResource
+    });
+    this.logger = (0, import_pino.default)({
+      level: "trace",
+      browser: {
+        write: {
+          fatal: /* @__PURE__ */ __name((o) => console.trace(o), "fatal"),
+          error: /* @__PURE__ */ __name((o) => console.error(o), "error"),
+          warn: /* @__PURE__ */ __name((o) => console.warn(o), "warn"),
+          info: /* @__PURE__ */ __name((o) => console.info(o), "info"),
+          debug: /* @__PURE__ */ __name((o) => console.debug(o), "debug"),
+          trace: /* @__PURE__ */ __name((o) => console.trace(o), "trace")
+        }
+      }
+    });
+    this.executor = new import_FlowExecutor.FlowExecutor(this);
+  }
+  /** 上一个引擎（根引擎为 undefined） */
+  get previousEngine() {
+    return this._previousEngine;
+  }
+  /** 下一个引擎（若存在） */
+  get nextEngine() {
+    return this._nextEngine;
+  }
+  /**
+   * 将当前引擎链接到 prev 之后（用于视图打开时形成栈关系）。
+   */
+  linkAfter(engine) {
+    let prev = engine;
+    while (prev._nextEngine) prev = prev._nextEngine;
+    this._previousEngine = prev;
+    if (prev) {
+      prev._nextEngine = this;
+    }
+  }
+  /**
+   * 将当前引擎从栈中移除并修复相邻指针（用于视图关闭时）。
+   */
+  unlinkFromStack() {
+    const prev = this._previousEngine;
+    const next = this._nextEngine;
+    if (prev) {
+      prev._nextEngine = void 0;
+    }
+  }
+  // （已移除）getModelGlobal/forEachModelGlobal/getAllModelsGlobal：不再维护冗余全局遍历 API
+  /**
+   * Get the flow engine context object.
+   * @returns {FlowEngineContext} Flow engine context
+   */
+  get context() {
+    if (!this._flowContext) {
+      this._flowContext = new import_flowContext.FlowEngineContext(this);
+    }
+    return this._flowContext;
+  }
+  get dataSourceManager() {
+    return this.context.dataSourceManager;
+  }
+  /**
+   * Get the flow application cache.
+   * @returns {Map<string, ApplyFlowCacheEntry>} Flow application cache map
+   * @internal
+   */
+  get applyFlowCache() {
+    return this._applyFlowCache;
+  }
+  /**
+   * Set the model repository for persisting and querying model instances.
+   * If a model repository was already set, it will be overwritten and a warning will be printed.
+   * @param {IFlowModelRepository} modelRepository The model repository instance implementing IFlowModelRepository.
+   * @example
+   * flowEngine.setModelRepository(new MyFlowModelRepository());
+   */
+  setModelRepository(modelRepository) {
+    if (this._modelRepository) {
+      console.warn("FlowEngine: Model repository is already set and will be overwritten.");
+    }
+    this._modelRepository = modelRepository;
+  }
+  get modelRepository() {
+    return this._modelRepository;
+  }
+  /**
+   * Internationalization translation method, calls the context's t method.
+   * @param {string} keyOrTemplate Translation key or template string
+   * @param {any} [options] Optional parameters
+   * @returns {string} Translated string
+   */
+  translate(keyOrTemplate, options) {
+    return this.context.t(keyOrTemplate, options);
+  }
+  /**
+   * Register multiple actions.
+   * @param {Record<string, ActionDefinition>} actions Action definition object collection
+   */
+  registerActions(actions) {
+    this._actionRegistry.registerActions(actions);
+  }
+  /**
+   * Get a registered action definition.
+   * @template TModel Specific FlowModel subclass type
+   * @param {string} name Action name
+   * @returns {ActionDefinition<TModel> | undefined} Action definition, or undefined if not found
+   */
+  getAction(name) {
+    return this._actionRegistry.getAction(name);
+  }
+  /**
+   * Get all registered global actions.
+   * Returns a new Map to avoid external mutation of internal state.
+   */
+  getActions() {
+    return this._actionRegistry.getActions();
+  }
+  /**
+   * Register multiple events.
+   */
+  registerEvents(events) {
+    this._eventRegistry.registerEvents(events);
+  }
+  /**
+   * Get a registered event definition.
+   */
+  getEvent(name) {
+    return this._eventRegistry.getEvent(name);
+  }
+  /**
+   * Get all registered global events.
+   */
+  getEvents() {
+    return this._eventRegistry.getEvents();
+  }
+  /**
+   * Register multiple model classes.
+   * @param {Record<string, ModelConstructor>} models Model class map, key is model name, value is model constructor
+   * @returns {void}
+   * @example
+   * flowEngine.registerModels({ UserModel, OrderModel });
+   */
+  registerModels(models) {
+    for (const [name, modelClass] of Object.entries(models)) {
+      __privateMethod(this, _FlowEngine_instances, registerModel_fn).call(this, name, modelClass);
+    }
+  }
+  registerResources(resources) {
+    for (const [name, resourceClass] of Object.entries(resources)) {
+      this._resources.set(name, resourceClass);
+    }
+  }
+  createResource(resourceType, options) {
+    if (typeof resourceType === "string") {
+      const ResourceClass = this._resources.get(resourceType);
+      if (!ResourceClass) {
+        throw new Error(`Resource class '${resourceType}' not found. Please register it first.`);
+      }
+      return new ResourceClass((options == null ? void 0 : options.context) || this.context);
+    }
+    const R = resourceType;
+    return new R((options == null ? void 0 : options.context) || this.context);
+  }
+  /**
+   * Get all registered model classes.
+   * @returns {Map<string, ModelConstructor>} Model class map
+   */
+  getModelClasses() {
+    return this._modelClasses;
+  }
+  /**
+   * Get a registered model class (constructor).
+   * @param {string} name Model class name
+   * @returns {ModelConstructor | undefined} Model constructor, or undefined if not found
+   */
+  getModelClass(name) {
+    return this._modelClasses.get(name);
+  }
+  /**
+   * Find a registered model class by predicate.
+   * @param predicate Callback function, arguments are (name, ModelClass), returns true if matched
+   * @returns {[string, ModelConstructor] | undefined} Matched model class and name
+   */
+  findModelClass(predicate) {
+    for (const [name, ModelClass] of this._modelClasses) {
+      if (predicate(name, ModelClass)) {
+        return [name, ModelClass];
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Filter model classes by base class (supports multi-level inheritance), with optional custom filter.
+   * @param {string | ModelConstructor} baseClass Base class name or constructor
+   * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+   * @returns {Map<string, ModelConstructor>} Model classes inherited from base class and passed the filter
+   */
+  getSubclassesOf(baseClass, filter) {
+    const parentModelClass = typeof baseClass === "string" ? this.getModelClass(baseClass) : baseClass;
+    const result = /* @__PURE__ */ new Map();
+    if (!parentModelClass) return result;
+    for (const [className, ModelClass] of this._modelClasses) {
+      if ((0, import_utils.isInheritedFrom)(ModelClass, parentModelClass)) {
+        if (!filter || filter(ModelClass, className)) {
+          result.set(className, ModelClass);
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Create and register a model instance.
+   * If an instance with the same UID exists, returns the existing instance.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {CreateModelOptions} options Model creation options
+   * @returns {T} Created model instance
+   */
+  createModel(options, extra) {
+    const { parentId, uid, use: modelClassName, subModels } = options;
+    const ModelClass = typeof modelClassName === "string" ? this.getModelClass(modelClassName) : modelClassName;
+    if (uid && this._modelInstances.has(uid)) {
+      return this._modelInstances.get(uid);
+    }
+    let modelInstance;
+    if (!ModelClass) {
+      modelInstance = new import_models.ErrorFlowModel({ ...options, flowEngine: this });
+      modelInstance.setErrorMessage(`Model class '${modelClassName}' not found. Please register it first.`);
+    } else {
+      modelInstance = new ModelClass({ ...options, flowEngine: this });
+    }
+    if (extra == null ? void 0 : extra.delegate) {
+      modelInstance.context.addDelegate(extra.delegate);
+    }
+    if (parentId && this._modelInstances.has(parentId)) {
+      modelInstance.setParent(this._modelInstances.get(parentId));
+      if ((extra == null ? void 0 : extra.delegateToParent) === false) {
+        modelInstance.removeParentDelegate();
+      }
+    }
+    this._modelInstances.set(modelInstance.uid, modelInstance);
+    modelInstance.onInit(options);
+    this._applyFlowDefinitionDefaultParams(modelInstance).catch((err) => {
+      console.warn("FlowEngine: apply flow defaultParams failed:", err);
+    });
+    modelInstance._createSubModels(options.subModels);
+    return modelInstance;
+  }
+  /**
+   * 尝试应用当前模型可用 flow 的 defaultParams（如果存在）到 model.stepParams。
+   * 仅对尚未存在的步骤参数进行填充，不覆盖已有值。
+   */
+  async _applyFlowDefinitionDefaultParams(model) {
+    var _a;
+    try {
+      const flows = model.getFlows();
+      if (!flows || flows.size === 0) return;
+      const ctx = model.context;
+      for (const [flowKey, flowDef] of flows.entries()) {
+        const dp = flowDef.defaultParams;
+        if (!dp) continue;
+        let resolved;
+        try {
+          resolved = typeof dp === "function" ? await dp(ctx) : dp;
+        } catch (e) {
+          console.warn(`FlowEngine: resolve defaultParams of flow '${flowKey}' failed:`, e);
+          continue;
+        }
+        if (!resolved || typeof resolved !== "object") continue;
+        const stepsMap = (_a = flowDef.getSteps) == null ? void 0 : _a.call(flowDef);
+        const stepKeys = stepsMap ? Array.from(stepsMap.keys()) : Object.keys(flowDef.steps || {});
+        const entries = Object.entries(resolved).filter(([k]) => stepKeys.includes(k));
+        if (entries.length === 0) continue;
+        for (const [stepKey, params] of entries) {
+          const exists = model.getStepParams(flowKey, stepKey);
+          if (exists === void 0 && params && typeof params === "object") {
+            model.setStepParams(flowKey, stepKey, params);
+          }
+        }
+      }
+    } catch (error) {
+      console.warn("FlowEngine: apply flow defaultParams error:", error);
+    }
+  }
+  /**
+   * Get a model instance by UID.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {string} uid Model instance UID
+   * @returns {T | undefined} Model instance, or undefined if not found
+   */
+  getModel(uid, global) {
+    if (!global) {
+      return this._modelInstances.get(uid);
+    }
+    let top = this;
+    while (top.nextEngine) top = top.nextEngine;
+    let eng = top;
+    while (eng) {
+      const found = eng._modelInstances.get(uid);
+      if (found) return found;
+      eng = eng.previousEngine;
+    }
+    return void 0;
+  }
+  /**
+   * Iterate all registered model instances.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {(model: T) => void} callback Callback function
+   */
+  forEachModel(callback) {
+    this._modelInstances.forEach(callback);
+  }
+  /**
+   * Remove a local model instance.
+   * @param {string} uid UID of the model instance to destroy
+   * @returns {boolean} Returns true if successfully destroyed, false otherwise (e.g. instance does not exist)
+   */
+  removeModel(uid) {
+    var _a;
+    if (!this._modelInstances.has(uid)) {
+      console.warn(`FlowEngine: Model with UID '${uid}' does not exist.`);
+      return false;
+    }
+    const modelInstance = this._modelInstances.get(uid);
+    modelInstance.clearForks();
+    if ((_a = modelInstance.parent) == null ? void 0 : _a.subModels) {
+      for (const subKey in modelInstance.parent.subModels) {
+        const subModelValue = modelInstance.parent.subModels[subKey];
+        if (Array.isArray(subModelValue)) {
+          const index = subModelValue.findIndex((subModel) => subModel == modelInstance);
+          if (index !== -1) {
+            subModelValue.splice(index, 1);
+            modelInstance.parent.emitter.emit("onSubModelRemoved", modelInstance);
+            break;
+          }
+        } else if (subModelValue && subModelValue === modelInstance) {
+          delete modelInstance.parent.subModels[subKey];
+          modelInstance.parent.emitter.emit("onSubModelRemoved", modelInstance);
+          break;
+        }
+      }
+    }
+    this._modelInstances.delete(uid);
+    return true;
+  }
+  /**
+   * Check if the model repository is set.
+   * @returns {boolean} Returns true if set, false otherwise.
+   * @private
+   */
+  ensureModelRepository() {
+    if (!this._modelRepository) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Load a model instance (prefers local, falls back to repository).
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {any} options Load options
+   * @returns {Promise<T | null>} Loaded model instance or null
+   */
+  async loadModel(options) {
+    if (!this.ensureModelRepository()) return;
+    const model = this.findModelByParentId(options.parentId, options.subKey);
+    if (model) {
+      return model;
+    }
+    const data = await this._modelRepository.findOne(options);
+    return (data == null ? void 0 : data.uid) ? this.createModel(data) : null;
+  }
+  /**
+   * Find a sub-model by parent model ID and subKey.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {string} parentId Parent model UID
+   * @param {string} subKey Sub-model key
+   * @returns {T | null} Found sub-model or null
+   */
+  findModelByParentId(parentId, subKey) {
+    if (parentId && this._modelInstances.has(parentId)) {
+      const parentModel = this._modelInstances.get(parentId);
+      if (parentModel && parentModel.subModels[subKey]) {
+        const subModels = parentModel.subModels[subKey];
+        if (Array.isArray(subModels)) {
+          return subModels[0];
+        } else {
+          return subModels;
+        }
+      }
+    }
+  }
+  /**
+   * Load or create a model instance.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {any} options Load or create options
+   * @returns {Promise<T | null>} Model instance or null
+   */
+  async loadOrCreateModel(options, extra) {
+    if (!this.ensureModelRepository()) return;
+    const { uid, parentId, subKey } = options;
+    if (uid && this._modelInstances.has(uid)) {
+      return this._modelInstances.get(uid);
+    }
+    const m = this.findModelByParentId(parentId, subKey);
+    if (m) {
+      return m;
+    }
+    const data = await this._modelRepository.findOne(options);
+    let model = null;
+    if (data == null ? void 0 : data.uid) {
+      model = this.createModel(data, extra);
+    } else {
+      model = this.createModel(options, extra);
+      await model.save();
+    }
+    if (model.parent) {
+      const subModel = model.parent.findSubModel(model.subKey, (m2) => {
+        return m2.uid === model.uid;
+      });
+      if (subModel) {
+        return model;
+      }
+      if (model.subType === "array") {
+        model.parent.addSubModel(model.subKey, model);
+      } else {
+        model.parent.setSubModel(model.subKey, model);
+      }
+    }
+    return model;
+  }
+  /**
+   * Persist and save a model instance.
+   * Prevents concurrent saves of the same model by tracking save operations.
+   * If a model is already being saved, subsequent calls will wait for the existing save to complete.
+   *
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {T} model Model instance to save
+   * @param {object} [options] Save options
+   * @param {boolean} [options.onlyStepParams] Whether to save only step parameters
+   * @returns {Promise<any>} Repository save result
+   */
+  async saveModel(model, options) {
+    if (!this.ensureModelRepository()) return;
+    const modelUid = model.uid;
+    if (this._savingModels.has(modelUid)) {
+      this.logger.debug(`Model ${modelUid} is already being saved, waiting for existing save operation`);
+      return await this._savingModels.get(modelUid);
+    }
+    const savePromise = this._performModelSave(model, options);
+    this._savingModels.set(modelUid, savePromise);
+    try {
+      const result = await savePromise;
+      return result;
+    } finally {
+      this._savingModels.delete(modelUid);
+    }
+  }
+  /**
+   * Perform the actual model save operation.
+   * @template T FlowModel subclass type, defaults to FlowModel.
+   * @param {T} model Model instance to save
+   * @param {object} [options] Save options
+   * @returns {Promise<any>} Repository save result
+   * @private
+   */
+  async _performModelSave(model, options) {
+    this.logger.debug(`Starting save operation for model ${model.uid}`);
+    try {
+      const result = await this._modelRepository.save(model, options);
+      this.logger.debug(`Successfully saved model ${model.uid}`);
+      return result;
+    } catch (error) {
+      this.logger.error(`Failed to save model ${model.uid}:`, error);
+      throw error;
+    }
+  }
+  /**
+   * Destroy a model instance (persistently delete and remove local instance).
+   * @param {string} uid UID of the model to destroy
+   * @returns {Promise<boolean>} Whether destroyed successfully
+   */
+  async destroyModel(uid) {
+    if (this.ensureModelRepository()) {
+      await this._modelRepository.destroy(uid);
+    }
+    return this.removeModel(uid);
+  }
+  /**
+   * Replace a model instance with a new instance of a class.
+   * @template T New model type
+   * @param {string} uid UID of the model to replace
+   * @param {Partial<FlowModelOptions> | ((oldModel: FlowModel) => Partial<FlowModelOptions>)} [optionsOrFn]
+   *        Options for creating the new model, supports two forms:
+   *        1. Pass options directly
+   *        2. Pass a function that receives current options and returns new options
+   * @returns {Promise<T | null>} Newly created model instance
+   */
+  async replaceModel(uid, optionsOrFn) {
+    var _a;
+    const oldModel = this.getModel(uid);
+    if (!oldModel) {
+      console.warn(`FlowEngine: Cannot replace model. Model with UID '${uid}' not found.`);
+      return null;
+    }
+    const currentParent = oldModel.parent;
+    const currentSubKey = oldModel.subKey;
+    const currentSubType = oldModel.subType;
+    const currentOptions = oldModel.serialize();
+    let userOptions;
+    if (typeof optionsOrFn === "function") {
+      userOptions = optionsOrFn(oldModel);
+    } else {
+      userOptions = optionsOrFn || {};
+    }
+    const newOptions = {
+      ...import_lodash.default.omit(currentOptions, ["subModels"]),
+      ...userOptions
+    };
+    if (currentParent) {
+      currentParent.emitter.setPaused(true);
+    }
+    await oldModel.destroy();
+    const newModel = this.createModel(newOptions);
+    if (currentParent && currentSubKey) {
+      if (currentSubType === "array") {
+        currentParent.addSubModel(currentSubKey, newModel);
+      } else {
+        currentParent.setSubModel(currentSubKey, newModel);
+      }
+    }
+    if (currentParent) {
+      currentParent.emitter.setPaused(false);
+      currentParent.parent.invalidateAutoFlowCache(true);
+      (_a = currentParent.parent) == null ? void 0 : _a.rerender();
+      currentParent.emitter.emit("onSubModelReplaced", { oldModel, newModel });
+    }
+    await newModel.save();
+    return newModel;
+  }
+  /**
+   * Move a model instance within its parent model.
+   * @param {any} sourceId Source model UID
+   * @param {any} targetId Target model UID
+   * @returns {Promise<void>} No return value
+   */
+  async moveModel(sourceId, targetId, options) {
+    const sourceModel = this.getModel(sourceId);
+    const targetModel = this.getModel(targetId);
+    if (!sourceModel || !targetModel) {
+      console.warn(`FlowEngine: Cannot move model. Source or target model not found.`);
+      return;
+    }
+    const move = /* @__PURE__ */ __name((sourceModel2, targetModel2) => {
+      if (!sourceModel2.parent || !targetModel2.parent || sourceModel2.parent !== targetModel2.parent) {
+        console.error("FlowModel.moveTo: Both models must have the same parent to perform move operation.");
+        return false;
+      }
+      const subModels = sourceModel2.parent.subModels[sourceModel2.subKey];
+      if (!subModels || !Array.isArray(subModels)) {
+        console.error("FlowModel.moveTo: Parent subModels must be an array to perform move operation.");
+        return false;
+      }
+      const findIndex = /* @__PURE__ */ __name((model) => subModels.findIndex((item) => item.uid === model.uid), "findIndex");
+      const currentIndex = findIndex(sourceModel2);
+      const targetIndex = findIndex(targetModel2);
+      if (currentIndex === -1 || targetIndex === -1) {
+        console.error("FlowModel.moveTo: Current or target model not found in parent subModels.");
+        return false;
+      }
+      if (currentIndex === targetIndex) {
+        console.warn("FlowModel.moveTo: Current model is already at the target position. No action taken.");
+        return false;
+      }
+      const [movedModel] = subModels.splice(currentIndex, 1);
+      subModels.splice(targetIndex, 0, movedModel);
+      subModels.forEach((model, index) => {
+        model.sortIndex = index;
+      });
+      return true;
+    }, "move");
+    move(sourceModel, targetModel);
+    if ((options == null ? void 0 : options.persist) !== false && this.ensureModelRepository()) {
+      const position = sourceModel.sortIndex - targetModel.sortIndex > 0 ? "after" : "before";
+      await this._modelRepository.move(sourceId, targetId, position);
+    }
+    sourceModel.parent.emitter.emit("onSubModelMoved", { source: sourceModel, target: targetModel });
+  }
+  /**
+   * Filter model classes by parent class (supports multi-level inheritance).
+   * @param {string | ModelConstructor} parentClass Parent class name or constructor
+   * @returns {Map<string, ModelConstructor>} Model classes inherited from the specified parent class
+   */
+  filterModelClassByParent(parentClass) {
+    const parentModelClass = typeof parentClass === "string" ? this.getModelClass(parentClass) : parentClass;
+    if (!parentModelClass) {
+      return /* @__PURE__ */ new Map();
+    }
+    const modelClasses = /* @__PURE__ */ new Map();
+    for (const [className, ModelClass] of this._modelClasses) {
+      if ((0, import_utils.isInheritedFrom)(ModelClass, parentModelClass)) {
+        modelClasses.set(className, ModelClass);
+      }
+    }
+    return modelClasses;
+  }
+  /**
+   * Generate a unique key for the flow application cache.
+   * @param {string} prefix Prefix
+   * @param {string} flowKey Flow key
+   * @param {string} modelUid Model UID
+   * @returns {string} Unique cache key
+   * @internal
+   */
+  static generateApplyFlowCacheKey(prefix, flowKey, modelUid) {
+    return `${prefix}:${flowKey}:${modelUid}`;
+  }
+};
+_FlowEngine_instances = new WeakSet();
+/**
+ * Register a single model class.
+ * @param {string} name Model class name
+ * @param {ModelConstructor} modelClass Model class constructor
+ * @private
+ */
+registerModel_fn = /* @__PURE__ */ __name(function(name, modelClass) {
+  if (this._modelClasses.has(name)) {
+    console.warn(`FlowEngine: Model class with name '${name}' is already registered and will be overwritten.`);
+  }
+  Object.defineProperty(modelClass, "name", { value: name });
+  this._modelClasses.set(name, modelClass);
+}, "#registerModel");
+__name(_FlowEngine, "FlowEngine");
+let FlowEngine = _FlowEngine;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlowEngine
+});