@nocobase/flow-engine 2.1.0-alpha.13 → 2.1.0-alpha.15

package/lib/flowEngine.d.ts

@@ -8,7 +8,7 @@ import { FlowResource } from './resources';
 import { Emitter } from './emitter';
 import ModelOperationScheduler from './scheduler/ModelOperationScheduler';
 import type { ScheduleOptions, ScheduledCancel } from './scheduler/ModelOperationScheduler';
-import type { ActionDefinition, ApplyFlowCacheEntry, CreateModelOptions, EnsureBatchResult, EventDefinition, FlowModelLoaderMap, FlowModelOptions, IFlowModelRepository, ModelConstructor, PersistOptions, ResourceType } from './types';
+import type { ActionDefinition, ApplyFlowCacheEntry, CreateModelOptions, EnsureBatchResult, EventDefinition, FlowModelLoaderInputMap, FlowModelOptions, IFlowModelRepository, ModelConstructor, PersistOptions, ResourceType } from './types';
 /**
  * FlowEngine is the core class of the flow engine, responsible for managing flow models, actions, model repository, and more.
  * It provides capabilities for registering, creating, finding, persisting, replacing, and moving models.
@@ -262,16 +262,19 @@ export declare class FlowEngine {
     registerModels(models: Record<string, ModelConstructor | typeof FlowModel<any>>): void;
     /**
      * Register multiple model loader entries.
-     * @param {FlowModelLoaderMap} loaders Model loader entry map, key is model name, value is the model loader entry
+     * The `extends` field declares parent class(es) for async subclass discovery via `getSubclassesOfAsync`.
+     * It accepts `string | ModelConstructor | (string | ModelConstructor)[]` and is normalized to `string[]` internally.
+     * @param {FlowModelLoaderInputMap} loaders Model loader input map
      * @returns {void}
      * @example
      * flowEngine.registerModelLoaders({
      *   DemoModel: {
+     *     extends: 'BaseModel',
      *     loader: () => import('./models/DemoModel'),
      *   },
      * });
      */
-    registerModelLoaders(loaders: FlowModelLoaderMap): void;
+    registerModelLoaders(loaders: FlowModelLoaderInputMap): void;
     /**
      * Get a registered model class (constructor) asynchronously.
      * This will first ensure the model loader entry is resolved.
@@ -381,6 +384,15 @@ export declare class FlowEngine {
      * @returns {Map<string, ModelConstructor>} Model classes inherited from base class and passed the filter
      */
     getSubclassesOf(baseClass: string | ModelConstructor, filter?: (ModelClass: ModelConstructor, className: string) => boolean): Map<string, ModelConstructor>;
