ee-core 5.0.0-beta.2 → 5.0.0-beta.5

package/dist/cjs/core/loader/file_loader.js

@@ -4,39 +4,61 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileLoader = exports.EXPORTS = exports.FULLPATH = void 0;
+/**
+ * @module core/loader/file_loader
+ * @description Generic file loader. Scans files in a specified directory and organizes
+ * exported content into nested objects based on directory structure, for use by
+ * controllers, services, and other modules.
+ *
+ * Three loading methods:
+ * - parse(): Synchronous file scanning + require(), suitable for CJS dev mode
+ * - parseFromRegistry(): Load from pre-registered registry, suitable for bundle mode
+ * - parseAsync(): Asynchronous file scanning + import(), suitable for ESM dev mode
+ *
+ * Directory structure to property mapping:
+ * ```
+ * controller/user.js       -> target.controller.user
+ * controller/admin/login.js -> target.controller.admin.login
+ * ```
+ *
+ * Property naming style is controlled by caseStyle:
+ * - 'camel': camelCase (default) — user-info -> userInfo
+ * - 'lower': all lowercase — User Info -> user info (used by controllers)
+ */
 const debug_1 = __importDefault(require("debug"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const globby_1 = __importDefault(require("globby"));
+const globby_1 = require("globby");
 const type_check_js_1 = require("../../utils/type_check.js");
 const index_js_1 = require("../utils/index.js");
 const wrap_js_1 = require("../../utils/wrap.js");
 const debugLog = (0, debug_1.default)('ee-core:core:loader:file_loader');
+/** Symbol marker: records the full path of a file */
 exports.FULLPATH = Symbol('LOADER_ITEM_FULLPATH');
+/** Symbol marker: indicates the export has been processed by the loader */
 exports.EXPORTS = Symbol('LOADER_ITEM_EXPORTS');
+/** Default configuration */
 const defaults = {
+    /** Property naming style */
     caseStyle: 'camel',
+    /** Custom initializer: performs additional processing on exported content */
     initializer: null,
+    /** Whether to automatically invoke function-type exports */
     call: true,
+    /** Injection arguments for function calls */
     inject: undefined,
+    /** Target object (deprecated; now created internally by load()) */
     target: null,
+    /** File match patterns (overrides default filePatterns) */
     match: undefined,
 };
 /**
- * Load files from directory to target object.
+ * FileLoader — File loader
+ *
+ * Organizes exported content from files in a directory into nested property objects
+ * based on directory structure. Supports synchronous/asynchronous loading and registry mode.
  */
 class FileLoader {
-    /**
-     * @class
-     * @param {Object} options - options
-     * @param {String|Array} options.directory - directories to be loaded
-     * @param {Object} options.target - attach the target object from loaded files
-     * @param {String} options.match - match the files when load, support glob, default to all js files
-     * @param {Function} options.initializer - custom file exports, receive two parameters, first is the inject object(if not js file, will be content buffer), second is an `options` object that contain `path`
-     * @param {Boolean} options.call - determine whether invoke when exports is function
-     * @param {Object} options.inject - an object that be the argument when invoke the function
-     * @param {String|Function} options.caseStyle - set property's case when converting a filepath to property list.
-     */
     constructor(options) {
         if (!options.directory) {
             throw new Error('options.directory is required');
@@ -45,30 +67,75 @@ class FileLoader {
         debugLog('[constructor] options: %o', this.options);
     }
     /**
-     * attach items to target object. Mapping the directory to properties.
-     * `xxx/group/repository.js` => `target.group.repository`
-     * @return {Object} target
+     * Process a single export
+     *
+     * Execution flow:
+     * 1. Run initializer (if present) for custom processing of the export
+     * 2. Set pathName and fullPath properties on classes
+     * 3. Class/generator function/async function/bytecode class -> return directly
+     * 4. Plain function -> auto-invoke based on the call option
+     *
+     * @param exports - File exported content
+     * @param fullpath - File full path
+     * @param properties - Property path (array converted from directory + filename)
+     * @param dirName - Directory name (used as property path prefix)
+     * @returns LoaderItem or null (skipped when export is null/undefined)
      */
-    load() {
-        const items = this.parse();
+    _processExport(exports, fullpath, properties, dirName) {
+        if (exports == null)
+            return null;
+        const pathName = dirName + '.' + properties.join('.');
+        const initializer = this.options.initializer;
+        if (initializer) {
+            exports = initializer(exports, { pathName, path: fullpath });
+        }
+        // Set path info on classes for IPC routing and debugging
+        if ((0, type_check_js_1.isClass)(exports) || (0, index_js_1.isBytecodeClass)(exports)) {
+            exports.prototype.pathName = pathName;
+            exports.prototype.fullPath = fullpath;
+        }
+        // Class/generator/async/bytecode class -> do not auto-invoke, return directly
+        if ((0, type_check_js_1.isClass)(exports) || (0, type_check_js_1.isGeneratorFunction)(exports) || (0, type_check_js_1.isAsyncFunction)(exports) || (0, index_js_1.isBytecodeClass)(exports)) {
+            return { fullpath, properties, exports };
+        }
+        // Plain function: auto-invoke based on the call option
+        if (this.options.call && (0, type_check_js_1.isFunction)(exports)) {
+            exports = exports(this.options.inject);
+            if (exports != null) {
+                return { fullpath, properties, exports };
+            }
+        }
+        return { fullpath, properties, exports };
+    }
+    /**
+     * Assign load items to target object
+     *
+     * Creates nested objects level by level along the property path, ultimately mounting
+     * the exported content at the leaf node. Also marks non-primitive exports with
+     * FULLPATH and EXPORTS symbols.
+     *
+     * @param items - Load item list
+     * @returns Nested property object
+     */
+    _assignToTarget(items) {
         const target = {};
         for (const item of items) {
-            // item { fullpath, properties: [ 'a', 'b', 'c'], exports }
             let current = target;
             for (let i = 0; i < item.properties.length; i++) {
                 const property = item.properties[i];
                 if (!property)
                     continue;
-                // properties is a path slice, only the last value is the file name
                 const isLast = i === item.properties.length - 1;
                 if (isLast) {
                     current[property] = item.exports;
+                    // Mark full path and export identifier for non-primitive types
                     if (item.exports && !(0, type_check_js_1.isPrimitive)(item.exports)) {
                         item.exports[exports.FULLPATH] = item.fullpath;
                         item.exports[exports.EXPORTS] = true;
                     }
                 }
                 else {
+                    // Intermediate level: ensure object exists
                     current[property] = current[property] || {};
                     current = current[property];
                 }
@@ -77,19 +144,23 @@ class FileLoader {
         return target;
     }
     /**
-     * Parse files from given directories, then return an items list, each item contains properties and exports.
-     * For example, parse `controller/group/repository.js`
-     * It returns a item
-     * ```
-     * {
-     *   fullpath: '',
-     *   properties: [ 'group', 'repository' ],
-     *   exports: { ... },
-     * }
-     * ```
-     * `Properties` is an array that contains the directory of a filepath.
-     * `Exports` depends on type, if exports is a function, it will be called. if initializer is specified, it will be called with exports for customizing.
-     * @return {Array} items
+     * Load files and build target object
+     *
+     * Loads from registry when available (bundle mode), otherwise scans filesystem (dev mode).
+     *
+     * @returns Nested property object organized by directory structure
+     */
+    load() {
+        const items = this.options.registry ? this.parseFromRegistry() : this.parse();
+        return this._assignToTarget(items);
+    }
+    /**
+     * Parse files synchronously from filesystem
+     *
+     * Uses globby to scan directories and require() to load files.
+     * Suitable for CJS dev mode.
+     *
+     * @returns Load item list
      */
     parse() {
         let files = (this.options.match || (0, index_js_1.filePatterns)());
@@ -106,48 +177,103 @@ class FileLoader {
         const items = [];
         debugLog('[parse] directories %o', directories);
         for (const directory of directories) {
-            const filepaths = globby_1.default.sync(files, { cwd: directory });
+            const filepaths = (0, globby_1.globbySync)(files, { cwd: directory });
             debugLog('[parse] filepaths %o', filepaths);
             for (const filepath of filepaths) {
                 const fullpath = path_1.default.join(directory, filepath);
                 if (!fs_1.default.statSync(fullpath).isFile())
                     continue;
-                // get properties
-                // controller/foo/bar.js => [ 'foo', 'bar' ]
                 const properties = (0, wrap_js_1.getProperties)(filepath, { caseStyle: this.options.caseStyle });
-                // debugLog('[parse] properties %o', properties);
-                // controller/foo/bar.js => controller.foo.bar
-                const dirName = directory.split(/[/\\]/).slice(-1)[0];
-                const pathName = dirName + '.' + properties.join('.');
-                // debugLog('[parse] pathName %s', pathName);
-                // get exports from the file
-                let exports = (0, index_js_1.loadFile)(fullpath);
-                // ignore exports when it's null or false returned by filter function
-                if (exports == null)
-                    continue;
-                const initializer = this.options.initializer;
-                if (initializer) {
-                    exports = initializer(exports, { pathName, path: fullpath });
-                }
-                // set properties of class
-                if ((0, type_check_js_1.isClass)(exports) || (0, index_js_1.isBytecodeClass)(exports)) {
-                    exports.prototype.pathName = pathName;
-                    exports.prototype.fullPath = fullpath;
-                }
-                // class / generator / async / bytecodeClass → return directly
-                if ((0, type_check_js_1.isClass)(exports) || (0, type_check_js_1.isGeneratorFunction)(exports) || (0, type_check_js_1.isAsyncFunction)(exports) || (0, index_js_1.isBytecodeClass)(exports)) {
-                    items.push({ fullpath, properties, exports });
+                // Take the last level of the directory as the property prefix (e.g. 'controller')
+                const dirName = directory.split(/[/\\]/).slice(-1)[0] || 'unknown';
+                const exports = (0, index_js_1.loadFile)(fullpath);
+                const item = this._processExport(exports, fullpath, properties, dirName);
+                if (item)
+                    items.push(item);
+            }
+        }
+        return items;
+    }
+    /**
+     * Parse modules from pre-registered registry
+     *
+     * In bundle mode, the esbuild plugin pre-registers controller/configuration info
+     * into global variables. This method reads the registry directly without filesystem scanning.
+     *
+     * @returns Load item list
+     */
+    parseFromRegistry() {
+        const registry = this.options.registry;
+        if (!registry)
+            return [];
+        const items = [];
+        debugLog('[parseFromRegistry] entries %d', registry.length);
+        for (const entry of registry) {
+            let exports = entry.module;
+            // ESM interop: handle modules with __esModule marker
+            if (exports && exports.__esModule) {
+                exports = 'default' in exports
+                    ? exports.default
+                    : exports;
+            }
+            const fullpath = entry.fullpath;
+            const properties = entry.properties;
+            // Extract the second-to-last directory name from registry entry path (e.g. 'controller')
+            const dirName = fullpath.split(/[/\\]/).slice(-2, -1)[0] || 'controller';
+            const item = this._processExport(exports, fullpath, properties, dirName);
+            if (item)
+                items.push(item);
+        }
+        return items;
+    }
+    /**
+     * Load files asynchronously and build target object
+     *
+     * Uses globby async scanning and import() dynamic loading.
+     * Suitable for ESM dev mode.
+     *
+     * @returns Nested property object organized by directory structure
+     */
+    async loadAsync() {
+        const items = await this.parseAsync();
+        return this._assignToTarget(items);
+    }
+    /**
+     * Parse files asynchronously from filesystem
+     *
+     * Uses globby async scanning and fs.promises.stat for async file checking.
+     * Suitable for ESM dev mode.
+     *
+     * @returns Load item list
+     */
+    async parseAsync() {
+        let files = (this.options.match || (0, index_js_1.filePatterns)());
+        if (!Array.isArray(files)) {
+            files = [files];
+        }
+        let directories;
+        if (Array.isArray(this.options.directory)) {
+            directories = this.options.directory;
+        }
+        else {
+            directories = [this.options.directory];
+        }
+        const items = [];
+        debugLog('[parseAsync] directories %o', directories);
+        for (const directory of directories) {
+            const filepaths = await (0, globby_1.globby)(files, { cwd: directory });
+            debugLog('[parseAsync] filepaths %o', filepaths);
+            for (const filepath of filepaths) {
+                const fullpath = path_1.default.join(directory, filepath);
+                const stat = await fs_1.default.promises.stat(fullpath);
+                if (!stat.isFile())
                     continue;
-                }
-                // whether to execute the function
-                if (this.options.call && (0, type_check_js_1.isFunction)(exports)) {
-                    exports = exports(this.options.inject);
-                    if (exports != null) {
-                        items.push({ fullpath, properties, exports });
-                        continue;
-                    }
-                }
-                items.push({ fullpath, properties, exports });
+                const properties = (0, wrap_js_1.getProperties)(filepath, { caseStyle: this.options.caseStyle });
+                const dirName = directory.split(/[/\\]/).slice(-1)[0] || 'unknown';
+                const exports = await (0, index_js_1.loadFileAsync)(fullpath);
+                const item = this._processExport(exports, fullpath, properties, dirName);
+                if (item)
+                    items.push(item);
             }
         }
         return items;

package/dist/cjs/core/loader/file_loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"file_loader.js","sourceRoot":"","sources":["../../../../src/core/loader/file_loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file_loader.js","sourceRoot":"","sources":["../../../../src/core/loader/file_loader.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/utils/index.d.ts

@@ -1,15 +1,70 @@
+/**
+ * @module core/utils
+ * @description Core utility functions. Provides file loading, function invocation, bytecode class detection,
+ * and other foundational capabilities. Serves as a low-level dependency for FileLoader and other modules.
+ */
 import 'bytenode';
 declare const extensions: NodeJS.RequireExtensions;
+/**
+ * Load a file synchronously
+ *
+ * Execution flow:
+ * 1. Non-JS files (extensions not in Module._extensions) -> return file content as Buffer
+ * 2. JS/CJS/JSC files -> load module using require()
+ * 3. ESM modules (with __esModule marker) -> extract default export
+ *
+ * @param filepath - Absolute file path
+ * @returns File content (Buffer) or module export value
+ * @throws Throws an error containing the file path when file loading fails
+ */
 export declare function loadFile(filepath: string): unknown;
+/**
+ * Call a function with bound context
+ *
+ * @param fn - Function to call
+ * @param args - Function argument list
+ * @param ctx - Function execution context (this binding); if not provided, calls directly
+ * @returns Function return value; returns undefined if fn is not a function
+ */
 export declare function callFn(fn: (...args: unknown[]) => unknown, args?: unknown[], ctx?: unknown): Promise<unknown>;
+/**
+ * Get the relative path name of a file
+ *
+ * Converts an absolute path to a relative path based on baseDir, using forward slashes as separators.
+ *
+ * @param filepath - Absolute file path
+ * @param baseDir - Base directory
+ * @returns Relative path (forward slash separated)
+ */
 export declare function getResolvedFilename(filepath: string, baseDir: string): string;
 /**
- * 字节码类
+ * Determine if an export is a bytecode class
+ *
+ * Checks whether the toString() result contains '[class'.
+ * Classes from bytenode-compiled .jsc files appear as '[class XXX]' in Node.js.
+ *
+ * @param exports - Export value to check
+ * @returns Whether it is a bytecode class
  */
 export declare function isBytecodeClass(exports: unknown): boolean;
 /**
- * 文件类型
+ * Get supported file match patterns
+ *
+ * Used for filtering file types when globby scans directories.
+ *
+ * @returns File pattern list (.js and .jsc)
  */
 export declare function filePatterns(): string[];
 export { extensions };
+/**
+ * Load a file asynchronously (ESM support)
+ *
+ * Same functionality as loadFile, but uses dynamic import() to load modules,
+ * supporting ESM format files. Non-JS files are read using fs.promises.readFile.
+ *
+ * @param filepath - Absolute file path
+ * @returns File content (Buffer) or module export value
+ * @throws Throws an error containing the file path when file loading fails
+ */
+export declare function loadFileAsync(filepath: string): Promise<unknown>;
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,CAAC;AAelB,QAAA,MAAM,UAAU,EAAE,MAAM,CAAC,iBAAsC,CAAC;AAEhE,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAmBlD;AAED,wBAAsB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAInH;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAIzD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,UAAU,CAAC;AAelB,QAAA,MAAM,UAAU,EAAE,MAAM,CAAC,iBAAsC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAmBlD;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAInH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAGzD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBtE"}

package/dist/cjs/core/utils/index.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9,32 +42,49 @@ exports.callFn = callFn;
 exports.getResolvedFilename = getResolvedFilename;
 exports.isBytecodeClass = isBytecodeClass;
 exports.filePatterns = filePatterns;
+exports.loadFileAsync = loadFileAsync;
+/**
+ * @module core/utils
+ * @description Core utility functions. Provides file loading, function invocation, bytecode class detection,
+ * and other foundational capabilities. Serves as a low-level dependency for FileLoader and other modules.
+ */
 require("bytenode");
 const type_check_js_1 = require("../../utils/type_check.js");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const module_1 = require("module");
-const requireMod = (0, module_1.createRequire)(__filename);
+// __filename is available in CJS; in pure ESM without a bundler, use cwd as the base path for createRequire
+const requireMod = (0, module_1.createRequire)(typeof __filename !== 'undefined'
+    ? __filename
+    : path_1.default.join(process.cwd(), '__virtual__.js'));
 const Module = requireMod('module');
-// Module._extensions:
-// '.js': [Function (anonymous)],
-// '.json': [Function (anonymous)],
-// '.node': [Function: func],
-// '.jsc': [Function (anonymous)]
+// File extensions natively supported by Node.js (including .jsc registered by bytenode)
 const extensions = Module._extensions;
 exports.extensions = extensions;
+/**
+ * Load a file synchronously
+ *
+ * Execution flow:
+ * 1. Non-JS files (extensions not in Module._extensions) -> return file content as Buffer
+ * 2. JS/CJS/JSC files -> load module using require()
+ * 3. ESM modules (with __esModule marker) -> extract default export
+ *
+ * @param filepath - Absolute file path
+ * @returns File content (Buffer) or module export value
+ * @throws Throws an error containing the file path when file loading fails
+ */
 function loadFile(filepath) {
     try {
-        // if not js module, just return content buffer
+        // Non-JS module, return file content directly
         const extname = path_1.default.extname(filepath);
         if (extname && !extensions[extname]) {
             return fs_1.default.readFileSync(filepath);
         }
-        // require js module
+        // Load JS module
         const obj = requireMod(filepath);
         if (!obj)
             return obj;
-        // it's es module
+        // ESM interop: extract default export
         if (obj.__esModule)
             return 'default' in obj ? obj.default : obj;
         return obj;
@@ -45,29 +95,87 @@ function loadFile(filepath) {
         throw error;
     }
 }
+/**
+ * Call a function with bound context
+ *
+ * @param fn - Function to call
+ * @param args - Function argument list
+ * @param ctx - Function execution context (this binding); if not provided, calls directly
+ * @returns Function return value; returns undefined if fn is not a function
+ */
 async function callFn(fn, args, ctx) {
     args = args || [];
     if (!(0, type_check_js_1.isFunction)(fn))
         return undefined;
     return ctx ? fn.call(ctx, ...args) : fn(...args);
 }
+/**
+ * Get the relative path name of a file
+ *
+ * Converts an absolute path to a relative path based on baseDir, using forward slashes as separators.
+ *
+ * @param filepath - Absolute file path
+ * @param baseDir - Base directory
+ * @returns Relative path (forward slash separated)
+ */
 function getResolvedFilename(filepath, baseDir) {
     const reg = /[/\\]/g;
     return filepath.replace(baseDir + path_1.default.sep, '').replace(reg, '/');
 }
 /**
- * 字节码类
+ * Determine if an export is a bytecode class
+ *
+ * Checks whether the toString() result contains '[class'.
+ * Classes from bytenode-compiled .jsc files appear as '[class XXX]' in Node.js.
+ *
+ * @param exports - Export value to check
+ * @returns Whether it is a bytecode class
  */
 function isBytecodeClass(exports) {
     if (!exports)
         return false;
-    // 标识
     return String(exports).indexOf('[class') !== -1;
 }
 /**
- * 文件类型
+ * Get supported file match patterns
+ *
+ * Used for filtering file types when globby scans directories.
+ *
+ * @returns File pattern list (.js and .jsc)
  */
 function filePatterns() {
     return ['**/*.js', '**/*.jsc'];
 }
+/**
+ * Load a file asynchronously (ESM support)
+ *
+ * Same functionality as loadFile, but uses dynamic import() to load modules,
+ * supporting ESM format files. Non-JS files are read using fs.promises.readFile.
+ *
+ * @param filepath - Absolute file path
+ * @returns File content (Buffer) or module export value
+ * @throws Throws an error containing the file path when file loading fails
+ */
+async function loadFileAsync(filepath) {
+    try {
+        const extname = path_1.default.extname(filepath);
+        // Non-JS/ESM files: return content as Buffer
+        if (extname && !extensions[extname] && extname !== '.mjs') {
+            return fs_1.default.promises.readFile(filepath);
+        }
+        // Dynamic import, supporting both ESM and CJS
+        const obj = await Promise.resolve(`${filepath}`).then(s => __importStar(require(s)));
+        if (!obj)
+            return obj;
+        // ESM interop: extract default export
+        if (obj.__esModule)
+            return 'default' in obj ? obj.default : obj;
+        return obj;
+    }
+    catch (err) {
+        const error = err;
+        error.message = `[ee-core] load file async: ${filepath}, error: ${error.message}`;
+        throw error;
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/cjs/core/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/utils/index.ts"],"names":[],"mappings":";;;;;;AAiBA,4BAmBC;AAED,wBAIC;AAED,kDAGC;AAKD,0CAIC;AAKD,oCAEC;AA/DD,oBAAkB;AAClB,6DAA0E;AAC1E,gDAAwB;AACxB,4CAAoB;AACpB,mCAAuC;AAEvC,MAAM,UAAU,GAAG,IAAA,sBAAa,EAAC,UAAU,CAAC,CAAC;AAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;AAEpC,sBAAsB;AACtB,iCAAiC;AACjC,mCAAmC;AACnC,6BAA6B;AAC7B,iCAAiC;AAEjC,MAAM,UAAU,GAA6B,MAAM,CAAC,WAAW,CAAC;AAkDvD,gCAAU;AAhDnB,SAAgB,QAAQ,CAAC,QAAgB;IACvC,IAAI,CAAC;QACH,+CAA+C;QAC/C,MAAM,OAAO,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,OAAO,YAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC;QAED,oBAAoB;QACpB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG;YAAE,OAAO,GAAG,CAAC;QACrB,iBAAiB;QACjB,IAAI,GAAG,CAAC,UAAU;YAAE,OAAO,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QAChE,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,GAAY,CAAC;QAC3B,KAAK,CAAC,OAAO,GAAG,wBAAwB,QAAQ,YAAY,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5E,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,MAAM,CAAC,EAAmC,EAAE,IAAgB,EAAE,GAAa;IAC/F,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;IAClB,IAAI,CAAC,IAAA,0BAAe,EAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;AACnD,CAAC;AAED,SAAgB,mBAAmB,CAAC,QAAgB,EAAE,OAAe;IACnE,MAAM,GAAG,GAAG,QAAQ,CAAC;IACrB,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,GAAG,cAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACpE,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,OAAgB;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,KAAK;IACL,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/utils/index.ts"],"names":[],"mappings":"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"}