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

package/dist/esm/utils/port/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/port/index.ts"],"names":[],"mappings":"AAkFA,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2CvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/port/index.ts"],"names":[],"mappings":"AA4JA,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAOvC"}

package/dist/esm/utils/port/index.js

@@ -4,27 +4,67 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPort = getPort;
+exports.releasePortLocks = releasePortLocks;
+/**
+ * @module utils/port
+ * @description Port allocation utility. Provides getPort() function to find available TCP ports
+ * within a specified range, with a locking mechanism to prevent concurrent port conflicts
+ * within the same process.
+ *
+ * Port allocation strategy:
+ * 1. Create a temporary TCP server listening on the target port to verify availability
+ * 2. Check if the port is in the locked set (prevents concurrent allocation of the same port)
+ * 3. If the port is unavailable or locked, automatically increment the port number and retry
+ * 4. Port 0 means let the OS automatically assign a random available port
+ *
+ * Locking mechanism:
+ * - Uses old and young Sets to maintain allocated ports
+ * - Rotates every 15 seconds: young -> old, old is cleared and released
+ * - Two-level locking ensures ports are not re-allocated shortly after being assigned
+ * - Call releasePortLocks() to manually clear all locks
+ */
 const net_1 = __importDefault(require("net"));
 const os_1 = __importDefault(require("os"));
+/**
+ * Port locked error
+ *
+ * Thrown when the specified port is locked (in use).
+ */
 class Locked extends Error {
     constructor(port) {
         super(`${port} is locked`);
     }
 }
+/** Locked port sets, split into old and young levels */
 const lockedPorts = {
+    /** Previously locked ports, about to be released */
     old: new Set(),
+    /** Currently locked ports */
     young: new Set(),
 };
-// On this interval, the old locked ports are discarded,
-// the young locked ports are moved to old locked ports,
-// and a new young set for locked ports are created.
+/**
+ * Port lock rotation interval (ms)
+ *
+ * Every this interval, the old set is discarded (ports released),
+ * the young set moves into old, and a new young set is created.
+ * Two-level rotation ensures ports are locked for at least 15 seconds.
+ */
 const releaseOldLockedPortsIntervalMs = 1000 * 15;
-// Lazily create interval on first use
+/** Rotation timer reference, lazily created to avoid resource usage when idle */
 let interval;
