@yarn-tool/env-path 2.0.14 → 2.0.16

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.0.16](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/env-path@2.0.15...@yarn-tool/env-path@2.0.16) (2026-10-12)
+
+
+
+### 📚　Documentation
+
+* add jsdoc ([9cb9b13](https://github.com/bluelovers/ws-yarn-workspaces/commit/9cb9b13eda8c357221ad1b754458aa9916eada22))
+
+
+### 🛠　Build System
+
+* update build ([3186340](https://github.com/bluelovers/ws-yarn-workspaces/commit/3186340758172427cb1e9b8955f6fd677abac625))
+* **deps:** 更新測試腳本與依賴以支援 node:test ([f9c71c7](https://github.com/bluelovers/ws-yarn-workspaces/commit/f9c71c795c792c5c7ed9d613ce7e9c3c726c39d5))
+
+
+### ♻️　Chores
+
+* **workspace:** 更新測試指令路徑與新增工作區搜尋選項 ([a80039d](https://github.com/bluelovers/ws-yarn-workspaces/commit/a80039dd8c691e047466966ffc8f8a4e2e31c03f))
+
+
+### 🔖　Miscellaneous
+
+* . ([e5788f8](https://github.com/bluelovers/ws-yarn-workspaces/commit/e5788f84551b870490a96d0a5d67d8d542481373))
+
+
+
+## [2.0.15](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/env-path@2.0.14...@yarn-tool/env-path@2.0.15) (2026-09-06)
+
+
+
+### 🛠　Build System
+
+* update Static Files ([b2f5d72](https://github.com/bluelovers/ws-yarn-workspaces/commit/b2f5d7216773c53eb35f267ba34f8788543d46a1))
+
+
+### ♻️　Chores
+
+* **workspace:** 將所有套件的指令從 yarn 改為 pnpm 並更新依賴版本 ([0505892](https://github.com/bluelovers/ws-yarn-workspaces/commit/0505892e5e7c356f8cf59495fefda1aa681499c6))
+
+
+### 🔖　Miscellaneous
+
+* . ([b545589](https://github.com/bluelovers/ws-yarn-workspaces/commit/b54558925d67304019e2b4f9bb3c4671c429a96e))
+
+
+
 ## [2.0.14](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/env-path@2.0.13...@yarn-tool/env-path@2.0.14) (2026-04-26)
 
 

package/README.md

@@ -1,8 +1,16 @@
-# README.md
+# @yarn-tool/env-path
 
-    
+讀取與寫入 `PATH` 這類環境變數路徑 (Environment Path) 的小型工具，可直接操作 `process.env`，也可操作任意 record-like 的環境變數物件。
 
-## install
+## Features
+
+- 從 `process.env` 或任意 record-like 物件讀取 `PATH` 環境變數
+- 以陣列或字串寫入 `PATH` 環境變數，自動處理分隔符號 (Delimiter)
+- 自動偵測 `PATH` 的實際鍵名（例如 Windows 上可能為 `Path`）
+- 將 `PATH` 字串解析為結構化物件，方便取用各段路徑
+- 在無法存取 `process.env` 的環境下，可透過 `ignoreErrors` 安全地回傳 `undefined`
+
+## Installation
 
 ```bash
 yarn add @yarn-tool/env-path
@@ -10,3 +18,72 @@ yarn-tool add @yarn-tool/env-path
 yt add @yarn-tool/env-path
 ```
 
+## Usage
+
+```ts
+import envPathObject, {
+	processEnv,
+	envPathKey,
+	getEnvPathValue,
+	setEnvPathValue,
+	envObject,
+	delimiter,
+} from '@yarn-tool/env-path';
+
+// 取得目前 process.env 的 PATH 字串
+const pathValue = getEnvPathValue();
+
+// 取得 PATH 在目前環境中的實際鍵名
+const key = envPathKey();
+
+// 以陣列寫入 PATH（自動以平台分隔符號 join）
+setEnvPathValue(['/usr/local/bin', '/usr/bin']);
+
+// 解析 PATH 為結構化物件
+const { path } = envPathObject();
+console.log(path);
+```
+
+## API Documentation
+
+### `processEnv(ignoreErrors?: boolean): NodeJS.ProcessEnv | undefined`
+
+回傳 `process.env`。當存取 `process.env` 拋出例外時：
+
+- `ignoreErrors` 為 falsy（預設）：重新拋出例外
+- `ignoreErrors` 為 `true`：回傳 `undefined`，方便在受限環境（如沙箱）中安全呼叫
+
+### `envPathKey(env?: IRecordLike<string, any>): string`
+
+在給定的環境物件中找出 `PATH` 的實際鍵名（大小寫不敏感）。未傳入 `env` 時使用 `processEnv()`。
+
+### `getEnvPathValue(env?: IRecordLike<string, any>, key?: string): string`
+
+回傳 `PATH` 的字串值。`key` 未傳入時自動以 `envPathKey(env)` 取得。
+
+### `setEnvPathValue(value: string | string[], env?: IRecordLike<string, string>, key?: string, delim?: IPathDelimiter): void`
+
+寫入 `PATH` 值。若 `value` 是陣列，會以 `delim ?? delimiter` 連接成字串後寫入。
+
+### `envObject(env?: IRecordLike<string, any>, key?: string, delim?: IPathDelimiter)`
+
+將環境變數中的 `PATH` 字串解析為結構化物件（透過 `path-env2`）。若 `env` 是 `Map` 等具 `entries()` 的物件，會先轉為普通物件。
+
+### `envPathObject(env?: IRecordLike<string, any>, key?: string, delim?: IPathDelimiter)`
+
+等同於 `envObject(env, key, delim).path`，也是此套件的預設匯出 (Default Export)。
+
+### `delimiter: string`
+
+目前平台的 `PATH` 分隔符號（`path.delimiter`，Unix 為 `:`、Windows 為 `;`）。
+
+## Configuration
+
+此套件無需設定，所有參數皆以函式參數傳入：
+
+| 參數 | 型別 | 說明 |
+| --- | --- | --- |
+| `env` | `IRecordLike<string, any>` | 要操作的環境物件，預設為 `process.env` |
+| `key` | `string` | `PATH` 的鍵名，預設自動偵測 |
+| `delim` | `IPathDelimiter` | 陣列連接用的分隔符號，預設為平台的 `delimiter` |
+| `ignoreErrors` | `boolean` | 存取 `process.env` 失敗時是否忽略例外 |

package/index.d.ts

@@ -1,12 +1,75 @@
 import { IRecordLike } from 'value-from-record';
 import { IPathDelimiter } from 'path-env2';
 export type { IPathDelimiter };
+/**
+ * 平台的 PATH 分隔符號：在此統一轉型是因為 path.delimiter 的型別為 string，
+ * 而 path-env2 需要更窄的 IPathDelimiter，於此收斂型別可避免各呼叫端重複斷言。
+ *
+ * Platform PATH delimiter: the cast is done here because path.delimiter is typed as
+ * string while path-env2 expects the narrower IPathDelimiter, so callers avoid repeated assertions.
+ */
 declare const delimiter: IPathDelimiter;
 export { delimiter };
+/**
+ * 取得 process.env；在某些受限環境（例如沙箱）中存取 process.env 可能拋出例外，
+ * 因此提供 ignoreErrors 讓呼叫端選擇忽略並回傳 undefined，而非中斷流程。
+ *
+ * Get process.env; accessing it may throw in restricted environments (e.g. sandboxes),
+ * so ignoreErrors lets callers ignore the error and receive undefined instead of aborting.
+ *
+ * @param ignoreErrors 為 true 時忽略存取失敗並回傳 undefined / when true, ignore access errors and return undefined
+ * @returns process.env 或 undefined / process.env or undefined
+ */
 export declare function processEnv(ignoreErrors?: boolean): NodeJS.ProcessEnv;
+/**
+ * 在給定環境物件中找出 PATH 的實際鍵名。
+ * Windows 上鍵名可能為 Path 或 PATH（大小寫不一致），直接寫死 'PATH' 會取不到值，
+ * 故交由 keyFromRecord 做大小寫不敏感的比對。
+ *
+ * Find the actual key name of PATH in the given env object.
+ * On Windows the key may be Path or PATH (inconsistent casing), so hardcoding 'PATH' can fail;
+ * keyFromRecord performs a case-insensitive lookup instead.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @returns PATH 的實際鍵名 / the actual key name of PATH
+ */
 export declare function envPathKey(env?: IRecordLike<string, any>): string;
+/**
+ * 讀取 PATH 環境變數的字串值。
+ * key 省略時自動偵測實際鍵名，讓呼叫端不必處理 Windows 的大小寫差異。
+ *
+ * Read the string value of the PATH environment variable.
+ * When key is omitted the actual key is detected automatically, so callers need not handle Windows casing differences.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @returns PATH 字串值 / the PATH string value
+ */
 export declare function getEnvPathValue(env?: IRecordLike<string, any>, key?: string): string;
+/**
+ * 寫入 PATH 環境變數。
+ * 接受陣列形式以便呼叫端以路徑陣列操作，內部統一 join 成平台分隔字串後寫入。
+ *
+ * Set the PATH environment variable.
+ * Accepts an array so callers can work with path lists; it is joined with the platform delimiter before writing.
+ *
+ * @param value 要寫入的 PATH 值（字串或路徑陣列）/ value to write (string or array of paths)
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @param delim 陣列連接用的分隔符號，預設平台 delimiter / delimiter used to join the array, defaults to platform delimiter
+ */
 export declare function setEnvPathValue(value: string | string[], env?: IRecordLike<string, string>, key?: string, delim?: IPathDelimiter): IRecordLike<string, string>;
+/**
+ * 將 PATH 解析後只回傳 path 欄位的便捷函式。
+ * 適合只關心路徑陣列、不需其餘環境變數內容的常見情境。
+ *
+ * Convenience wrapper returning only the `path` field of the parsed PATH.
+ * Useful when only the path array is needed and not the rest of the env content.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @param delim 分隔符號，預設平台 delimiter / delimiter, defaults to platform delimiter
+ */
 export declare function envPathObject(env?: IRecordLike<string, any>, key?: string, delim?: IPathDelimiter): {
     get: {
         factory(): import("path-env2").IPathFactory;
@@ -27,5 +90,22 @@ export declare function envPathObject(env?: IRecordLike<string, any>, key?: stri
     surround(addend: import("path-env2").IPathArray): import("path-env2").IEnvFactory;
     deduplicate(): import("path-env2").IEnvFactory;
 };
+/**
+ * 將環境變數中的 PATH 字串解析為結構化物件（交由 path-env2 處理）。
+ * Map 等具 entries() 的類別需先轉成一般物件，否則 path-env2 無法以 record 方式存取。
+ *
+ * Parse the PATH string in the env object into a structured object (delegated to path-env2).
+ * Map-like objects with entries() are converted to plain objects first, otherwise path-env2 cannot access them as records.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @param delim 分隔符號，預設平台 delimiter / delimiter, defaults to platform delimiter
+ * @returns 含 path 陣列等欄位的解析結果 / parsed result containing the path array and other fields
+ */
 export declare function envObject(env?: IRecordLike<string, any>, key?: string, delim?: IPathDelimiter): import("path-env2").IEnvFactory;
+/**
+ * 預設匯出 (Default Export)：最常用的入口，直接回傳解析後的 path 欄位。
+ *
+ * Default export: the most common entry point, returning the parsed `path` field directly.
+ */
 export default envPathObject;

package/index.js

@@ -10,45 +10,150 @@ exports.envObject = envObject;
 const value_from_record_1 = require("value-from-record");
 const path_env2_1 = require("path-env2");
 const path_1 = require("path");
+/**
+ * 平台的 PATH 分隔符號：在此統一轉型是因為 path.delimiter 的型別為 string，
+ * 而 path-env2 需要更窄的 IPathDelimiter，於此收斂型別可避免各呼叫端重複斷言。
+ *
+ * Platform PATH delimiter: the cast is done here because path.delimiter is typed as
+ * string while path-env2 expects the narrower IPathDelimiter, so callers avoid repeated assertions.
+ */
 const delimiter = path_1.delimiter;
 exports.delimiter = delimiter;
+/**
+ * 取得 process.env；在某些受限環境（例如沙箱）中存取 process.env 可能拋出例外，
+ * 因此提供 ignoreErrors 讓呼叫端選擇忽略並回傳 undefined，而非中斷流程。
+ *
+ * Get process.env; accessing it may throw in restricted environments (e.g. sandboxes),
+ * so ignoreErrors lets callers ignore the error and receive undefined instead of aborting.
+ *
+ * @param ignoreErrors 為 true 時忽略存取失敗並回傳 undefined / when true, ignore access errors and return undefined
+ * @returns process.env 或 undefined / process.env or undefined
+ */
 function processEnv(ignoreErrors) {
+    /**
+     * 正常情況直接回傳 process.env，保留原本的例外行為作為預設值
+     *
+     * Return process.env directly in the normal case, keeping the original throw behavior as default
+     */
     try {
         return process.env;
     }
     catch (e) {
+        /**
+         * 僅在明確要求時吞掉例外；其餘情況重新拋出以保留除錯資訊
+         *
+         * Swallow the exception only when explicitly requested; otherwise rethrow to preserve debug info
+         */
         if (!ignoreErrors) {
             throw e;
         }
     }
 }
+/**
+ * 在給定環境物件中找出 PATH 的實際鍵名。
+ * Windows 上鍵名可能為 Path 或 PATH（大小寫不一致），直接寫死 'PATH' 會取不到值，
+ * 故交由 keyFromRecord 做大小寫不敏感的比對。
+ *
+ * Find the actual key name of PATH in the given env object.
+ * On Windows the key may be Path or PATH (inconsistent casing), so hardcoding 'PATH' can fail;
+ * keyFromRecord performs a case-insensitive lookup instead.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @returns PATH 的實際鍵名 / the actual key name of PATH
+ */
 function envPathKey(env) {
     return (0, value_from_record_1.keyFromRecord)('PATH', env !== null && env !== void 0 ? env : processEnv());
 }
+/**
+ * 讀取 PATH 環境變數的字串值。
+ * key 省略時自動偵測實際鍵名，讓呼叫端不必處理 Windows 的大小寫差異。
+ *
+ * Read the string value of the PATH environment variable.
+ * When key is omitted the actual key is detected automatically, so callers need not handle Windows casing differences.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @returns PATH 字串值 / the PATH string value
+ */
 function getEnvPathValue(env, key) {
+    /**
+     * ??= 僅在未傳入時才取預設值，避免覆蓋呼叫端明確傳入的 undefined 以外的情況
+     *
+     * ??= only computes the default when not supplied, avoiding overwrite of an explicitly passed value
+     */
     env !== null && env !== void 0 ? env : (env = processEnv());
     key !== null && key !== void 0 ? key : (key = envPathKey(env));
     return (0, value_from_record_1.valueFromRecord)(key, env);
 }
+/**
+ * 寫入 PATH 環境變數。
+ * 接受陣列形式以便呼叫端以路徑陣列操作，內部統一 join 成平台分隔字串後寫入。
+ *
+ * Set the PATH environment variable.
+ * Accepts an array so callers can work with path lists; it is joined with the platform delimiter before writing.
+ *
+ * @param value 要寫入的 PATH 值（字串或路徑陣列）/ value to write (string or array of paths)
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @param delim 陣列連接用的分隔符號，預設平台 delimiter / delimiter used to join the array, defaults to platform delimiter
+ */
 function setEnvPathValue(value, env, key, delim) {
     env !== null && env !== void 0 ? env : (env = processEnv());
     key !== null && key !== void 0 ? key : (key = envPathKey(env));
+    /**
+     * 非字串（即陣列）才需要 join；字串維持原樣以保留既有分隔符號
+     *
+     * Only non-strings (i.e. arrays) need joining; strings pass through to keep their existing delimiters
+     */
     if (typeof value !== 'string') {
         value = [...value].join(delim !== null && delim !== void 0 ? delim : delimiter);
     }
     return (0, value_from_record_1.setRecordValue)(value, key, env);
 }
+/**
+ * 將 PATH 解析後只回傳 path 欄位的便捷函式。
+ * 適合只關心路徑陣列、不需其餘環境變數內容的常見情境。
+ *
+ * Convenience wrapper returning only the `path` field of the parsed PATH.
+ * Useful when only the path array is needed and not the rest of the env content.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @param delim 分隔符號，預設平台 delimiter / delimiter, defaults to platform delimiter
+ */
 function envPathObject(env, key, delim) {
     return envObject(env, key, delim).path;
 }
+/**
+ * 將環境變數中的 PATH 字串解析為結構化物件（交由 path-env2 處理）。
+ * Map 等具 entries() 的類別需先轉成一般物件，否則 path-env2 無法以 record 方式存取。
+ *
+ * Parse the PATH string in the env object into a structured object (delegated to path-env2).
+ * Map-like objects with entries() are converted to plain objects first, otherwise path-env2 cannot access them as records.
+ *
+ * @param env 環境物件，預設 process.env / env object, defaults to process.env
+ * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default
+ * @param delim 分隔符號，預設平台 delimiter / delimiter, defaults to platform delimiter
+ * @returns 含 path 陣列等欄位的解析結果 / parsed result containing the path array and other fields
+ */
 function envObject(env, key, delim) {
     env !== null && env !== void 0 ? env : (env = processEnv());
     key !== null && key !== void 0 ? key : (key = envPathKey(env));
     delim !== null && delim !== void 0 ? delim : (delim = delimiter);
+    /**
+     * Map 的 entries 是原型方法，typeof 檢查可同時涵蓋 Map 與自訂的 iterable-like 物件
+     *
+     * Map.entries is a prototype method; the typeof check covers Map and custom iterable-like objects alike
+     */
     if (typeof env.entries === 'function') {
         env = Object.fromEntries((0, value_from_record_1.entriesOfRecord)(env));
     }
     return (0, path_env2_1.pathEnv)(env, key, delim);
 }
+/**
+ * 預設匯出 (Default Export)：最常用的入口，直接回傳解析後的 path 欄位。
+ *
+ * Default export: the most common entry point, returning the parsed `path` field directly.
+ */
 exports.default = envPathObject;
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAgBA,gCAaC;AAED,gCAGC;AAED,0CAQC;AAED,0CAcC;AAED,sCAMC;AAED,8BAeC;AArFD,yDAM2B;AAC3B,yCAAoD;AACpD,+BAA+C;AAI/C,MAAM,SAAS,GAAmB,gBAAiB,CAAC;AAE3C,8BAAS;AAElB,SAAgB,UAAU,CAAC,YAAsB;IAEhD,IACA,CAAC;QACA,OAAO,OAAO,CAAC,GAAG,CAAA;IACnB,CAAC;IACD,OAAO,CAAC,EACR,CAAC;QACA,IAAI,CAAC,YAAY,EACjB,CAAC;YACA,MAAM,CAAC,CAAA;QACR,CAAC;IACF,CAAC;AACF,CAAC;AAED,SAAgB,UAAU,CAAC,GAA8B;IAExD,OAAO,IAAA,iCAAa,EAAC,MAAM,EAAE,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,UAAU,EAAE,CAAC,CAAA;AAClD,CAAC;AAED,SAAgB,eAAe,CAAC,GAA8B,EAC7D,GAAY;IAGZ,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,EAAE,EAAC;IACrB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,CAAC,GAAG,CAAC,EAAC;IAExB,OAAO,IAAA,mCAAe,EAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AACjC,CAAC;AAED,SAAgB,eAAe,CAAC,KAAwB,EAAE,GAAiC,EAC1F,GAAY,EACZ,KAAsB;IAGtB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,EAAE,EAAC;IACrB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,CAAC,GAAG,CAAC,EAAC;IAExB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAC7B,CAAC;QACA,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,IAAA,kCAAc,EAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AACvC,CAAC;AAED,SAAgB,aAAa,CAAC,GAA8B,EAC3D,GAAY,EACZ,KAAsB;IAGtB,OAAO,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,IAAI,CAAA;AACvC,CAAC;AAED,SAAgB,SAAS,CAAC,GAA8B,EACvD,GAAY,EACZ,KAAsB;IAGtB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,EAAE,EAAC;IACrB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,CAAC,GAAG,CAAC,EAAC;IACxB,KAAK,aAAL,KAAK,cAAL,KAAK,IAAL,KAAK,GAAK,SAAS,EAAC;IAEpB,IAAI,OAAQ,GAAqB,CAAC,OAAO,KAAK,UAAU,EACxD,CAAC;QACA,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,IAAA,mCAAe,EAAC,GAAG,CAAC,CAAC,CAAA;IAC/C,CAAC;IAED,OAAO,IAAA,mBAAO,EAAC,GAAuB,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;AACpD,CAAC;AAED,kBAAe,aAAa,CAAA","sourcesContent":["import {\n\tvalueFromRecord,\n\tIRecordLike,\n\tkeyFromRecord,\n\tentriesOfRecord,\n\tsetRecordValue,\n} from 'value-from-record';\nimport { pathEnv, IPathDelimiter } from 'path-env2';\nimport { delimiter as _delimiter } from 'path';\n\nexport type { IPathDelimiter }\n\nconst delimiter: IPathDelimiter = _delimiter as any;\n\nexport { delimiter }\n\nexport function processEnv(ignoreErrors?: boolean)\n{\n\ttry\n\t{\n\t\treturn process.env\n\t}\n\tcatch (e)\n\t{\n\t\tif (!ignoreErrors)\n\t\t{\n\t\t\tthrow e\n\t\t}\n\t}\n}\n\nexport function envPathKey(env?: IRecordLike<string, any>): string\n{\n\treturn keyFromRecord('PATH', env ?? processEnv())\n}\n\nexport function getEnvPathValue(env?: IRecordLike<string, any>,\n\tkey?: string,\n): string\n{\n\tenv ??= processEnv();\n\tkey ??= envPathKey(env);\n\n\treturn valueFromRecord(key, env)\n}\n\nexport function setEnvPathValue(value: string | string[], env?: IRecordLike<string, string>,\n\tkey?: string,\n\tdelim?: IPathDelimiter,\n)\n{\n\tenv ??= processEnv();\n\tkey ??= envPathKey(env);\n\n\tif (typeof value !== 'string')\n\t{\n\t\tvalue = [...value].join(delim ?? delimiter);\n\t}\n\n\treturn setRecordValue(value, key, env)\n}\n\nexport function envPathObject(env?: IRecordLike<string, any>,\n\tkey?: string,\n\tdelim?: IPathDelimiter,\n)\n{\n\treturn envObject(env, key, delim).path\n}\n\nexport function envObject(env?: IRecordLike<string, any>,\n\tkey?: string,\n\tdelim?: IPathDelimiter,\n)\n{\n\tenv ??= processEnv();\n\tkey ??= envPathKey(env);\n\tdelim ??= delimiter;\n\n\tif (typeof (env as Map<any, any>).entries === 'function')\n\t{\n\t\tenv = Object.fromEntries(entriesOfRecord(env))\n\t}\n\n\treturn pathEnv(env as Record<any, any>, key, delim)\n}\n\nexport default envPathObject\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAiCA,gCAuBC;AAcD,gCAGC;AAaD,0CAaC;AAcD,0CAmBC;AAaD,sCAMC;AAcD,8BAoBC;AAzLD,yDAM2B;AAC3B,yCAAoD;AACpD,+BAA+C;AAI/C;;;;;;GAMG;AACH,MAAM,SAAS,GAAmB,gBAAiB,CAAC;AAE3C,8BAAS;AAElB;;;;;;;;;GASG;AACH,SAAgB,UAAU,CAAC,YAAsB;IAEhD;;;;OAIG;IACH,IACA,CAAC;QACA,OAAO,OAAO,CAAC,GAAG,CAAA;IACnB,CAAC;IACD,OAAO,CAAC,EACR,CAAC;QACA;;;;WAIG;QACH,IAAI,CAAC,YAAY,EACjB,CAAC;YACA,MAAM,CAAC,CAAA;QACR,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,UAAU,CAAC,GAA8B;IAExD,OAAO,IAAA,iCAAa,EAAC,MAAM,EAAE,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,UAAU,EAAE,CAAC,CAAA;AAClD,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,eAAe,CAAC,GAA8B,EAC7D,GAAY;IAGZ;;;;OAIG;IACH,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,EAAE,EAAC;IACrB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,CAAC,GAAG,CAAC,EAAC;IAExB,OAAO,IAAA,mCAAe,EAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAAC,KAAwB,EAAE,GAAiC,EAC1F,GAAY,EACZ,KAAsB;IAGtB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,EAAE,EAAC;IACrB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,CAAC,GAAG,CAAC,EAAC;IAExB;;;;OAIG;IACH,IAAI,OAAO,KAAK,KAAK,QAAQ,EAC7B,CAAC;QACA,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,IAAA,kCAAc,EAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAAC,GAA8B,EAC3D,GAAY,EACZ,KAAsB;IAGtB,OAAO,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,IAAI,CAAA;AACvC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CAAC,GAA8B,EACvD,GAAY,EACZ,KAAsB;IAGtB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,EAAE,EAAC;IACrB,GAAG,aAAH,GAAG,cAAH,GAAG,IAAH,GAAG,GAAK,UAAU,CAAC,GAAG,CAAC,EAAC;IACxB,KAAK,aAAL,KAAK,cAAL,KAAK,IAAL,KAAK,GAAK,SAAS,EAAC;IAEpB;;;;OAIG;IACH,IAAI,OAAQ,GAAqB,CAAC,OAAO,KAAK,UAAU,EACxD,CAAC;QACA,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,IAAA,mCAAe,EAAC,GAAG,CAAC,CAAC,CAAA;IAC/C,CAAC;IAED,OAAO,IAAA,mBAAO,EAAC,GAAuB,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;AACpD,CAAC;AAED;;;;GAIG;AACH,kBAAe,aAAa,CAAA","sourcesContent":["import {\n\tvalueFromRecord,\n\tIRecordLike,\n\tkeyFromRecord,\n\tentriesOfRecord,\n\tsetRecordValue,\n} from 'value-from-record';\nimport { pathEnv, IPathDelimiter } from 'path-env2';\nimport { delimiter as _delimiter } from 'path';\n\nexport type { IPathDelimiter }\n\n/**\n * 平台的 PATH 分隔符號：在此統一轉型是因為 path.delimiter 的型別為 string，\n * 而 path-env2 需要更窄的 IPathDelimiter，於此收斂型別可避免各呼叫端重複斷言。\n *\n * Platform PATH delimiter: the cast is done here because path.delimiter is typed as\n * string while path-env2 expects the narrower IPathDelimiter, so callers avoid repeated assertions.\n */\nconst delimiter: IPathDelimiter = _delimiter as any;\n\nexport { delimiter }\n\n/**\n * 取得 process.env；在某些受限環境（例如沙箱）中存取 process.env 可能拋出例外，\n * 因此提供 ignoreErrors 讓呼叫端選擇忽略並回傳 undefined，而非中斷流程。\n *\n * Get process.env; accessing it may throw in restricted environments (e.g. sandboxes),\n * so ignoreErrors lets callers ignore the error and receive undefined instead of aborting.\n *\n * @param ignoreErrors 為 true 時忽略存取失敗並回傳 undefined / when true, ignore access errors and return undefined\n * @returns process.env 或 undefined / process.env or undefined\n */\nexport function processEnv(ignoreErrors?: boolean)\n{\n\t/**\n\t * 正常情況直接回傳 process.env，保留原本的例外行為作為預設值\n\t *\n\t * Return process.env directly in the normal case, keeping the original throw behavior as default\n\t */\n\ttry\n\t{\n\t\treturn process.env\n\t}\n\tcatch (e)\n\t{\n\t\t/**\n\t\t * 僅在明確要求時吞掉例外；其餘情況重新拋出以保留除錯資訊\n\t\t *\n\t\t * Swallow the exception only when explicitly requested; otherwise rethrow to preserve debug info\n\t\t */\n\t\tif (!ignoreErrors)\n\t\t{\n\t\t\tthrow e\n\t\t}\n\t}\n}\n\n/**\n * 在給定環境物件中找出 PATH 的實際鍵名。\n * Windows 上鍵名可能為 Path 或 PATH（大小寫不一致），直接寫死 'PATH' 會取不到值，\n * 故交由 keyFromRecord 做大小寫不敏感的比對。\n *\n * Find the actual key name of PATH in the given env object.\n * On Windows the key may be Path or PATH (inconsistent casing), so hardcoding 'PATH' can fail;\n * keyFromRecord performs a case-insensitive lookup instead.\n *\n * @param env 環境物件，預設 process.env / env object, defaults to process.env\n * @returns PATH 的實際鍵名 / the actual key name of PATH\n */\nexport function envPathKey(env?: IRecordLike<string, any>): string\n{\n\treturn keyFromRecord('PATH', env ?? processEnv())\n}\n\n/**\n * 讀取 PATH 環境變數的字串值。\n * key 省略時自動偵測實際鍵名，讓呼叫端不必處理 Windows 的大小寫差異。\n *\n * Read the string value of the PATH environment variable.\n * When key is omitted the actual key is detected automatically, so callers need not handle Windows casing differences.\n *\n * @param env 環境物件，預設 process.env / env object, defaults to process.env\n * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default\n * @returns PATH 字串值 / the PATH string value\n */\nexport function getEnvPathValue(env?: IRecordLike<string, any>,\n\tkey?: string,\n): string\n{\n\t/**\n\t * ??= 僅在未傳入時才取預設值，避免覆蓋呼叫端明確傳入的 undefined 以外的情況\n\t *\n\t * ??= only computes the default when not supplied, avoiding overwrite of an explicitly passed value\n\t */\n\tenv ??= processEnv();\n\tkey ??= envPathKey(env);\n\n\treturn valueFromRecord(key, env)\n}\n\n/**\n * 寫入 PATH 環境變數。\n * 接受陣列形式以便呼叫端以路徑陣列操作，內部統一 join 成平台分隔字串後寫入。\n *\n * Set the PATH environment variable.\n * Accepts an array so callers can work with path lists; it is joined with the platform delimiter before writing.\n *\n * @param value 要寫入的 PATH 值（字串或路徑陣列）/ value to write (string or array of paths)\n * @param env 環境物件，預設 process.env / env object, defaults to process.env\n * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default\n * @param delim 陣列連接用的分隔符號，預設平台 delimiter / delimiter used to join the array, defaults to platform delimiter\n */\nexport function setEnvPathValue(value: string | string[], env?: IRecordLike<string, string>,\n\tkey?: string,\n\tdelim?: IPathDelimiter,\n)\n{\n\tenv ??= processEnv();\n\tkey ??= envPathKey(env);\n\n\t/**\n\t * 非字串（即陣列）才需要 join；字串維持原樣以保留既有分隔符號\n\t *\n\t * Only non-strings (i.e. arrays) need joining; strings pass through to keep their existing delimiters\n\t */\n\tif (typeof value !== 'string')\n\t{\n\t\tvalue = [...value].join(delim ?? delimiter);\n\t}\n\n\treturn setRecordValue(value, key, env)\n}\n\n/**\n * 將 PATH 解析後只回傳 path 欄位的便捷函式。\n * 適合只關心路徑陣列、不需其餘環境變數內容的常見情境。\n *\n * Convenience wrapper returning only the `path` field of the parsed PATH.\n * Useful when only the path array is needed and not the rest of the env content.\n *\n * @param env 環境物件，預設 process.env / env object, defaults to process.env\n * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default\n * @param delim 分隔符號，預設平台 delimiter / delimiter, defaults to platform delimiter\n */\nexport function envPathObject(env?: IRecordLike<string, any>,\n\tkey?: string,\n\tdelim?: IPathDelimiter,\n)\n{\n\treturn envObject(env, key, delim).path\n}\n\n/**\n * 將環境變數中的 PATH 字串解析為結構化物件（交由 path-env2 處理）。\n * Map 等具 entries() 的類別需先轉成一般物件，否則 path-env2 無法以 record 方式存取。\n *\n * Parse the PATH string in the env object into a structured object (delegated to path-env2).\n * Map-like objects with entries() are converted to plain objects first, otherwise path-env2 cannot access them as records.\n *\n * @param env 環境物件，預設 process.env / env object, defaults to process.env\n * @param key PATH 的鍵名，預設自動偵測 / PATH key, detected automatically by default\n * @param delim 分隔符號，預設平台 delimiter / delimiter, defaults to platform delimiter\n * @returns 含 path 陣列等欄位的解析結果 / parsed result containing the path array and other fields\n */\nexport function envObject(env?: IRecordLike<string, any>,\n\tkey?: string,\n\tdelim?: IPathDelimiter,\n)\n{\n\tenv ??= processEnv();\n\tkey ??= envPathKey(env);\n\tdelim ??= delimiter;\n\n\t/**\n\t * Map 的 entries 是原型方法，typeof 檢查可同時涵蓋 Map 與自訂的 iterable-like 物件\n\t *\n\t * Map.entries is a prototype method; the typeof check covers Map and custom iterable-like objects alike\n\t */\n\tif (typeof (env as Map<any, any>).entries === 'function')\n\t{\n\t\tenv = Object.fromEntries(entriesOfRecord(env))\n\t}\n\n\treturn pathEnv(env as Record<any, any>, key, delim)\n}\n\n/**\n * 預設匯出 (Default Export)：最常用的入口，直接回傳解析後的 path 欄位。\n *\n * Default export: the most common entry point, returning the parsed `path` field directly.\n */\nexport default envPathObject\n"]}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@yarn-tool/env-path",
-  "version": "2.0.14",
-  "description": "",
+  "version": "2.0.16",
+  "description": "read/write PATH-like environment variables from process.env or any record-like env object",
   "keywords": [
+    "env-path",
+    "environment-variables",
+    "process-env",
+    "PATH",
+    "env",
     "yarn",
     "yarn-tool",
     "npm",
@@ -29,17 +34,19 @@
   "author": "bluelovers",
   "main": "index.js",
   "scripts": {
-    "coverage": "yarn run test -- --coverage",
+    "coverage": "pnpm run test -- --coverage",
     "lint": "ynpx --quiet eslint -- **/*.ts",
-    "test": "jest --passWithNoTests",
+    "test": "node --run test:node",
     "test:jest": "jest --passWithNoTests",
-    "test:jest:coverage": "yarn run test:jest -- --coverage",
-    "test:jest:snapshot": "yarn run test:jest -- -u",
+    "test:jest:coverage": "pnpm run test:jest -- --coverage",
+    "test:jest:snapshot": "pnpm run test:jest -- -u",
     "test:mocha": "ynpx --quiet -p ts-node -p mocha mocha -- --require ts-node/register \"!(node_modules)/**/*.{test,spec}.{ts,tsx}\"",
-    "test:snapshot": "yarn run test -- -u",
+    "test:node": "tsx --test --test-update-snapshots **/*.node-spec.ts **/*.node-test.ts **/*.spec.ts **/*.test.ts",
+    "test:snapshot": "pnpm run test -u",
+    "test:tsc": "tsc --noEmit & echo typescript check done",
     "test:tsd": "ynpx tsd",
-    "preversion": "echo preversion && yarn run test",
-    "prepublishOnly:update": "yarn run ncu && yarn run sort-package-json",
+    "preversion": "echo preversion && pnpm run test",
+    "prepublishOnly:update": "pnpm run ncu && pnpm run sort-package-json",
     "ncu": "yarn-tool ncu -u",
     "sort-package-json": "yarn-tool sort",
     "tsc:showConfig": "ynpx get-current-tsconfig -p"
@@ -52,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8c939a673ef0f088d4a3aa8a240ed6c28d390f98"
+  "gitHead": "471c63ee11851f0ac3487f23d1c472936f99b460"
 }