+    /**
+     * Asynchronously get all subclasses of a base class, including those registered via model loaders.
+     * Merges results from already-loaded classes (_modelClasses) and async loader entries with matching `extends` declarations.
+     * Loader-resolved classes are validated with `isInheritedFrom`; mismatches are warned and excluded.
+     * @param {string | ModelConstructor} baseClass Base class name or constructor
+     * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+     * @returns {Promise<Map<string, ModelConstructor>>} Model classes that are subclasses of the base class
+     */
+    getSubclassesOfAsync(baseClass: string | ModelConstructor, filter?: (ModelClass: ModelConstructor, className: string) => boolean): Promise<Map<string, ModelConstructor>>;
     /**
      * Create and register a model instance.
      * If an instance with the same UID exists, returns the existing instance.

package/lib/flowEngine.js

@@ -418,21 +418,31 @@ const _FlowEngine = class _FlowEngine {
   }
   /**
    * Register multiple model loader entries.
-   * @param {FlowModelLoaderMap} loaders Model loader entry map, key is model name, value is the model loader entry
+   * The `extends` field declares parent class(es) for async subclass discovery via `getSubclassesOfAsync`.
+   * It accepts `string | ModelConstructor | (string | ModelConstructor)[]` and is normalized to `string[]` internally.
+   * @param {FlowModelLoaderInputMap} loaders Model loader input map
    * @returns {void}
    * @example
    * flowEngine.registerModelLoaders({
    *   DemoModel: {
+   *     extends: 'BaseModel',
    *     loader: () => import('./models/DemoModel'),
    *   },
    * });
    */
   registerModelLoaders(loaders) {
     let changed = false;
-    for (const [name, entry] of Object.entries(loaders)) {
+    for (const [name, input] of Object.entries(loaders)) {
       if (this._modelLoaders.has(name)) {
         console.warn(`FlowEngine: Model loader with name '${name}' is already registered and will be overwritten.`);
       }
+      const entry = {
+        loader: input.loader
+      };
+      if (input.extends != null) {
+        const raw = Array.isArray(input.extends) ? input.extends : [input.extends];
+        entry.extends = raw.map((item) => typeof item === "string" ? item : item.name);
+      }
       this._modelLoaders.set(name, entry);
       changed = true;
     }
@@ -737,6 +747,55 @@ const _FlowEngine = class _FlowEngine {
     }
     return result;
   }
+  /**
+   * Asynchronously get all subclasses of a base class, including those registered via model loaders.
+   * Merges results from already-loaded classes (_modelClasses) and async loader entries with matching `extends` declarations.
+   * Loader-resolved classes are validated with `isInheritedFrom`; mismatches are warned and excluded.
+   * @param {string | ModelConstructor} baseClass Base class name or constructor
+   * @param {(ModelClass: ModelConstructor, className: string) => boolean} [filter] Optional filter function
+   * @returns {Promise<Map<string, ModelConstructor>>} Model classes that are subclasses of the base class
+   */
+  async getSubclassesOfAsync(baseClass, filter) {
+    var _a;
+    const baseClassName = typeof baseClass === "string" ? baseClass : baseClass.name;
+    let parentModelClass;
+    if (typeof baseClass === "string") {
+      if (!this.getModelClass(baseClass)) {
+        await this.ensureModel(baseClass);
+      }
+      parentModelClass = this.getModelClass(baseClass);
+    } else {
+      parentModelClass = baseClass;
+    }
+    if (!parentModelClass) {
+      return /* @__PURE__ */ new Map();
+    }
+    const result = this.getSubclassesOf(parentModelClass, filter);
+    const loaderCandidates = [];
+    for (const [name, entry] of this._modelLoaders) {
+      if (result.has(name) || this._modelClasses.has(name)) continue;
+      if ((_a = entry.extends) == null ? void 0 : _a.includes(baseClassName)) {
+        loaderCandidates.push(name);
+      }
+    }
+    if (loaderCandidates.length > 0) {
+      await this.ensureModels(loaderCandidates);
+    }
+    for (const name of loaderCandidates) {
+      const ModelClass = this._modelClasses.get(name);
+      if (!ModelClass) continue;
+      if (!(0, import_utils.isInheritedFrom)(ModelClass, parentModelClass)) {
+        console.warn(
+          `FlowEngine: Model '${name}' declares extends '${baseClassName}' but does not actually inherit from it. Skipping.`
+        );
+        continue;
+      }
+      if (!filter || filter(ModelClass, name)) {
+        result.set(name, ModelClass);
+      }
+    }
+    return result;
+  }
   /**
    * Create and register a model instance.
    * If an instance with the same UID exists, returns the existing instance.
@@ -1140,10 +1199,7 @@ const _FlowEngine = class _FlowEngine {
     if (hydrated) {
       return hydrated;
     }
-    const shouldUseEnsure = !(extra == null ? void 0 : extra.skipSave) && !uid && !!parentId && !!subKey && (options == null ? void 0 : options.subType) === "object";
-    const data = shouldUseEnsure ? await this._modelRepository.ensure(options, {
-      includeAsyncNode: !!((options == null ? void 0 : options.includeAsyncNode) || (options == null ? void 0 : options.async))
-    }) ?? await this._modelRepository.findOne(options) : await this._modelRepository.findOne(options);
+    const data = await this._modelRepository.findOne(options);
     let model = null;
     if (data == null ? void 0 : data.uid) {
       model = await this.createModelAsync(data, extra);

package/lib/locale/en-US.json

@@ -34,6 +34,7 @@
   "Failed to destroy model after creation error": "Failed to destroy model after creation error",
   "Failed to get action {{action}}": "Failed to get action {{action}}",
   "Failed to get configurable flows for model {{model}}": "Failed to get configurable flows for model {{model}}",
+  "Attributes are unavailable before selecting a record": "Attributes are unavailable before selecting a record",
   "Failed to import FormDialog": "Failed to import FormDialog",
   "Failed to import FormDialog or FormStep": "Failed to import FormDialog or FormStep",
   "Failed to import Formily components": "Failed to import Formily components",

package/lib/locale/index.d.ts

@@ -43,6 +43,7 @@ export declare const locales: {
         "Failed to destroy model after creation error": string;
         "Failed to get action {{action}}": string;
         "Failed to get configurable flows for model {{model}}": string;
+        "Attributes are unavailable before selecting a record": string;
         "Failed to import FormDialog": string;
         "Failed to import FormDialog or FormStep": string;
         "Failed to import Formily components": string;
@@ -120,6 +121,7 @@ export declare const locales: {
         "Failed to destroy model after creation error": string;
         "Failed to get action {{action}}": string;
         "Failed to get configurable flows for model {{model}}": string;
+        "Attributes are unavailable before selecting a record": string;
         "Failed to import FormDialog": string;
         "Failed to import FormDialog or FormStep": string;
         "Failed to import Formily components": string;

package/lib/locale/zh-CN.json

@@ -31,6 +31,7 @@
   "Failed to destroy model after creation error": "创建错误后销毁模型失败",
   "Failed to get action {{action}}": "获取 action '{{action}}' 失败",
   "Failed to get configurable flows for model {{model}}": "获取模型 '{{model}}' 的可配置 flows 失败",
+  "Attributes are unavailable before selecting a record": "选择记录之前，当前项属性不可用",
   "Failed to import FormDialog": "导入 FormDialog 失败",
   "Failed to import FormDialog or FormStep": "导入 FormDialog 或 FormStep 失败",
   "Failed to import Formily components": "导入 Formily 组件失败",

package/lib/reactive/observer.js

@@ -51,8 +51,31 @@ const observer = /* @__PURE__ */ __name((Component, options) => {
     const ctxRef = (0, import_react.useRef)(ctx);
     ctxRef.current = ctx;
     const pendingDisposerRef = (0, import_react.useRef)(null);
+    const pendingTimerRef = (0, import_react.useRef)(null);
+    const clearPendingDisposer = /* @__PURE__ */ __name(() => {
+      if (pendingDisposerRef.current) {
+        pendingDisposerRef.current();
+        pendingDisposerRef.current = null;
+      }
+    }, "clearPendingDisposer");
+    const clearPendingTimer = /* @__PURE__ */ __name(() => {
+      if (pendingTimerRef.current) {
+        clearTimeout(pendingTimerRef.current);
+        pendingTimerRef.current = null;
+      }
+    }, "clearPendingTimer");
+    const isContextActive = /* @__PURE__ */ __name(() => {
+      var _a, _b;
+      const pageActive = getPageActive(ctxRef.current);
+      const tabActive = (_b = (_a = ctxRef.current) == null ? void 0 : _a.tabActive) == null ? void 0 : _b.value;
+      return pageActive !== false && tabActive !== false;
+    }, "isContextActive");
     (0, import_react.useEffect)(() => {
       return () => {
+        if (pendingTimerRef.current) {
+          clearTimeout(pendingTimerRef.current);
+          pendingTimerRef.current = null;
+        }
         if (pendingDisposerRef.current) {
           pendingDisposerRef.current();
           pendingDisposerRef.current = null;
@@ -62,30 +85,37 @@ const observer = /* @__PURE__ */ __name((Component, options) => {
     const ObservedComponent = (0, import_react.useMemo)(
       () => (0, import_reactive_react.observer)(Component, {
         scheduler(updater) {
-          var _a, _b;
-          const pageActive = getPageActive(ctxRef.current);
-          const tabActive = (_b = (_a = ctxRef.current) == null ? void 0 : _a.tabActive) == null ? void 0 : _b.value;
-          if (pageActive === false || tabActive === false) {
-            setTimeout(() => {
+          if (!isContextActive()) {
+            if (pendingTimerRef.current || pendingDisposerRef.current) {
+              return;
+            }
+            pendingTimerRef.current = setTimeout(() => {
+              pendingTimerRef.current = null;
               if (pendingDisposerRef.current) {
                 return;
               }
-              const disposer = (0, import_reactive.autorun)(() => {
-                var _a2, _b2, _c, _d, _e, _f;
-                if (((_b2 = (_a2 = ctxRef.current) == null ? void 0 : _a2.pageActive) == null ? void 0 : _b2.value) && (((_d = (_c = ctxRef.current) == null ? void 0 : _c.tabActive) == null ? void 0 : _d.value) === true || ((_f = (_e = ctxRef.current) == null ? void 0 : _e.tabActive) == null ? void 0 : _f.value) === void 0)) {
+              if (isContextActive()) {
+                updater();
+                return;
+              }
+              pendingDisposerRef.current = (0, import_reactive.reaction)(
+                () => isContextActive(),
+                (active) => {
+                  if (!active) {
+                    return;
+                  }
+                  clearPendingDisposer();
                   updater();
-                  disposer == null ? void 0 : disposer();
-                  pendingDisposerRef.current = null;
+                },
+                {
+                  name: "FlowObserverPendingUpdate"
                 }
-              });
-              pendingDisposerRef.current = disposer;
+              );
             });
             return;
           }
-          if (pendingDisposerRef.current) {
-            pendingDisposerRef.current();
-            pendingDisposerRef.current = null;
-          }
+          clearPendingTimer();
+          clearPendingDisposer();
           updater();
         },
         ...options

package/lib/runjs-context/snippets/scene/detail/set-field-style.snippet.js

@@ -32,18 +32,18 @@ module.exports = __toCommonJS(set_field_style_snippet_exports);
 const snippet = {
   contexts: ["*"],
   scenes: ["detailFieldEvent", "formFieldEvent"],
-  prefix: "sn-field-style",
-  label: "Set field style",
-  description: "Customize form and detail field styles",
+  prefix: "sn-item-style",
+  label: "Set form item/details item style",
+  description: "Customize form item and details item container styles",
   locales: {
     "zh-CN": {
-      label: "\u8868\u5355\u3001\u8BE6\u60C5\u5B57\u6BB5\u6837\u5F0F\u8BBE\u7F6E",
-      description: "\u81EA\u5B9A\u4E49\u8868\u5355\u5B57\u6BB5\u548C\u8BE6\u60C5\u5B57\u6BB5\u7684\u6837\u5F0F"
+      label: "\u8BBE\u7F6E\u8868\u5355\u9879/\u8BE6\u60C5\u9879\u6837\u5F0F",
+      description: "\u81EA\u5B9A\u4E49\u8868\u5355\u9879\u548C\u8BE6\u60C5\u9879\u5BB9\u5668\u6837\u5F0F"
     }
   },
   content: `
-ctx.model.subModels.field.props.style = {
-  fontWeight: 900,
+ctx.model.props.style = {
+  background: 'red',
 };
 `
 };

package/lib/runjs-context/snippets/scene/table/set-cell-style.snippet.js

@@ -45,7 +45,7 @@ const snippet = {
 ctx.model.props.onCell = (record, rowIndex) => {
   return {
     style: {
-      fontWeight: 900,
+      background: 'red',
     },
   };
 };

package/lib/types.d.ts

@@ -316,17 +316,28 @@ export type FlowModelLoaderResult = ModelConstructor | {
  */
 export type FlowModelLoader = () => Promise<FlowModelLoaderResult>;
 /**
- * FlowModel loader entry.
- * Future contribution-style fields are intentionally kept as commented placeholders in phase A
- * and are not consumed by current runtime logic.
+ * FlowModel loader entry (normalized internal form).
  */
 export interface FlowModelLoaderEntry {
     loader: FlowModelLoader;
+    extends?: string[];
 }
 /**
- * FlowModel loader entry map.
+ * FlowModel loader input (user-facing form for registerModelLoaders).
+ * The `extends` field accepts flexible formats that will be normalized to `string[]` at registration time.
+ */
+export interface FlowModelLoaderInput {
+    loader: FlowModelLoader;
+    extends?: string | ModelConstructor | (string | ModelConstructor)[];
+}
+/**
+ * FlowModel loader entry map (normalized internal form).
  */
 export type FlowModelLoaderMap = Record<string, FlowModelLoaderEntry>;
+/**
+ * FlowModel loader input map (user-facing form for registerModelLoaders).
+ */
+export type FlowModelLoaderInputMap = Record<string, FlowModelLoaderInput>;
 /**
  * Batch ensure result.
  */
@@ -340,18 +351,6 @@ export interface EnsureBatchResult {
 }
 export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
     findOne(query: Record<string, any>): Promise<Record<string, any> | null>;
-    /**
-     * Ensure a model exists (create if missing) in a single request.
-     */
-    ensure: (values: Record<string, any>, options?: {
-        includeAsyncNode?: boolean;
-    }) => Promise<Record<string, any> | null>;
-    /**
-     * Optional: run multiple ops in a single transaction (server capability).
-     */
-    mutate?: (values: Record<string, any>, options?: {
-        includeAsyncNode?: boolean;
-    }) => Promise<Record<string, any>>;
     save(model: T, options?: {
         onlyStepParams?: boolean;
     }): Promise<Record<string, any>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.1.0-alpha.13",
+  "version": "2.1.0-alpha.15",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,9 +8,10 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.1.0-alpha.13",
-    "@nocobase/shared": "2.1.0-alpha.13",
+    "@nocobase/sdk": "2.1.0-alpha.15",
+    "@nocobase/shared": "2.1.0-alpha.15",
     "ahooks": "^3.7.2",
+    "axios": "^1.7.0",
     "dayjs": "^1.11.9",
     "dompurify": "^3.0.2",
     "lodash": "^4.x",
@@ -36,5 +37,5 @@
   ],
   "author": "NocoBase Team",
   "license": "Apache-2.0",
-  "gitHead": "2807a8948412d9c235115a31a81a66f7c82dd173"
+  "gitHead": "7c86e75b0af4b9f532c8ebf5ef96a7423b0ab60e"
 }

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

@@ -89,13 +89,7 @@ describe('FlowEngine', () => {
     class MockFlowModelRepository implements IFlowModelRepository {
       // 使用可配置返回值，便于不同用例控制 findOne 行为
       findOneResult: any = null;
-      ensureResult: any = null;
-      ensureCalls = 0;
       save = vi.fn(async (model: FlowModel) => ({ success: true, uid: model.uid }));
-      async ensure() {
-        this.ensureCalls += 1;
-        return this.ensureResult ? JSON.parse(JSON.stringify(this.ensureResult)) : null;
-      }
       async findOne() {
         // 返回深拷贝，避免被测试过程修改
         return this.findOneResult ? JSON.parse(JSON.stringify(this.findOneResult)) : null;
@@ -194,47 +188,171 @@ describe('FlowEngine', () => {
       expect(Array.isArray(mounted)).toBe(false);
       expect(mounted?.uid).toBe('c3');
     });
+  });
 
-    it('should call repository.ensure with repository context preserved', async () => {
-      const parent = engine.createModel({ uid: 'p4', use: 'FlowModel' });
+  describe('getSubclassesOfAsync', () => {
+    it('should return async-loaded subclasses matching extends declaration', async () => {
+      class AsyncSubModelD extends BaseModel {}
+      class AsyncSubModelE extends BaseModel {}
 
-      repo.ensureResult = {
-        uid: 'c4',
-        use: 'FlowModel',
-        parentId: parent.uid,
-        subKey: 'page',
-        subType: 'object',
-      };
+      engine.registerModelLoaders({
+        AsyncSubModelD: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModelD }),
+        },
+        AsyncSubModelE: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModelE }),
+        },
+      });
 
-      const child = await engine.loadOrCreateModel({
-        parentId: parent.uid,
-        subKey: 'page',
-        subType: 'object',
-        use: 'FlowModel',
-        async: true,
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+
+      // Sync-registered subclasses
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(true);
+      expect(result.has('SubModelC')).toBe(true);
+      // Async-loaded subclasses
+      expect(result.has('AsyncSubModelD')).toBe(true);
+      expect(result.has('AsyncSubModelE')).toBe(true);
+      // Base class excluded
+      expect(result.has('BaseModel')).toBe(false);
+    });
+
+    it('should merge sync-registered and async-loaded subclasses', async () => {
+      class AsyncSubModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncSubModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ AsyncSubModel }),
+        },
       });
 
-      expect(child).toBeTruthy();
-      expect(repo.ensureCalls).toBe(1);
-      expect((parent.subModels as any).page).toBe(child);
-      expect(repo.save).not.toHaveBeenCalled();
+      const result = await engine.getSubclassesOfAsync('BaseModel');
+
+      // Sync: SubModelA, SubModelB, SubModelC
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(true);
+      expect(result.has('SubModelC')).toBe(true);
+      // Async
+      expect(result.has('AsyncSubModel')).toBe(true);
+      expect(result.size).toBe(4);
     });
 
-    it('should not persist through ensure when skipSave is true', async () => {
-      repo.findOneResult = null;
+    it('should support extends as string array (multiple parents)', async () => {
+      class AnotherBase extends FlowModel {}
+      class MultiParentModel extends BaseModel {}
+
+      engine.registerModels({ AnotherBase });
+      engine.registerModelLoaders({
+        MultiParentModel: {
+          extends: ['BaseModel', 'AnotherBase'],
+          loader: async () => ({ MultiParentModel }),
+        },
+      });
+
+      const resultBase = await engine.getSubclassesOfAsync(BaseModel);
+      expect(resultBase.has('MultiParentModel')).toBe(true);
+
+      // Also found by AnotherBase (even though actual inheritance is from BaseModel, not AnotherBase)
+      // The extends declaration triggers loading, but isInheritedFrom validation will exclude it from AnotherBase results
+      const resultAnother = await engine.getSubclassesOfAsync(AnotherBase);
+      expect(resultAnother.has('MultiParentModel')).toBe(false);
+    });
+
+    it('should support extends as ModelConstructor', async () => {
+      class AsyncCtorSubModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        AsyncCtorSubModel: {
+          extends: BaseModel,
+          loader: async () => ({ AsyncCtorSubModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      expect(result.has('AsyncCtorSubModel')).toBe(true);
+    });
+
+    it('should validate actual inheritance and warn on mismatch', async () => {
+      class UnrelatedModel extends FlowModel {}
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
-      const model = await engine.loadOrCreateModel(
-        {
-          uid: 'c5',
-          use: 'FlowModel',
+      engine.registerModelLoaders({
+        UnrelatedModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ UnrelatedModel }),
         },
-        { skipSave: true },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      expect(result.has('UnrelatedModel')).toBe(false);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("declares extends 'BaseModel' but does not actually inherit from it"),
       );
 
-      expect(model).toBeTruthy();
-      expect(model?.uid).toBe('c5');
-      expect(repo.ensureCalls).toBe(0);
-      expect(repo.save).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+    });
+
+    it('should resolve base class from loaders if not in _modelClasses', async () => {
+      const freshEngine = new FlowEngine();
+
+      class LazyBase extends FlowModel {}
+      class LazySub extends LazyBase {}
+
+      freshEngine.registerModelLoaders({
+        LazyBase: {
+          loader: async () => ({ LazyBase }),
+        },
+        LazySub: {
+          extends: 'LazyBase',
+          loader: async () => ({ LazySub }),
+        },
+      });
+
+      const result = await freshEngine.getSubclassesOfAsync('LazyBase');
+      expect(result.has('LazySub')).toBe(true);
+      expect(result.size).toBe(1);
+    });
+
+    it('should return empty Map when base class cannot be found', async () => {
+      const result = await engine.getSubclassesOfAsync('NonExistentModel');
+      expect(result.size).toBe(0);
+    });
+
+    it('should support filter parameter on both sync and async sources', async () => {
+      class FilteredAsyncModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        FilteredAsyncModel: {
+          extends: 'BaseModel',
+          loader: async () => ({ FilteredAsyncModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel, (_ModelClass, name) => name.startsWith('SubModelA'));
+
+      // Only SubModelA passes the filter (SubModelB, SubModelC, FilteredAsyncModel excluded)
+      expect(result.has('SubModelA')).toBe(true);
+      expect(result.has('SubModelB')).toBe(false);
+      expect(result.has('SubModelC')).toBe(false);
+      expect(result.has('FilteredAsyncModel')).toBe(false);
+    });
+
+    it('should not include loaders without extends declaration', async () => {
+      class NoExtendsModel extends BaseModel {}
+
+      engine.registerModelLoaders({
+        NoExtendsModel: {
+          loader: async () => ({ NoExtendsModel }),
+        },
+      });
+
+      const result = await engine.getSubclassesOfAsync(BaseModel);
+      // Only sync-registered subclasses; NoExtendsModel has no extends, so not discovered
+      expect(result.has('NoExtendsModel')).toBe(false);
+      expect(result.has('SubModelA')).toBe(true);
     });
   });
 });