+/**
+ * Get all local network interface addresses
+ *
+ * Collects IP addresses of all network interfaces, and adds undefined (represents using default host)
+ * and '0.0.0.0' (represents listening on all IPv4 interfaces).
+ * When host is not specified, port availability needs to be verified on all interfaces.
+ *
+ * @returns Set of host addresses
+ */
 const getLocalHosts = () => {
     const interfaces = os_1.default.networkInterfaces();
-    // Add undefined value for createServer function to use default host,
-    // and default IPv4 host in case createServer defaults to IPv6.
+    // undefined lets createServer use default host;
+    // '0.0.0.0' is IPv4 wildcard address, prevents createServer defaulting to IPv6
     const results = new Set([undefined, '0.0.0.0']);
     for (const _interface of Object.values(interfaces)) {
         if (!_interface)
@@ -35,8 +75,19 @@ const getLocalHosts = () => {
     }
     return results;
 };
+/**
+ * Check if a single port is available on the specified host
+ *
+ * Creates a temporary TCP server to attempt listening; if successful, the port is available;
+ * if failed, the port is occupied. Uses server.unref() to ensure the temporary server
+ * doesn't prevent process exit.
+ *
+ * @param options - net.ListenOptions, containing port and host
+ * @returns Available port number
+ */
 const checkAvailablePort = (options) => new Promise((resolve, reject) => {
     const server = net_1.default.createServer();
+    // Don't prevent process exit
     server.unref();
     server.on('error', reject);
     server.listen(options, () => {
@@ -47,16 +98,30 @@ const checkAvailablePort = (options) => new Promise((resolve, reject) => {
         });
     });
 });
+/**
+ * Verify port availability across multiple hosts
+ *
+ * When host is not specified, port availability must be verified on each local network interface
+ * individually, ensuring the port is not occupied on any interface.
+ * EADDRNOTAVAIL and EINVAL errors indicate the interface doesn't support this port and can be skipped.
+ *
+ * @param options - Listen options
+ * @param hosts - Host address set
+ * @returns Available port number
+ */
 const getAvailablePort = async (options, hosts) => {
+    // When host is specified or port is 0 (OS auto-assign), only need to check once
     if (options.host || options.port === 0) {
         return checkAvailablePort(options);
     }
+    // When host is not specified, verify on all interfaces individually
     for (const host of hosts) {
         try {
             await checkAvailablePort({ port: options.port, host });
         }
         catch (error) {
             const err = error;
+            // Address unavailable or invalid: this interface doesn't support this port, skip and continue checking
             if (!['EADDRNOTAVAIL', 'EINVAL'].includes(err.code || '')) {
                 throw error;
             }
@@ -64,25 +129,64 @@ const getAvailablePort = async (options, hosts) => {
     }
     return options.port || 0;
 };
+/**
+ * Generate port check sequence
+ *
+ * Tries user-specified port list in order; if all are unavailable, falls back to port 0
+ * (OS auto-assigns a random available port).
+ *
+ * @param ports - User-specified port list
+ * @yields Port number to check
+ */
 function* portCheckSequence(ports) {
     if (ports) {
         for (const port of ports) {
             yield port;
         }
     }
+    // When all specified ports are unavailable, fall back to OS auto-assign
     yield 0;
 }
+/**
+ * Get an available TCP port
+ *
+ * Finds an available port within the specified range, with a two-level locking mechanism
+ * to prevent concurrent allocation conflicts.
+ * Search flow:
+ * 1. Try binding one by one according to the port check sequence
+ * 2. Check if the port is in the locked set (old or young)
+ * 3. On lock conflict: if a specific port was requested, throw Locked; otherwise auto-get a new port
+ * 4. After finding an available port, add it to the young locked set and return
+ *
+ * @param options - Port search options
+ * @returns Available port number
+ * @throws Error - Throws when all ports are unavailable
+ *
+ * @example
+ * ```ts
+ * // Get a system auto-assigned random port
+ * const port = await getPort();
+ *
+ * // Try a specific port, auto-find next if unavailable
+ * const port = await getPort({ port: 3000 });
+ *
+ * // Try multiple candidate ports
+ * const port = await getPort({ port: [3000, 3001, 3002] });
+ * ```
+ */
 async function getPort(options) {
     let ports;
     if (options) {
         ports = typeof options.port === 'number' ? [options.port] : options.port;
     }
+    // Lazily create rotation timer, initialize on first call
     if (interval === undefined) {
         interval = setInterval(() => {
+            // Rotate locked sets: young -> old, old is cleared and released
             lockedPorts.old = lockedPorts.young;
             lockedPorts.young = new Set();
         }, releaseOldLockedPortsIntervalMs);
-        // Does not exist in some environments (Electron, Jest jsdom env, browser, etc).
+        // unref ensures the timer doesn't prevent process exit (Electron/Jest environments may not have unref)
         if (interval.unref) {
             interval.unref();
         }
@@ -91,17 +195,22 @@ async function getPort(options) {
     for (const port of portCheckSequence(ports)) {
         try {
             let availablePort = await getAvailablePort({ ...options, port }, hosts);
+            // Check if port is in locked set, preventing concurrent allocation of the same port
             while (lockedPorts.old.has(availablePort) || lockedPorts.young.has(availablePort)) {
+                // Specified port number is locked -> throw exception to let caller know
                 if (port !== 0) {
                     throw new Locked(port);
                 }
+                // OS auto-assigned port is locked -> request a new one
                 availablePort = await getAvailablePort({ ...options, port: 0 }, hosts);
             }
+            // Found available port, add to young locked set
             lockedPorts.young.add(availablePort);
             return availablePort;
         }
         catch (error) {
             const err = error;
+            // EADDRINUSE (port occupied) and EACCES (insufficient permissions) are expected errors, try next port
             if (!['EADDRINUSE', 'EACCES'].includes(err.code || '') && !(error instanceof Locked)) {
                 throw error;
             }
@@ -109,4 +218,18 @@ async function getPort(options) {
     }
     throw new Error('No available ports found');
 }
+/**
+ * Clean up port lock resources
+ *
+ * Clears the rotation timer and releases all locked ports.
+ * Call during application shutdown to ensure resources are cleaned up, preventing timer leaks.
+ */
+function releasePortLocks() {
+    if (interval !== undefined) {
+        clearInterval(interval);
+        interval = undefined;
+    }
+    lockedPorts.old.clear();
+    lockedPorts.young.clear();
+}
 //# sourceMappingURL=index.js.map

package/dist/esm/utils/port/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/port/index.ts"],"names":[],"mappings":";;;;;AAuFA,0BA2CC;AAlID,8CAAsB;AACtB,4CAAoB;AAEpB,MAAM,MAAO,SAAQ,KAAK;IACxB,YAAY,IAAY;QACtB,KAAK,CAAC,GAAG,IAAI,YAAY,CAAC,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,IAAI,GAAG,EAAU;IACtB,KAAK,EAAE,IAAI,GAAG,EAAU;CACzB,CAAC;AAEF,wDAAwD;AACxD,wDAAwD;AACxD,oDAAoD;AACpD,MAAM,+BAA+B,GAAG,IAAI,GAAG,EAAE,CAAC;AAElD,sCAAsC;AACtC,IAAI,QAAoC,CAAC;AAEzC,MAAM,aAAa,GAAG,GAA4B,EAAE;IAClD,MAAM,UAAU,GAAG,YAAE,CAAC,iBAAiB,EAAE,CAAC;IAC1C,qEAAqE;IACrE,+DAA+D;IAC/D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAqB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;IAEpE,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,UAAU;YAAE,SAAS;QAC1B,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF,MAAM,kBAAkB,GAAG,CAAC,OAA0B,EAAmB,EAAE,CACzE,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IAC9B,MAAM,MAAM,GAAG,aAAG,CAAC,YAAY,EAAE,CAAC;IAClC,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE3B,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE;QAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC;QAClE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;YAChB,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,MAAM,gBAAgB,GAAG,KAAK,EAAE,OAA0B,EAAE,KAA8B,EAAmB,EAAE;IAC7G,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,kBAAkB,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAA8B,CAAC;YAC3C,IAAI,CAAC,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;gBAC1D,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;AAC3B,CAAC,CAAC;AAEF,QAAQ,CAAC,CAAC,iBAAiB,CAAC,KAAgB;IAC1C,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC;QACb,CAAC;IACH,CAAC;IAED,MAAM,CAAC,CAAC;AACV,CAAC;AAOM,KAAK,UAAU,OAAO,CAAC,OAAwB;IACpD,IAAI,KAA2B,CAAC;IAEhC,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,GAAG,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3E,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;YAC1B,WAAW,CAAC,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC;YACpC,WAAW,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QAChC,CAAC,EAAE,+BAA+B,CAAC,CAAC;QAEpC,gFAAgF;QAChF,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,aAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,IAAI,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,IAAI,aAAa,GAAG,MAAM,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC;YACxE,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;gBAClF,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;oBACf,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;gBACzB,CAAC;gBAED,aAAa,GAAG,MAAM,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YACzE,CAAC;YAED,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YACrC,OAAO,aAAa,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAA8B,CAAC;YAC3C,IAAI,CAAC,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,MAAM,CAAC,EAAE,CAAC;gBACrF,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/port/index.ts"],"names":[],"mappings":";;;;;AAoMA,0BAkDC;AAQD,4CAOC;AArQD;;;;;;;;;;;;;;;;;GAiBG;AACH,8CAAsB;AACtB,4CAAoB;AAEpB;;;;GAIG;AACH,MAAM,MAAO,SAAQ,KAAK;IACxB,YAAY,IAAY;QACtB,KAAK,CAAC,GAAG,IAAI,YAAY,CAAC,CAAC;IAC7B,CAAC;CACF;AAED,wDAAwD;AACxD,MAAM,WAAW,GAAG;IAClB,oDAAoD;IACpD,GAAG,EAAE,IAAI,GAAG,EAAU;IACtB,6BAA6B;IAC7B,KAAK,EAAE,IAAI,GAAG,EAAU;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,+BAA+B,GAAG,IAAI,GAAG,EAAE,CAAC;AAElD,iFAAiF;AACjF,IAAI,QAAoC,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,aAAa,GAAG,GAA4B,EAAE;IAClD,MAAM,UAAU,GAAG,YAAE,CAAC,iBAAiB,EAAE,CAAC;IAC1C,gDAAgD;IAChD,+EAA+E;IAC/E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAqB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;IAEpE,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,UAAU;YAAE,SAAS;QAC1B,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,kBAAkB,GAAG,CAAC,OAA0B,EAAmB,EAAE,CACzE,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IAC9B,MAAM,MAAM,GAAG,aAAG,CAAC,YAAY,EAAE,CAAC;IAClC,6BAA6B;IAC7B,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE3B,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE;QAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC;QAClE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;YAChB,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;GAUG;AACH,MAAM,gBAAgB,GAAG,KAAK,EAAE,OAA0B,EAAE,KAA8B,EAAmB,EAAE;IAC7G,gFAAgF;IAChF,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,oEAAoE;IACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,kBAAkB,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAA8B,CAAC;YAC3C,uGAAuG;YACvG,IAAI,CAAC,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;gBAC1D,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;AAC3B,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,QAAQ,CAAC,CAAC,iBAAiB,CAAC,KAAgB;IAC1C,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC;QACb,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,MAAM,CAAC,CAAC;AACV,CAAC;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACI,KAAK,UAAU,OAAO,CAAC,OAAwB;IACpD,IAAI,KAA2B,CAAC;IAEhC,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,GAAG,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3E,CAAC;IAED,yDAAyD;IACzD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;YAC1B,gEAAgE;YAChE,WAAW,CAAC,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC;YACpC,WAAW,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QAChC,CAAC,EAAE,+BAA+B,CAAC,CAAC;QAEpC,uGAAuG;QACvG,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,aAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,IAAI,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,IAAI,aAAa,GAAG,MAAM,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC;YACxE,oFAAoF;YACpF,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;gBAClF,wEAAwE;gBACxE,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;oBACf,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;gBACzB,CAAC;gBAED,uDAAuD;gBACvD,aAAa,GAAG,MAAM,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YACzE,CAAC;YAED,gDAAgD;YAChD,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YACrC,OAAO,aAAa,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAA8B,CAAC;YAC3C,sGAAsG;YACtG,IAAI,CAAC,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,MAAM,CAAC,EAAE,CAAC;gBACrF,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB;IAC9B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,aAAa,CAAC,QAAQ,CAAC,CAAC;QACxB,QAAQ,GAAG,SAAS,CAAC;IACvB,CAAC;IACD,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACxB,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC"}

package/dist/esm/utils/type_check.d.ts

@@ -1,9 +1,88 @@
+/**
+ * @module utils/type_check
+ * @description Runtime type checking utility. Provides a set of Type Guard functions
+ * for determining value types at runtime, used with TypeScript's type narrowing.
+ *
+ * Difference from utils/is.ts: is.ts detects Electron runtime environment (process type, OS),
+ * while this module detects JavaScript value types (functions, classes, objects, etc.).
+ */
+/**
+ * Determine if a value is a function
+ *
+ * Covers all callable types including regular functions, arrow functions, class constructors, and async functions.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a function type, TypeScript will also narrow val to function type
+ */
 export declare function isFunction(val: unknown): val is (...args: unknown[]) => unknown;
+/**
+ * Determine if a value is an ES6 class
+ *
+ * Primary check is structural: an ES6 class has a non-writable `prototype`
+ * (writable: false), whereas a regular function's prototype is writable, and
+ * arrow/async functions have no prototype at all. This reads the runtime object
+ * shape rather than source text, so it survives minify and bytecode (.jsc) compilation.
+ *
+ * Fallback check keeps the previous behavior: sniff the toString() output for a
+ * leading `class` keyword, covering any edge case the structural check misses.
+ * Note: constructor functions declared with function are not recognized as classes.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a class declared with class
+ */
 export declare function isClass(val: unknown): val is new (...args: unknown[]) => unknown;
+/**
+ * Determine if a value is a string
+ *
+ * @param val - Value to check
+ * @returns true if the value is of type string
+ */
 export declare function isString(val: unknown): val is string;
+/**
+ * Determine if a value is a plain object
+ *
+ * A plain object is one created via {} or new Object().
+ * Excludes null, arrays, and class instances.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a non-null, non-array ordinary object
+ */
 export declare function isObject(val: unknown): val is Record<string, unknown>;
+/**
+ * Determine if a value is an array
+ *
+ * @param val - Value to check
+ * @returns true if the value is an Array instance
+ */
 export declare function isArray(val: unknown): val is unknown[];
+/**
+ * Determine if a value is a primitive type
+ *
+ * Primitive types include: null, undefined, string, number, boolean, symbol, bigint.
+ * That is, values that are neither objects nor functions.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a primitive type
+ */
 export declare function isPrimitive(val: unknown): boolean;
+/**
+ * Determine if a value is a generator function (function*)
+ *
+ * Determines by checking if the function constructor's name is 'GeneratorFunction'.
+ * Generator functions are declared with function* and return Generator objects.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a generator function
+ */
 export declare function isGeneratorFunction(val: unknown): boolean;
+/**
+ * Determine if a value is an async function (async function)
+ *
+ * Determines by checking if the function constructor's name is 'AsyncFunction'.
+ * Async functions are declared with the async keyword and return Promises.
+ *
+ * @param val - Value to check
+ * @returns true if the value is an async function
+ */
 export declare function isAsyncFunction(val: unknown): boolean;
 //# sourceMappingURL=type_check.d.ts.map

package/dist/esm/utils/type_check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type_check.d.ts","sourceRoot":"","sources":["../../../src/utils/type_check.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAE/E;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAEhF;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAEpD;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,EAAE,CAEtD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEjD;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAErD"}
+{"version":3,"file":"type_check.d.ts","sourceRoot":"","sources":["../../../src/utils/type_check.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAE/E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAOhF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,EAAE,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAErD"}

package/dist/esm/utils/type_check.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * @module utils/type_check
+ * @description Runtime type checking utility. Provides a set of Type Guard functions
+ * for determining value types at runtime, used with TypeScript's type narrowing.
+ *
+ * Difference from utils/is.ts: is.ts detects Electron runtime environment (process type, OS),
+ * while this module detects JavaScript value types (functions, classes, objects, etc.).
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isFunction = isFunction;
 exports.isClass = isClass;
@@ -8,27 +16,105 @@ exports.isArray = isArray;
 exports.isPrimitive = isPrimitive;
 exports.isGeneratorFunction = isGeneratorFunction;
 exports.isAsyncFunction = isAsyncFunction;
+/**
+ * Determine if a value is a function
+ *
+ * Covers all callable types including regular functions, arrow functions, class constructors, and async functions.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a function type, TypeScript will also narrow val to function type
+ */
 function isFunction(val) {
     return typeof val === 'function';
 }
+/**
+ * Determine if a value is an ES6 class
+ *
+ * Primary check is structural: an ES6 class has a non-writable `prototype`
+ * (writable: false), whereas a regular function's prototype is writable, and
+ * arrow/async functions have no prototype at all. This reads the runtime object
+ * shape rather than source text, so it survives minify and bytecode (.jsc) compilation.
+ *
+ * Fallback check keeps the previous behavior: sniff the toString() output for a
+ * leading `class` keyword, covering any edge case the structural check misses.
+ * Note: constructor functions declared with function are not recognized as classes.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a class declared with class
+ */
 function isClass(val) {
-    return typeof val === 'function' && /^\s*class\b/.test(val.toString());
+    if (typeof val !== 'function')
+        return false;
+    // Primary: structural check (immune to minify / bytecode compilation)
+    const desc = Object.getOwnPropertyDescriptor(val, 'prototype');
+    if (desc && desc.writable === false)
+        return true;
+    // Fallback: source-string sniffing (preserves prior behavior)
+    return /^\s*class\b/.test(val.toString());
 }
+/**
+ * Determine if a value is a string
+ *
+ * @param val - Value to check
+ * @returns true if the value is of type string
+ */
 function isString(val) {
     return typeof val === 'string';
 }
+/**
+ * Determine if a value is a plain object
+ *
+ * A plain object is one created via {} or new Object().
+ * Excludes null, arrays, and class instances.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a non-null, non-array ordinary object
+ */
 function isObject(val) {
     return typeof val === 'object' && val !== null && !Array.isArray(val);
 }
+/**
+ * Determine if a value is an array
+ *
+ * @param val - Value to check
+ * @returns true if the value is an Array instance
+ */
 function isArray(val) {
     return Array.isArray(val);
 }
+/**
+ * Determine if a value is a primitive type
+ *
+ * Primitive types include: null, undefined, string, number, boolean, symbol, bigint.
+ * That is, values that are neither objects nor functions.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a primitive type
+ */
 function isPrimitive(val) {
     return val === null || (typeof val !== 'object' && typeof val !== 'function');
 }
+/**
+ * Determine if a value is a generator function (function*)
+ *
+ * Determines by checking if the function constructor's name is 'GeneratorFunction'.
+ * Generator functions are declared with function* and return Generator objects.
+ *
+ * @param val - Value to check
+ * @returns true if the value is a generator function
+ */
 function isGeneratorFunction(val) {
     return typeof val === 'function' && val.constructor?.name === 'GeneratorFunction';
 }
+/**
+ * Determine if a value is an async function (async function)
+ *
+ * Determines by checking if the function constructor's name is 'AsyncFunction'.
+ * Async functions are declared with the async keyword and return Promises.
+ *
+ * @param val - Value to check
+ * @returns true if the value is an async function
+ */
 function isAsyncFunction(val) {
     return typeof val === 'function' && val.constructor?.name === 'AsyncFunction';
 }

package/dist/esm/utils/type_check.js.map

@@ -1 +1 @@
-{"version":3,"file":"type_check.js","sourceRoot":"","sources":["../../../src/utils/type_check.ts"],"names":[],"mappings":";;AAAA,gCAEC;AAED,0BAEC;AAED,4BAEC;AAED,4BAEC;AAED,0BAEC;AAED,kCAEC;AAED,kDAEC;AAED,0CAEC;AA9BD,SAAgB,UAAU,CAAC,GAAY;IACrC,OAAO,OAAO,GAAG,KAAK,UAAU,CAAC;AACnC,CAAC;AAED,SAAgB,OAAO,CAAC,GAAY;IAClC,OAAO,OAAO,GAAG,KAAK,UAAU,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAY;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC;AACjC,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAY;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AACxE,CAAC;AAED,SAAgB,OAAO,CAAC,GAAY;IAClC,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAgB,WAAW,CAAC,GAAY;IACtC,OAAO,GAAG,KAAK,IAAI,IAAI,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC;AAChF,CAAC;AAED,SAAgB,mBAAmB,CAAC,GAAY;IAC9C,OAAO,OAAO,GAAG,KAAK,UAAU,IAAI,GAAG,CAAC,WAAW,EAAE,IAAI,KAAK,mBAAmB,CAAC;AACpF,CAAC;AAED,SAAgB,eAAe,CAAC,GAAY;IAC1C,OAAO,OAAO,GAAG,KAAK,UAAU,IAAI,GAAG,CAAC,WAAW,EAAE,IAAI,KAAK,eAAe,CAAC;AAChF,CAAC"}
+{"version":3,"file":"type_check.js","sourceRoot":"","sources":["../../../src/utils/type_check.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAUH,gCAEC;AAiBD,0BAOC;AAQD,4BAEC;AAWD,4BAEC;AAQD,0BAEC;AAWD,kCAEC;AAWD,kDAEC;AAWD,0CAEC;AA1GD;;;;;;;GAOG;AACH,SAAgB,UAAU,CAAC,GAAY;IACrC,OAAO,OAAO,GAAG,KAAK,UAAU,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,OAAO,CAAC,GAAY;IAClC,IAAI,OAAO,GAAG,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC5C,sEAAsE;IACtE,MAAM,IAAI,GAAG,MAAM,CAAC,wBAAwB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC/D,IAAI,IAAI,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACjD,8DAA8D;IAC9D,OAAO,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,QAAQ,CAAC,GAAY;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,QAAQ,CAAC,GAAY;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,OAAO,CAAC,GAAY;IAClC,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,WAAW,CAAC,GAAY;IACtC,OAAO,GAAG,KAAK,IAAI,IAAI,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAAC,GAAY;IAC9C,OAAO,OAAO,GAAG,KAAK,UAAU,IAAI,GAAG,CAAC,WAAW,EAAE,IAAI,KAAK,mBAAmB,CAAC;AACpF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAAC,GAAY;IAC1C,OAAO,OAAO,GAAG,KAAK,UAAU,IAAI,GAAG,CAAC,WAAW,EAAE,IAAI,KAAK,eAAe,CAAC;AAChF,CAAC"}

package/dist/esm/utils/wrap.d.ts

@@ -1,5 +1,31 @@
+/**
+ * Convert file path to property path array
+ *
+ * Determines property name naming style based on caseStyle configuration.
+ * Supports preset styles (lower/upper/camel) and fully custom conversion functions.
+ *
+ * @param filepath - Relative file path (e.g. 'a/b/c.js')
+ * @param options - Conversion options
+ * @param options.caseStyle - Naming style: 'lower' (first letter lowercase), 'upper' (first letter uppercase),
+ *   'camel' (camelCase, default) or custom conversion function
+ * @returns Property path array (e.g. ['a', 'b', 'c'])
+ * @throws Error - Throws when caseStyle is a function but return value is not an array
+ */
 export declare function getProperties(filepath: string, { caseStyle }: {
     caseStyle: string | ((filepath: string) => string[]);
 }): string[];
+/**
+ * Default camelCase conversion implementation
+ *
+ * Processing flow:
+ * 1. Remove file extension, split by '/' into path segments
+ * 2. For each path segment: capitalize letters after underscores/hyphens (e.g. foo_bar -> fooBar)
+ * 3. Adjust first letter case based on caseStyle
+ *
+ * @param filepath - Relative file path
+ * @param caseStyle - Naming style
+ * @returns Property path array
+ * @throws Error - Throws when path segment contains illegal characters (not a-z0-9_-)
+ */
 export declare function defaultCamelize(filepath: string, caseStyle: string): string[];
 //# sourceMappingURL=wrap.d.ts.map

package/dist/esm/utils/wrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../../src/utils/wrap.ts"],"names":[],"mappings":"AAIA,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,EAAE;IAAE,SAAS,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC,CAAA;CAAE,GAAG,MAAM,EAAE,CAWjI;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CA+B7E"}
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../../src/utils/wrap.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,EAAE;IAAE,SAAS,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC,CAAA;CAAE,GAAG,MAAM,EAAE,CAWjI;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAgC7E"}

package/dist/esm/utils/wrap.js

@@ -2,11 +2,34 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getProperties = getProperties;
 exports.defaultCamelize = defaultCamelize;
+/**
+ * @module utils/wrap
+ * @description File path to property path conversion utility. Converts directory/file paths
+ * to nested property name arrays for use by FileLoader to build nested object structures.
+ *
+ * Conversion examples:
+ * ```
+ * 'a/b/c.js' -> ['a', 'b', 'c']
+ * 'user_info.js' -> ['userInfo'] (caseStyle='camel')
+ * 'UserInfo.js' -> ['userInfo'] (caseStyle='lower')
+ * ```
+ */
 const type_check_js_1 = require("./type_check.js");
-// convert file path to an array of properties
-// a/b/c.js => ['a', 'b', 'c']
+/**
+ * Convert file path to property path array
+ *
+ * Determines property name naming style based on caseStyle configuration.
+ * Supports preset styles (lower/upper/camel) and fully custom conversion functions.
+ *
+ * @param filepath - Relative file path (e.g. 'a/b/c.js')
+ * @param options - Conversion options
+ * @param options.caseStyle - Naming style: 'lower' (first letter lowercase), 'upper' (first letter uppercase),
+ *   'camel' (camelCase, default) or custom conversion function
+ * @returns Property path array (e.g. ['a', 'b', 'c'])
+ * @throws Error - Throws when caseStyle is a function but return value is not an array
+ */
 function getProperties(filepath, { caseStyle }) {
-    // if caseStyle is function, return the result of function
+    // When caseStyle is a function, delegate entirely to the caller's custom conversion logic
     if ((0, type_check_js_1.isFunction)(caseStyle)) {
         const result = caseStyle(filepath);
         if (!Array.isArray(result)) {
@@ -14,35 +37,49 @@ function getProperties(filepath, { caseStyle }) {
         }
         return result;
     }
-    // use default camelize
+    // Use built-in camelCase conversion rules
     return defaultCamelize(filepath, caseStyle);
 }
+/**
+ * Default camelCase conversion implementation
+ *
+ * Processing flow:
+ * 1. Remove file extension, split by '/' into path segments
+ * 2. For each path segment: capitalize letters after underscores/hyphens (e.g. foo_bar -> fooBar)
+ * 3. Adjust first letter case based on caseStyle
+ *
+ * @param filepath - Relative file path
+ * @param caseStyle - Naming style
+ * @returns Property path array
+ * @throws Error - Throws when path segment contains illegal characters (not a-z0-9_-)
+ */
 function defaultCamelize(filepath, caseStyle) {
+    // Remove extension, split by path separator
     const properties = filepath.substring(0, filepath.lastIndexOf('.')).split('/');
     return properties.map((property) => {
+        // Validate path segment only contains legal characters
         if (!/^[a-z][a-z0-9_-]*$/i.test(property)) {
             throw new Error(`${property} is not match 'a-z0-9_-' in ${filepath}`);
         }
-        // use default camelize, will capitalize the first letter
-        // foo_bar.js > FooBar
-        // fooBar.js  > FooBar
-        // FooBar.js  > FooBar
-        // FooBar.js  > FooBar
-        // FooBar.js  > fooBar
+        // Underscore/hyphen to camelCase: foo_bar -> fooBar, foo-bar -> fooBar
         const normalized = property.replace(/[_-][a-z]/gi, (s) => s.substring(1).toUpperCase());
         const first = normalized[0];
         if (!first)
             return normalized;
+        // Adjust first letter based on caseStyle
         let firstChar = first;
         switch (caseStyle) {
             case 'lower':
+                // First letter lowercase: FooBar -> fooBar (controllers use this style)
                 firstChar = first.toLowerCase();
                 break;
             case 'upper':
+                // First letter uppercase: fooBar -> FooBar
                 firstChar = first.toUpperCase();
                 break;
             case 'camel':
             default:
+                // Keep as-is (camelCase)
                 break;
         }
         return firstChar + normalized.substring(1);

package/dist/esm/utils/wrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"wrap.js","sourceRoot":"","sources":["../../../src/utils/wrap.ts"],"names":[],"mappings":";;AAIA,sCAWC;AAED,0CA+BC;AAhDD,mDAA6C;AAE7C,8CAA8C;AAC9C,8BAA8B;AAC9B,SAAgB,aAAa,CAAC,QAAgB,EAAE,EAAE,SAAS,EAA4D;IACrH,0DAA0D;IAC1D,IAAI,IAAA,0BAAU,EAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAI,SAA4C,CAAC,QAAQ,CAAC,CAAC;QACvE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,sCAAsC,MAAM,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,uBAAuB;IACvB,OAAO,eAAe,CAAC,QAAQ,EAAE,SAAmB,CAAC,CAAC;AACxD,CAAC;AAED,SAAgB,eAAe,CAAC,QAAgB,EAAE,SAAiB;IACjE,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/E,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QACjC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,+BAA+B,QAAQ,EAAE,CAAC,CAAC;QACxE,CAAC;QAED,yDAAyD;QACzD,sBAAsB;QACtB,sBAAsB;QACtB,sBAAsB;QACtB,sBAAsB;QACtB,sBAAsB;QACtB,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACxF,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK;YAAE,OAAO,UAAU,CAAC;QAE9B,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,OAAO;gBACV,SAAS,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;gBAChC,MAAM;YACR,KAAK,OAAO;gBACV,SAAS,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;gBAChC,MAAM;YACR,KAAK,OAAO,CAAC;YACb;gBACE,MAAM;QACV,CAAC;QACD,OAAO,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"wrap.js","sourceRoot":"","sources":["../../../src/utils/wrap.ts"],"names":[],"mappings":";;AA2BA,sCAWC;AAeD,0CAgCC;AArFD;;;;;;;;;;;GAWG;AACH,mDAA6C;AAE7C;;;;;;;;;;;;GAYG;AACH,SAAgB,aAAa,CAAC,QAAgB,EAAE,EAAE,SAAS,EAA4D;IACrH,0FAA0F;IAC1F,IAAI,IAAA,0BAAU,EAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAI,SAA4C,CAAC,QAAQ,CAAC,CAAC;QACvE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,sCAAsC,MAAM,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,0CAA0C;IAC1C,OAAO,eAAe,CAAC,QAAQ,EAAE,SAAmB,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,eAAe,CAAC,QAAgB,EAAE,SAAiB;IACjE,4CAA4C;IAC5C,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/E,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QACjC,uDAAuD;QACvD,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,QAAQ,+BAA+B,QAAQ,EAAE,CAAC,CAAC;QACxE,CAAC;QAED,uEAAuE;QACvE,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QACxF,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK;YAAE,OAAO,UAAU,CAAC;QAE9B,yCAAyC;QACzC,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,OAAO;gBACV,wEAAwE;gBACxE,SAAS,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;gBAChC,MAAM;YACR,KAAK,OAAO;gBACV,2CAA2C;gBAC3C,SAAS,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;gBAChC,MAAM;YACR,KAAK,OAAO,CAAC;YACb;gBACE,yBAAyB;gBACzB,MAAM;QACV,CAAC;QACD,OAAO,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC"}