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

package/dist/cjs/utils/ip.js

@@ -5,15 +5,38 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.publicIpv4 = publicIpv4;
 exports.publicIpv6 = publicIpv6;
+/**
+ * @module utils/ip
+ * @description Public IP address query utility. Obtains the machine's public IPv4/IPv6 address
+ * via DNS resolution or HTTPS requests.
+ *
+ * Supports three query methods:
+ * - DNS query: resolves via OpenDNS special domain myip.opendns.com
+ * - HTTPS query: obtains via third-party IP query services (icanhazip, ipify)
+ * - Combined query (all): tries DNS first, falls back to HTTPS on failure
+ *
+ * All query methods return Promises with an attached cancel() method, allowing cancellation at any time.
+ */
 const dgram_1 = __importDefault(require("dgram"));
 const net_1 = require("net");
 const dns_socket_1 = __importDefault(require("dns-socket"));
 const urllib_1 = require("urllib");
+/** Empty string constant, indicates query failure with no result */
 const emptyIP = '';
+/** Default query options */
 const defaults = {
+    /** Query timeout (ms) */
     timeout: 3000,
+    /** Query method: 'http' uses HTTPS interface, 'dns' uses DNS resolution, 'all' tries DNS then HTTPS */
     type: 'http',
 };
+/**
+ * Pre-configured DNS server list
+ *
+ * Uses OpenDNS public DNS servers, obtains the machine's public IP by querying
+ * the A/AAAA records of myip.opendns.com. OpenDNS returns the querier's IP
+ * address as the response.
+ */
 const dnsServers = [
     {
         v4: {
@@ -36,6 +59,12 @@ const dnsServers = [
         },
     },
 ];
+/**
+ * Query configuration organized by protocol version
+ *
+ * IPv4 and IPv6 each use different DNS record types (A/AAAA)
+ * and different HTTPS query endpoints.
+ */
 const ipType = {
     v4: {
         dnsServers: dnsServers.map(({ v4: { servers, ...question } }) => ({
@@ -58,11 +87,22 @@ const ipType = {
         ],
     },
 };
+/**
+ * Query public IP via DNS
+ *
+ * Sends a special domain query to OpenDNS servers; OpenDNS returns the querier's
+ * IP address as the DNS response. Tries servers in the list sequentially until success.
+ *
+ * @param version - IP version, 'v4' or 'v6'
+ * @param options - Query options
+ * @returns Promise of IP address string, with cancel() method to cancel the query
+ */
 function queryDns(version, options) {
     const data = ipType[version];
     const socket = (0, dns_socket_1.default)({
         retries: 0,
         maxQueries: 1,
+        // IPv6 uses udp6 Socket, IPv4 uses udp4 Socket
         socket: dgram_1.default.createSocket(version === 'v6' ? 'udp6' : 'udp4'),
         timeout: options.timeout,
     });
@@ -70,6 +110,7 @@ function queryDns(version, options) {
         for (const dnsServerInfo of data.dnsServers) {
             const { servers, question } = dnsServerInfo;
             for (const server of servers) {
+                // If socket has been cancelled, return empty immediately
                 if (socket.destroyed) {
                     return emptyIP;
                 }
@@ -81,6 +122,7 @@ function queryDns(version, options) {
                         continue;
                     const response = (typeof answer.data === 'string' ? answer.data : answer.data.toString()).trim();
                     const ip = response;
+                    // Validate the returned IP format
                     const method = version === 'v6' ? net_1.isIPv6 : net_1.isIPv4;
                     if (ip && method(ip)) {
                         socket.destroy();
@@ -88,18 +130,29 @@ function queryDns(version, options) {
                     }
                 }
                 catch {
-                    // ignore
+                    // Single server query failure does not affect subsequent attempts
                 }
             }
         }
         socket.destroy();
         return emptyIP;
     })();
+    // Provide cancel method, allowing external cancellation of ongoing DNS queries
     promise.cancel = () => {
         socket.destroy();
     };
     return promise;
 }
+/**
+ * Query public IP via HTTPS interface
+ *
+ * Sends HTTP GET requests to third-party IP query services; the response body is the public IP address.
+ * Tries URLs in the list sequentially until success.
+ *
+ * @param version - IP version, 'v4' or 'v6'
+ * @param options - Query options
+ * @returns Promise of IP address string, with cancel() method
+ */
 function queryHttps(version, options) {
     let cancelFn;
     const promise = (async () => {
@@ -108,6 +161,7 @@ function queryHttps(version, options) {
             timeout: options.timeout,
             dataType: 'text',
         };
+        // Combine default URLs with user-provided fallback URLs
         const urls = [
             ...ipType[version].httpsUrls,
             ...(options.fallbackUrls ?? []),
@@ -117,13 +171,14 @@ function queryHttps(version, options) {
                 const response = await (0, urllib_1.request)(url, requestOptions);
                 const result = response.res.status === 200 ? response.data.toString() : '';
                 const ip = result.trim();
+                // Validate the returned IP format
                 const method = version === 'v6' ? net_1.isIPv6 : net_1.isIPv4;
                 if (ip && method(ip)) {
                     return ip;
                 }
             }
             catch {
-                // ignore
+                // Single URL request failure does not affect subsequent attempts
             }
         }
         return emptyIP;
@@ -133,16 +188,28 @@ function queryHttps(version, options) {
     };
     return promise;
 }
+/**
+ * Combined query for public IP (DNS first, then HTTPS)
+ *
+ * Tries DNS query first; when DNS fails, automatically falls back to HTTPS query,
+ * ensuring the public IP can still be obtained in restricted network environments.
+ *
+ * @param version - IP version, 'v4' or 'v6'
+ * @param options - Query options
+ * @returns Promise of IP address string, with cancel() method
+ */
 function queryAll(version, options) {
     let cancelFn;
     const promise = (async () => {
         let response;
+        // Try DNS query first
         const dnsPromise = queryDns(version, options);
         cancelFn = dnsPromise.cancel ?? (() => { });
         try {
             response = await dnsPromise;
         }
         catch {
+            // DNS query failed, fall back to HTTPS
             const httpsPromise = queryHttps(version, options);
             cancelFn = httpsPromise.cancel ?? (() => { });
             response = await httpsPromise;
@@ -154,7 +221,20 @@ function queryAll(version, options) {
     };
     return promise;
 }
-// 查询 public ipv4
+/**
+ * Query public IPv4 address
+ *
+ * @param options - Query options (type, timeout, fallbackUrls)
+ * @returns Promise of IPv4 address string, with cancel() method to cancel the query
+ *
+ * @example
+ * ```ts
+ * const p = publicIpv4({ type: 'http', timeout: 5000 });
+ * const ip = await p;
+ * // Or cancel the query
+ * p.cancel();
+ * ```
+ */
 function publicIpv4(options) {
     const merged = {
         ...defaults,
@@ -166,9 +246,20 @@ function publicIpv4(options) {
     if (merged.type === 'dns') {
         return queryDns('v4', merged);
     }
+    // type === 'all': DNS first, then HTTPS
     return queryAll('v4', merged);
 }
-// 查询 public ipv6
+/**
+ * Query public IPv6 address
+ *
+ * @param options - Query options (type, timeout, fallbackUrls)
+ * @returns Promise of IPv6 address string, with cancel() method to cancel the query
+ *
+ * @example
+ * ```ts
+ * const ip = await publicIpv6({ type: 'dns' });
+ * ```
+ */
 function publicIpv6(options) {
     const merged = {
         ...defaults,

package/dist/cjs/utils/ip.js.map

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

package/dist/cjs/utils/is.d.ts

@@ -1,15 +1,138 @@
+/**
+ * @module utils/is
+ * @description Electron runtime environment detection utility. Provides a set of functions
+ * for determining the current process type, operating system platform, and processor
+ * architecture, enabling framework code to execute different logic for different environments.
+ *
+ * Usage:
+ * ```ts
+ * import { main, osx, all } from './is.js';
+ * if (all(main, osx)) { /* main process + macOS *\/ }
+ * ```
+ */
+/**
+ * Detect whether currently running in the renderer process
+ *
+ * Electron process.type values:
+ * - 'renderer': renderer process
+ * - 'browser': main process
+ * - 'worker': Worker process
+ *
+ * @returns true if currently in the renderer process
+ */
 export declare function renderer(): boolean;
+/**
+ * Detect whether currently running in the main process
+ *
+ * The main process's process.type is 'browser' in Electron.
+ *
+ * @returns true if currently in the main process
+ */
 export declare function main(): boolean;
+/**
+ * Detect whether the current operating system is macOS
+ *
+ * Based on process.platform === 'darwin'.
+ * macOS, iOS, and other Apple systems all have platform 'darwin'.
+ *
+ * @returns true if currently running on macOS
+ */
 export declare function osx(): boolean;
+/**
+ * Detect whether the current operating system is macOS (alias for osx)
+ *
+ * @returns true if currently running on macOS
+ */
 export declare function macOS(): boolean;
+/**
+ * Detect whether the current operating system is Windows
+ *
+ * Based on process.platform === 'win32'.
+ * Note: 64-bit Windows also has platform 'win32'.
+ *
+ * @returns true if currently running on Windows
+ */
 export declare function windows(): boolean;
+/**
+ * Detect whether the current operating system is Linux
+ *
+ * @returns true if currently running on Linux
+ */
 export declare function linux(): boolean;
+/**
+ * Detect whether the current operating system is OpenHarmony
+ *
+ * @returns true if currently running on OpenHarmony
+ */
+export declare function openharmony(): boolean;
+/**
+ * Detect whether the processor architecture is x86 (32-bit)
+ *
+ * Based on process.arch === 'ia32'.
+ *
+ * @returns true for 32-bit x86 architecture
+ */
 export declare function x86(): boolean;
+/**
+ * Detect whether the processor architecture is x64 (64-bit)
+ *
+ * Based on process.arch === 'x64'.
+ *
+ * @returns true for 64-bit x86 architecture
+ */
 export declare function x64(): boolean;
+/**
+ * Detect whether the app is running in a macOS sandbox environment
+ *
+ * macOS sandbox apps contain APP_SANDBOX_CONTAINER_ID in environment variables.
+ *
+ * @returns true if running in a sandbox environment
+ */
 export declare function sandbox(): boolean;
+/**
+ * Detect whether the app is a Mac App Store build
+ *
+ * Electron's process.mas property is true in MAS builds.
+ *
+ * @returns true for MAS build
+ */
 export declare function mas(): boolean;
+/**
+ * Detect whether the app is a Windows Store (appx) build
+ *
+ * Electron's process.windowsStore property is true in Windows Store builds.
+ *
+ * @returns true for Windows Store build
+ */
 export declare function windowsStore(): boolean;
+/**
+ * Determine if all condition functions are true
+ *
+ * Accepts multiple functions returning boolean values, executes each and checks the result.
+ * Returns false at the first false result; returns true only if all are true.
+ *
+ * @param isFunctions - List of condition functions
+ * @returns true if all are true, false if any is false, undefined if no arguments
+ */
 export declare function all(...isFunctions: Array<() => boolean>): boolean | undefined;
+/**
+ * Determine if all condition functions are false
+ *
+ * Accepts multiple functions returning boolean values, executes each and checks the result.
+ * Returns false at the first true result; returns true only if all are false.
+ *
+ * @param isFunctions - List of condition functions
+ * @returns true if all are false, false if any is true, undefined if no arguments
+ */
 export declare function none(...isFunctions: Array<() => boolean>): boolean | undefined;
+/**
+ * Determine if at least one condition function is true
+ *
+ * Accepts multiple functions returning boolean values, executes each and checks the result.
+ * Returns true at the first true result; returns false only if all are false.
+ *
+ * @param isFunctions - List of condition functions
+ * @returns true if any is true, false if all are false, undefined if no arguments
+ */
 export declare function one(...isFunctions: Array<() => boolean>): boolean | undefined;
 //# sourceMappingURL=is.d.ts.map

package/dist/cjs/utils/is.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is.d.ts","sourceRoot":"","sources":["../../../src/utils/is.ts"],"names":[],"mappings":"AACA,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAGD,wBAAgB,IAAI,IAAI,OAAO,CAE9B;AAGD,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAGD,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAGD,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAGD,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAGD,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAGD,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAGD,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAGD,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAGD,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAGD,wBAAgB,GAAG,CAAC,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS,CAM7E;AAGD,wBAAgB,IAAI,CAAC,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS,CAM9E;AAGD,wBAAgB,GAAG,CAAC,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS,CAM7E"}
+{"version":3,"file":"is.d.ts","sourceRoot":"","sources":["../../../src/utils/is.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAE9B;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAED;;;;GAIG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED;;;;GAIG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,IAAI,OAAO,CAE7B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS,CAM7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS,CAM9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS,CAM7E"}

package/dist/cjs/utils/is.js

@@ -6,6 +6,7 @@ exports.osx = osx;
 exports.macOS = macOS;
 exports.windows = windows;
 exports.linux = linux;
+exports.openharmony = openharmony;
 exports.x86 = x86;
 exports.x64 = x64;
 exports.sandbox = sandbox;
@@ -14,51 +15,146 @@ exports.windowsStore = windowsStore;
 exports.all = all;
 exports.none = none;
 exports.one = one;
-// Checks if we are in renderer process
+/**
+ * @module utils/is
+ * @description Electron runtime environment detection utility. Provides a set of functions
+ * for determining the current process type, operating system platform, and processor
+ * architecture, enabling framework code to execute different logic for different environments.
+ *
+ * Usage:
+ * ```ts
+ * import { main, osx, all } from './is.js';
+ * if (all(main, osx)) { /* main process + macOS *\/ }
+ * ```
+ */
+/**
+ * Detect whether currently running in the renderer process
+ *
+ * Electron process.type values:
+ * - 'renderer': renderer process
+ * - 'browser': main process
+ * - 'worker': Worker process
+ *
+ * @returns true if currently in the renderer process
+ */
 function renderer() {
     return process.type === 'renderer';
 }
-// Checks if we are in main process
+/**
+ * Detect whether currently running in the main process
+ *
+ * The main process's process.type is 'browser' in Electron.
+ *
+ * @returns true if currently in the main process
+ */
 function main() {
     return process.type === 'browser';
 }
-// Checks if we are under Mac OS
+/**
+ * Detect whether the current operating system is macOS
+ *
+ * Based on process.platform === 'darwin'.
+ * macOS, iOS, and other Apple systems all have platform 'darwin'.
+ *
+ * @returns true if currently running on macOS
+ */
 function osx() {
     return process.platform === 'darwin';
 }
-// Checks if we are under Mac OS
+/**
+ * Detect whether the current operating system is macOS (alias for osx)
+ *
+ * @returns true if currently running on macOS
+ */
 function macOS() {
     return osx();
 }
-// Checks if we are under Windows OS
+/**
+ * Detect whether the current operating system is Windows
+ *
+ * Based on process.platform === 'win32'.
+ * Note: 64-bit Windows also has platform 'win32'.
+ *
+ * @returns true if currently running on Windows
+ */
 function windows() {
     return process.platform === 'win32';
 }
-// Checks if we are under Linux OS
+/**
+ * Detect whether the current operating system is Linux
+ *
+ * @returns true if currently running on Linux
+ */
 function linux() {
     return process.platform === 'linux';
 }
-// Checks if we are the processor's arch is x86
+/**
+ * Detect whether the current operating system is OpenHarmony
+ *
+ * @returns true if currently running on OpenHarmony
+ */
+function openharmony() {
+    return process.platform === 'openharmony';
+}
+/**
+ * Detect whether the processor architecture is x86 (32-bit)
+ *
+ * Based on process.arch === 'ia32'.
+ *
+ * @returns true for 32-bit x86 architecture
+ */
 function x86() {
     return process.arch === 'ia32';
 }
-// Checks if we are the processor's arch is x64
+/**
+ * Detect whether the processor architecture is x64 (64-bit)
+ *
+ * Based on process.arch === 'x64'.
+ *
+ * @returns true for 64-bit x86 architecture
+ */
 function x64() {
     return process.arch === 'x64';
 }
-// Checks if the app is running in a sandbox on macOS
+/**
+ * Detect whether the app is running in a macOS sandbox environment
+ *
+ * macOS sandbox apps contain APP_SANDBOX_CONTAINER_ID in environment variables.
+ *
+ * @returns true if running in a sandbox environment
+ */
 function sandbox() {
     return 'APP_SANDBOX_CONTAINER_ID' in process.env;
 }
-// Checks if the app is running as a Mac App Store build
+/**
+ * Detect whether the app is a Mac App Store build
+ *
+ * Electron's process.mas property is true in MAS builds.
+ *
+ * @returns true for MAS build
+ */
 function mas() {
     return process.mas === true;
 }
-// Checks if the app is running as a Windows Store (appx) build
+/**
+ * Detect whether the app is a Windows Store (appx) build
+ *
+ * Electron's process.windowsStore property is true in Windows Store builds.
+ *
+ * @returns true for Windows Store build
+ */
 function windowsStore() {
     return process.windowsStore === true;
 }
-// checks if all the 'is functions' passed as arguments are true
+/**
+ * Determine if all condition functions are true
+ *
+ * Accepts multiple functions returning boolean values, executes each and checks the result.
+ * Returns false at the first false result; returns true only if all are true.
+ *
+ * @param isFunctions - List of condition functions
+ * @returns true if all are true, false if any is false, undefined if no arguments
+ */
 function all(...isFunctions) {
     if (!isFunctions.length)
         return undefined;
@@ -68,7 +164,15 @@ function all(...isFunctions) {
     }
     return true;
 }
-// checks if all the 'is functions' passed as arguments are false
+/**
+ * Determine if all condition functions are false
+ *
+ * Accepts multiple functions returning boolean values, executes each and checks the result.
+ * Returns false at the first true result; returns true only if all are false.
+ *
+ * @param isFunctions - List of condition functions
+ * @returns true if all are false, false if any is true, undefined if no arguments
+ */
 function none(...isFunctions) {
     if (!isFunctions.length)
         return undefined;
@@ -78,7 +182,15 @@ function none(...isFunctions) {
     }
     return true;
 }
-// returns true if one of the 'is functions' passed as argument is true
+/**
+ * Determine if at least one condition function is true
+ *
+ * Accepts multiple functions returning boolean values, executes each and checks the result.
+ * Returns true at the first true result; returns false only if all are false.
+ *
+ * @param isFunctions - List of condition functions
+ * @returns true if any is true, false if all are false, undefined if no arguments
+ */
 function one(...isFunctions) {
     if (!isFunctions.length)
         return undefined;

package/dist/cjs/utils/is.js.map

@@ -1 +1 @@
-{"version":3,"file":"is.js","sourceRoot":"","sources":["../../../src/utils/is.ts"],"names":[],"mappings":";;AACA,4BAEC;AAGD,oBAEC;AAGD,kBAEC;AAGD,sBAEC;AAGD,0BAEC;AAGD,sBAEC;AAGD,kBAEC;AAGD,kBAEC;AAGD,0BAEC;AAGD,kBAEC;AAGD,oCAEC;AAGD,kBAMC;AAGD,oBAMC;AAGD,kBAMC;AAhFD,uCAAuC;AACvC,SAAgB,QAAQ;IACtB,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU,CAAC;AACrC,CAAC;AAED,mCAAmC;AACnC,SAAgB,IAAI;IAClB,OAAO,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC;AACpC,CAAC;AAED,gCAAgC;AAChC,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACvC,CAAC;AAED,gCAAgC;AAChC,SAAgB,KAAK;IACnB,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED,oCAAoC;AACpC,SAAgB,OAAO;IACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AACtC,CAAC;AAED,kCAAkC;AAClC,SAAgB,KAAK;IACnB,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AACtC,CAAC;AAED,+CAA+C;AAC/C,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC;AACjC,CAAC;AAED,+CAA+C;AAC/C,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC;AAChC,CAAC;AAED,qDAAqD;AACrD,SAAgB,OAAO;IACrB,OAAO,0BAA0B,IAAI,OAAO,CAAC,GAAG,CAAC;AACnD,CAAC;AAED,wDAAwD;AACxD,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED,+DAA+D;AAC/D,SAAgB,YAAY;IAC1B,OAAO,OAAO,CAAC,YAAY,KAAK,IAAI,CAAC;AACvC,CAAC;AAED,gEAAgE;AAChE,SAAgB,GAAG,CAAC,GAAG,WAAiC;IACtD,IAAI,CAAC,WAAW,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7B,IAAI,CAAC,EAAE,EAAE;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,iEAAiE;AACjE,SAAgB,IAAI,CAAC,GAAG,WAAiC;IACvD,IAAI,CAAC,WAAW,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7B,IAAI,EAAE,EAAE;YAAE,OAAO,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uEAAuE;AACvE,SAAgB,GAAG,CAAC,GAAG,WAAiC;IACtD,IAAI,CAAC,WAAW,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7B,IAAI,EAAE,EAAE;YAAE,OAAO,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"is.js","sourceRoot":"","sources":["../../../src/utils/is.ts"],"names":[],"mappings":";;AAsBA,4BAEC;AASD,oBAEC;AAUD,kBAEC;AAOD,sBAEC;AAUD,0BAEC;AAOD,sBAEC;AAOD,kCAEC;AASD,kBAEC;AASD,kBAEC;AASD,0BAEC;AASD,kBAEC;AASD,oCAEC;AAWD,kBAMC;AAWD,oBAMC;AAWD,kBAMC;AAhMD;;;;;;;;;;;GAWG;AACH;;;;;;;;;GASG;AACH,SAAgB,QAAQ;IACtB,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,IAAI;IAClB,OAAO,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,SAAgB,KAAK;IACnB,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,OAAO;IACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,SAAgB,KAAK;IACnB,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW;IACzB,OAAQ,OAAO,CAAC,QAAmB,KAAK,aAAa,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,OAAO;IACrB,OAAO,0BAA0B,IAAI,OAAO,CAAC,GAAG,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,GAAG;IACjB,OAAO,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY;IAC1B,OAAO,OAAO,CAAC,YAAY,KAAK,IAAI,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,GAAG,CAAC,GAAG,WAAiC;IACtD,IAAI,CAAC,WAAW,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7B,IAAI,CAAC,EAAE,EAAE;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,IAAI,CAAC,GAAG,WAAiC;IACvD,IAAI,CAAC,WAAW,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7B,IAAI,EAAE,EAAE;YAAE,OAAO,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,GAAG,CAAC,GAAG,WAAiC;IACtD,IAAI,CAAC,WAAW,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7B,IAAI,EAAE,EAAE;YAAE,OAAO,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/cjs/utils/json.d.ts

@@ -1,10 +1,64 @@
+/** JSON write options */
 export interface JsonWriteOptions {
+    /** Number of indent spaces, default 2 */
     space?: number;
+    /** JSON.stringify replacer function for custom serialization logic */
     replacer?: (key: string, value: unknown) => unknown;
 }
+/**
+ * Strictly parse a JSON string
+ *
+ * Unlike JSON.parse, additionally validates that the parsed result must be an object type,
+ * preventing primitive type values (such as strings, numbers) from being parsed.
+ *
+ * @param str - JSON string
+ * @returns Parsed object
+ * @throws Error - Throws when parse result is not an object
+ */
 export declare function strictParse(str: string): unknown;
+/**
+ * Synchronously read a JSON file
+ *
+ * Reads file content and parses it as an object; throws if file does not exist.
+ *
+ * @param filepath - JSON file path
+ * @returns Parsed object
+ * @throws Error - Throws when file does not exist
+ */
 export declare function readSync(filepath: string): unknown;
+/**
+ * Synchronously write a JSON file
+ *
+ * Automatically creates the target directory, objects are automatically serialized to JSON string,
+ * non-object values are converted to string for writing. Default uses 2-space indentation.
+ *
+ * @param filepath - Target file path
+ * @param str - Content to write, objects will be serialized by JSON.stringify
+ * @param options - Write options (indentation, replacer)
+ */
 export declare function writeSync(filepath: string, str: unknown, options?: JsonWriteOptions): void;
+/**
+ * Asynchronously read a JSON file
+ *
+ * First checks if the file exists and is a regular file, then reads and parses it.
+ * Uses fs.promises async API, does not block the event loop.
+ *
+ * @param filepath - JSON file path
+ * @returns Promise of the parsed object
+ * @throws Error - Throws when file does not exist or is not a file
+ */
 export declare function read(filepath: string): Promise<unknown>;
+/**
+ * Asynchronously write a JSON file
+ *
+ * Automatically creates the target directory, objects are automatically serialized to JSON string,
+ * non-object values are converted to string for writing. Default uses 2-space indentation.
+ * Uses fs.promises async API, does not block the event loop.
+ *
+ * @param filepath - Target file path
+ * @param str - Content to write, objects will be serialized by JSON.stringify
+ * @param options - Write options (indentation, replacer)
+ * @returns Promise that resolves when writing is complete
+ */
 export declare function write(filepath: string, str: unknown, options?: JsonWriteOptions): Promise<void>;
 //# sourceMappingURL=json.d.ts.map

package/dist/cjs/utils/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/utils/json.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACrD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMhD;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAY9F;AAED,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUvD;AAED,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnG"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/utils/json.ts"],"names":[],"mappings":"AASA,yBAAyB;AACzB,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAc9F;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAWvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYnG"}