Global

Members

EINT_USE

Description:

• iseint之use範圍表

  另須為安全整數(Number.isSafeInteger), 見iseint

Source:

• _numRange.mjs, line 52

ENUM_USE

Description:

• isenum之use範圍表

  可帶小數, 故為連續區間, 無整數限制

Source:

• _numRange.mjs, line 38

MAX_SAFE

Description:

• isenum(有效數字)與iseint(有效整數)之opt.use範圍表(單一來源)

  規格: 主控dspec〈輸入參數之檢測機制〉§7.1。兩函數之use範圍集中於此, 計時上限取自_const.mjs之TIMER_TIME_MAX, 不另寫數字; 日後單值檢測產生訊息(如 must be an integer between 1 and 65535)亦應讀本檔。

  每項之鍵意義: min: 下界(含); max: 上界(含); gt: 下界(不含); lt: 上界(不含) 未列之鍵視為無該限制。表為凍結之無原型物件, 故use為'constructor'、'proto'、'toString'等不會誤中

  表內各use之範圍依據(見各項註解), 以測試(test/_numRange.test.mjs)鎖定各use之上下界

Source:

• _numRange.mjs, line 20

TIMER_TIME_MAX :Integer

Description:

• 計時器(setTimeout、setInterval)之延遲毫秒上限

  值為 2^31 - 1 = 2147483647 毫秒, 約 24.8 天。

  【為何需要此上限 —— nodejs與瀏覽器之行為不同, 且皆為靜默失效】

  兩環境對超界值之處理機制不同, 實測(nodejs v24 / chromium)如下:

  輸入ms nodejs chromium

  ---

  2147483647 正常排程 正常排程 2^31 立即觸發(1ms)+警告 立即觸發(ToInt32為-2147483648) 2^32 - 5000 立即觸發(1ms)+警告 立即觸發(ToInt32為-5000) 2^32 + 5000 立即觸發(1ms)+警告 【約5秒後觸發】(ToInt32為5000) 2^32 + 100 立即觸發(1ms)+警告 【約100ms後觸發】(ToInt32為100) Infinity 立即觸發(1ms)+警告 立即觸發(ToInt32為0) NaN 立即觸發(1ms)+警告 立即觸發(ToInt32為0) -1 立即觸發(1ms)+警告 立即觸發

  nodejs為自家實作: 超過 2^31-1 一律夾為 1ms, 並以 process.on('warning') 發出 TimeoutOverflowWarning(NaN為TimeoutNaNWarning、負數為TimeoutNegativeWarning), 不拋錯。

  瀏覽器則依 WebIDL 之 long 型別轉換(即 ToInt32), 對超界值做 modulo 2^32 之【環繞】而非夾制, 且【完全沒有警告】。故 2^32 + 5000 於瀏覽器不是立即觸發, 而是 5 秒後觸發 —— 表面上看起來正常運作, 只是時間完全錯了(49.7天變成5秒), 比nodejs之立即觸發更難察覺。 環繞亦非單調: 輸入越大不代表延遲越長, 無法由行為反推輸入。

  wsemi為同構套件(前後端皆用), 故不可依賴runtime之行為, 必須於進入setTimeout之前自行檢核。

  【如何處置超界值 —— 檢核而非夾制】

  計時毫秒屬輸入參數之檢測(主控dspec〈輸入參數之檢測機制〉§7.1、K3), 現行處置為:

  1. 判斷: 以isenum(v, { use: 'timer' })(可帶小數)或iseint(v, { use: 'timer' })(須為整數)判定, 兩者之計時範圍(0 ~ TIMER_TIME_MAX)取自本常數, 集中於_numRange.mjs, 各函數不自寫數字; 超過上限、Infinity、NaN、負數、'0x10'、包裝物件等皆判定為非有效之計時毫秒。
  2. opt類參數(有預設者, 含JSDoc標[參數=預設]之位置參數): 非預期之輸入(含超界)視為未給, 改用預設, 不再夾至上限(經_optVal.mjs統一處理, opt.debug為true時輸出警告); 例: delay、debounce、waitFun、cache系、fsTask、domDetect。
  3. 必須參數(無預設者): 超界與其他非預期之輸入同樣報錯, 不夾至上限; 例: pmTimeout。 舊制「超大值之意圖為很久, 夾至上限最接近其意圖, 退回預設值反而變成高頻輪詢」已隨第221項改為上述處置 (超大值改用預設; 欲「很久」者由呼叫端給上限內之有限值, 或該參數本身以null等明確值表示不限時, 如execProcess.timeout)。

  仍使用Math.min夾至本上限者(皆非opt類參數之檢測):

  • 內部計算得之等待時間(如fsDownloadFileVerifyCore依整體時限剩餘時間排定之等待, 其輸入已通過檢測), 為避免計算結果超界;
  • execCli、execCliSession之timeoutMs等: 屬第三級(須先改下游), 尚待下游先行補檢測後再依上述處置改寫, 現況仍夾至上限。

  【與安全整數界線之區別 —— 兩者須分開檢核】

  iseint(v) 預設use為'safe', 擋的是「非安全整數」(Infinity、1e300、超出 Number.MAX_SAFE_INTEGER 者), 但 2^31 本身【是】合法的安全整數, 只是超過計時器之32位元上限。 故判定計時毫秒須明給 use: 'timer', 只做安全整數之檢核【擋不住】本上限: 第一層 iseint/isenum 預設(safe): 擋型別錯誤與非安全整數 第二層 use: 'timer': 擋超過計時器上限者

  【用法】

  判定輸入參數: iseint(ms, { use: 'timer', min: 1 }) //取自_numRange.mjs, 不直接讀本常數 夾制內部計算值: import cst from './_const.mjs' wait = Math.min(wait, cst.TIMER_TIME_MAX) //須用min, 用max會把正常值放大為上限

Source:

• _const.mjs, line 70

Type:

• Integer

Methods

_normKey(k) → {String|null}

Description:

• 欄位名之正規化(單一擁有者, 供arr2dt、dtmapping、ltdtmapping共用): 回傳欄位名字串, 或null表示略過

  規格: 使用者2026-11-14(排程第430項第二批, 裁定表〈三、arr2dt〉〈四、dtmapping〉): 略過: 空字串''、null、undefined(含陣列空洞)、物件(含陣列、包裝物件)、函數、Symbol(鍵只看字串鍵) 數字視同字串(String(k)); 其餘原始值(布林、BigInt)依String(k)取欄位名, 同修前(zipObject與lodash get皆以字串為鍵)

Source:

• _normKey.mjs, line 14

Parameters:

Returns:

Type

String | null

_setOwnKey(o, k, v)

Description:

• 以自有資料屬性寫入鍵值(單一擁有者, 供dtpick、dtmapping、arr2dt、ltdtDiffByKey等組裝結果物件之函數共用)

  鍵先轉為屬性鍵(Symbol原樣, 其餘String), 鍵'proto'以defineProperty設為自有之可列舉、可寫、可設定之資料屬性(一般賦值會改結果物件之原型而非新增欄位), 其餘鍵以一般賦值寫入

  規格: 使用者2026-11-14(排程第430項第二批, dspec〈輸入參數之檢測機制〉§11〈第二批〉): 鍵一律只看自有可列舉字串鍵, __proto__為自有欄位時以一般欄位寫入

Source:

• _setOwnKey.mjs, line 15

Parameters:

binUrlProblem(v) → {String}

Description:

• 清單之網址(廠商檔、分割檔、壓縮檔之url)之檢核(規格M2、F15之網址釘選判定): 只接受兩種已釘選之形式, 回傳錯誤說明或''

  ①GitHub版本標籤之資產網址 https://github.com///releases/download//<檔>(恰此6段; tag可含編碼之斜線); ②GitHub原始檔網址且ref為40碼小寫提交: https://raw.githubusercontent.com////或https://github.com///raw//。 須為https、不得帶帳密、不得有查詢字串、片段或埠號(以原始字串判定, 含空之?、#與預設埠:443)、反斜線與空白; 各段不得為空, 各段解碼後owner、repo、檔名與原始檔路徑之各段不得含斜線或反斜線; 其他主機、releases/latest、分支或標籤之原始檔網址(含master、main、HEAD、refs/heads/…與其他分支名)、blob頁面皆拒收(分支名無法自網址與標籤區分, 故原始檔一律須為提交)

Source:

• _binRules.mjs, line 54

Parameters:

Returns:

Type

String

buildCmd(src, port, sysRoot) → {Object}

Description:

• 組成子指令

Source:

• _execPortPids.mjs, line 323

Parameters:

Returns:

Type

Object

buildPsScript(port) → {String}

Description:

• 產生查詢指定本地埠之PowerShell腳本，只輸出數值與位址等ASCII欄位(避開字碼頁)，不以狀態篩選

  資料來源與耗時：優先以System.Reflection.Emit動態定義P/Invoke，呼叫作業系統之GetExtendedTcpTable(IPv4與IPv6各取一次，只輸出本地埠相符之列)，表於PowerShell內解析；不編譯C#、不產生暫存檔，耗時約為PowerShell啟動加一次查表(不到1秒)，不隨系統連線數明顯增加，系統忙碌時亦無編譯階段之拖累；Reflection.Emit或該API失敗(如受限語言模式下被擋、API回非預期之錯誤碼)時退回Get-NetTCPConnection -LocalPort，其耗時隨系統內TCP連線數增加(連線數千至上萬時可達十數秒)。兩條路徑輸出同一格式，以開始標記前之WSEMI-PORTPIDS-VIA api|cmdlet標示實際走哪一條(解析時略過)

  退回路徑查無連線時Get-NetTCPConnection拋CmdletizationQuery_NotFound_LocalPort，視為查無；其餘錯誤(含指令不存在CommandNotFoundException，其Category亦為ObjectNotFound，故以FullyQualifiedErrorId分辨)輸出錯誤識別碼並以離開碼3結束

  輸出用Write-Output而非[Console]::Out.WriteLine，後者於受限語言模式(Constrained Language Mode)被擋

Source:

• _execPortPids.mjs, line 193

Parameters:

Returns:

Type

String

buildSpawnArgs(command, argsopt, optopt) → {Object}

Description:

• 將command與args轉為可安全交給child_process.spawn之參數, 主要處理Windows下npm全域命令為.cmd批次檔而spawn無法直接執行之問題 策略優先順序:

  1. .exe → 直接spawn
  2. .cmd → 解析JS入口, 用node直接執行(繞過cmd.exe, 支援多行參數)
  3. .cmd為npm shim(cmd-shim之執行行)而入口檔不存在 → 拋ENOENT(同不存在之批次檔)
  4. 其餘.cmd → 透過cmd.exe /d /s /c執行(fallback, 不支援多行參數) 非Windows平台原樣回傳 回傳物件三個分支一律帶opt鍵(無額外設定時為{}), 呼叫端可直接展開至spawn之選項物件

Source:

• execCliCore.mjs, line 285

Parameters:

Returns:

Type

Object

buildSpawnEnv(envExtraopt) → {Object}

Description:

• 建立子進程之環境變數物件: 以process.env為底, 加入PYTHONIOENCODING=utf-8, 再併入envExtra(同名以envExtra為準) 每次呼叫重新求值且不動本進程process.env, 故並行調用可各自帶不同值 PYTHONIOENCODING對一般python直譯器有效(sys.stdout.encoding變utf-8); 對PyInstaller打包之exe無效, 其以隔離模式嵌入直譯器且文件明載刻意忽略PYTHONIOENCODING與PYTHONUTF8, 該類程式須於打包時以-X utf8_mode=1指定, 或由本進程以execProcess之codeCmd('auto'或系統字碼頁)解碼其輸出 Windows下環境變數大小寫不敏感但JS物件鍵敏感, 故併入前先移除大小寫不同之同名既有鍵, 否則呼叫端傳Path而process.env為PATH時兩鍵並存且Windows取原值, 注入靜默失效 此刪除僅限win32: POSIX環境變數大小寫敏感, Path與PATH為兩個獨立變數, 誤刪即退化

Source:

• execCliCore.mjs, line 390

Parameters:

Returns:

Type

Object

buildValidator(rule) → {function|null}

Description:

• 建立驗證函式 支援'nonempty', 'json', 'min:100'或自訂函式, 多規則可用逗號串接

Source:

• execCli.mjs, line 59

Parameters:

Returns:

Type

function | null

chkFsPath(v, name) → {String|null}

Description:

• fs系函數之路徑參數檢查，內部共用不對外(R-FS-INVALID-PATH-01)

  路徑須為非空字串且不含NUL字元；不符者為「無效」，與「存在與否」分開判定，故不得走到fs.statSync等再被當成「不存在」而回成功 回傳之說明字串不帶輸入值(Node之錯誤訊息會回顯輸入值，且含NUL之字串會原樣帶入)，格式依輸入規格V19: invalid <名稱>: must be <種類描述>

Source:

• _chkFsPath.mjs, line 11

Parameters:

Returns:

Type

String | null

classify(src, res, port, timeout) → {Object}

Description:

• 判定子指令之結果: 無法啟動、逾時、非預期之離開碼、輸出無法解析皆為失敗；成功者解析出PID

  netstat與powershell須離開碼0；lsof查無監聽者時以離開碼1結束，0與1皆為正常

Source:

• _execPortPids.mjs, line 536

Parameters:

Returns:

Type

Object

defer() → {Object}

Description:

• 延後警告之收集器(optVal.defer): 判定時不讀呼叫端之opt, 業務鍵全部讀完後才至多讀一次opt.debug/funLog並依序警告(規格§4 V11: 每鍵只讀一次, 且debug之讀取不影響其後業務鍵之讀取)

  用法: let col = optVal.defer(); x = col.take(v, def, rule); ...(其餘業務鍵); col.flush(opt) take之回傳值同optVal(v, def, rule)(不警告); flush於無非預期者時不讀opt; flush(opt, true)則一律讀一次(供轉交debug、funLog給下層), 回傳{ debug, funLog }

Source:

• _optVal.mjs, line 98

Returns:

Type

Object

detectorEvent(start, optopt) → {Object}

Description:

• 建立event模式之偵測器, 回傳EventEmitter並掛create與dispose

  create於microtask啟動: 晚於本次同步流程(例如Vue 2指令於bind時create, 元素於其後才插入), 早於任何計時器; create後同步才掛之監聽亦收得到首次事件 start(emit, addCleanup)於啟動時呼叫一次: 每建立一項資源(觀察器、計時器等)即以addCleanup登記其釋放函數, 使建立途中拋錯時已建立者仍可釋放 emit(name, value)經evEmit派發: 監聽器拋錯時有error監聽者則emit('error'), 否則console.error, 不中斷偵測亦不被吞掉; 已釋放後之emit不發出 start為null代表無法偵測(元素無效或環境不支援), 此時create與dispose皆可呼叫但永不觸發, error為原因 生命週期: 未開始 → 已create待啟動 → 偵測中 → 已釋放; create只於未開始時有效(重複呼叫不重複偵測), dispose後create無效, create後同一輪dispose則永不啟動; dispose可重複呼叫且回傳true start拋錯時視同無法偵測: error為所拋之值, 已登記之資源立即釋放, 轉為已釋放 釋放依登記之相反順序逐一呼叫, 單一釋放函數拋錯不影響其他; 已釋放後才登記者立即釋放

Source:

• _detector.mjs, line 39

Parameters:

Returns:

Type

Object

detectorFail(mode, reason) → {Promise|Object}

Description:

• 無法偵測時之回報: promise模式回傳被拒絕之Promise, event模式回傳永不觸發之偵測器(error為原因)

Source:

• _detector.mjs, line 127

Parameters:

Returns:

Type

Promise | Object

errToStr(err) → {String}

Description:

• 錯誤值轉字串且保證不拋錯，內部共用不對外

  一般Error同其toString('名稱: 訊息')，拋出之值為null、undefined時為'null'、'undefined'；無法轉字串者(無原型物件、已撤銷之Proxy、toString會拋錯者)退取字串message，仍無則為'unknown error'

  使用端: catch內須把呼叫端可能拋出之任意值轉為字串者(try內會執行呼叫端之toJSON、getter、Proxy陷阱、回調或注入之fs等)，如o2j、obj2str、obj2stru8arr

  刻意不匯入任何模組(含getErrorMessage): 本模組供基礎轉換函數(含cint等被getErrorMessage匯入者)使用, 有匯入即可能形成循環匯入

Source:

• _errToStr.mjs, line 13

Parameters:

Returns:

Type

String

escapeWinArg(arg) → {String}

Description:

• 轉義cmd.exe的單一參數(cross-spawn escapeArgument邏輯) 參考: https://qntm.org/cmd

Source:

• execCliCore.mjs, line 191

Parameters:

Returns:

Type

String

escapeWinCmd(cmd) → {String}

Description:

• 轉義cmd.exe的命令部分

Source:

• execCliCore.mjs, line 218

Parameters:

Returns:

Type

String

execCliOnce(command, argsopt, optopt, traceopt) → {Promise}

Description:

• 單次非同步呼叫(內部使用, 不含重試邏輯)

Source:

• execCli.mjs, line 124

Parameters:

Returns:

Type

Promise

execThrownMsg(e, err) → {String}

Description:

• 執行外部程序之入口讀取呼叫端輸入失敗時之訊息，內部共用不對外

  取execSpawnError所得之message；其只得code(呼叫端拋出非Error之值，如字串、null，取不到message而以code代之)時改取getErrorMessage，為空退_errToStr，保留拋出值之文字(R-EXEC-FAIL-01之13)

  使用端: execCli、execCliSession、execCliJsonRpc、execProcess之入口catch

Source:

• _execThrownMsg.mjs, line 16

Parameters:

Returns:

Type

String

fsMissFns(fs, names) → {Array}

Description:

• 檢查注入之fs物件是否提供指定函數(內部用)，回傳缺少者之名稱陣列；fs不是物件(含null)時視為全部缺少，讀取成員拋錯者視為缺少

Source:

• _fsMissFns.mjs, line 8

Parameters:

Returns:

Type

Array

getEnvValue(env, key) → {*}

Description:

• 由環境變數物件取值, 鍵不分大小寫(Windows環境變數大小寫不敏感, 但{...process.env}展開後之物件鍵敏感, 如Path與PATH)

Source:

• execCliCore.mjs, line 25

Parameters:

Returns:

Type

*

getMode(opt) → {String}

Description:

• 取偵測模式, 'event'以外皆為'promise'

Source:

• _detector.mjs, line 17

Parameters:

Returns:

Type

String

isBinName(v) → {Boolean}

Description:

• 是否為清單可用之檔名(原始字串, 不接受包裝物件)

Source:

• _binRules.mjs, line 20

Parameters:

Returns:

Type

Boolean

isBinRel(v) → {Boolean}

Description:

• 是否為清單可用之相對路徑: 以/分隔, 每段合檔名規則(中間可有空白)且非保留裝置名, 無空段、.、..、絕對路徑、反斜線(原始字串, 不接受包裝物件)

Source:

• _binRules.mjs, line 31

Parameters:

Returns:

Type

Boolean

isFileFollowLink(fp) → {Boolean}

Description:

• 判定路徑是否為檔案(跟隨連結), 用於命令搜尋: 一般檔案與指向檔案之符號連結為真; stat讀不到但本身為連結者亦為真(如WindowsApps之App Execution Alias, 其stat失敗而lstat為連結, where.exe亦列出); 資料夾與不存在者為假 不用fsIsFile: 其以lstat判定且連結一律為假, 會漏掉以連結安裝之執行檔

Source:

• execCliCore.mjs, line 38

Parameters:

Returns:

Type

Boolean

isFileStat(fp) → {Boolean}

Description:

• 判定路徑是否為實體檔案(跟隨連結, 懸空連結為假), 用於批次檔是否存在

Source:

• execCliCore.mjs, line 57

Parameters:

Returns:

Type

Boolean

isRealError(v) → {Boolean}

Description:

• 判定是否為真Error，內部共用不對外

  真Error為instanceof Error(含子類別、DOMException、Error之Proxy、以Error.prototype為原型者)或Error.isError為真(以內部槽判定，含跨realm之Error)；執行環境無Error.isError時，以未帶Symbol.toStringTag者之內部標籤為'[object Error]'或'[object DOMException]'判跨realm之Error(帶Symbol.toStringTag者其標籤可偽裝，不據以判定)

  不用lodash isError: 其對「非plain而帶字串name、message」之物件亦為真，會把恰帶此二欄之一般資料類別(聊天訊息、驗證項目等)壓成字串而遺失其餘欄位

  使用端: _realErrorToStr(序列化時把真Error轉為'名稱: 訊息'字串，供obj2stru8arr、obj2str之replacer)

  刻意不匯入任何模組: 本模組供基礎轉換函數使用, 有匯入即可能形成循環匯入

Source:

• _isRealError.mjs, line 15

Parameters:

Returns:

Type

Boolean

maxminsLimits(maxmins, keyMax, keyMin) → {Array}

Description:

• 檢測maxmins各區間之上下限並取值(arrGroupByMaxmin、arrLookupByMaxmin共用, 單一擁有者)

  使用者2026-11-02: 區間上下限屬使用方設定之邊界, 以isenum判定, Infinity、'0x10'、包裝物件等皆為非預期, 表「無上下限」由呼叫端給適當之有限極值; 上下限無效(含未給、null)即throw Error(invalid maxmins[索引].鍵: must be a valid number), 訊息不帶輸入值; 設定錯即報錯, 不靜默略過該區間

  先檢測全部區間再回傳, 故是否報錯與arr之內容無關; 每個鍵只讀一次, 回傳轉換後之數值(檢測之值即使用之值)

Source:

• _maxminsLimits.mjs, line 22

Parameters:

Returns:

Type

Array

optVal(v, def, rule, optopt) → {*}

Description:

• opt類數值參數之檢測與預設(單一擁有者), 供第221項第二批各函數共用, 不各自手寫

  規格: 主控dspec〈輸入參數之檢測機制〉K3(opt類參數遇非預期之輸入視為未給、改用預設, 含超出範圍; opt.debug警告)、V5、§7.1

  使用者2026-10-31: opt類參數(opt之鍵, 以及JSDoc標[參數=預設]或程式碼有回退之位置參數)給了非預期之輸入(含超出範圍)時, 視為未給、改用預設, 不報錯; 必須參數遇非預期之輸入才報錯(不使用本函數, 各函數自行判定)

  規則: v為undefined或null視為未給, 回傳預設 有效(rule.kind為'enum'以isenum判定, 為'eint'以iseint判定, rule.chk為其opt, 如{ use: 'timer', gt: 0 })則回傳Number(v), 即去頭尾空白後Number(…)取值(K4), 其後只用轉換值 非預期(含超出範圍、Infinity、包裝物件、'0x10'等isenum/iseint拒收者)回傳預設, 不拋錯 debug: 呼叫端傳入其opt(opt.debug === true, 非布林視為false)時, 非預期另輸出警告, 警告出口為opt.funLog(函數)或console.warn; 警告為固定詞彙, 只含函數名、參數名、種類描述與所採之預設(程式常數), 不含傳入之值(K9、V20); 同一函數、同一參數每個行程只警告一次(與_numOpt.mjs共用去重表, parseNumOpt.resetWarned()可重設) 位置參數無法帶debug者(呼叫端無opt)不傳opt, 即不警告

Source:

• _optVal.mjs, line 31

Parameters:

Returns:

Type

*

ot(v, …args) → {Object}

Description:

• dayjs之薄包裝(內部使用), 修正年份0000~0099之無時區日期字串被對映為1900~1999

  緣由: dayjs解析無時區之日期字串時(其內建正則分支)以new Date(y, m, d, h, mi, s, ms)建立日期, 依JS規則年份0~99被對映為1900~1999, 如dayjs('0050-03-04')得1950-03-04、dayjs('0000-01')得1900-01; 致ismonth、isday、istime等判斷因format結果與輸入字串不同而不收年份0000~0099, 其後之轉換與計算(time2day、addMonth等)若放行則結果差1900年

  做法: 年份0000~0099之標準寫法無時區字串, 以Date.setFullYear/setHours建立Date(不經兩位數年份對映, 月、日、時等超出範圍者與new Date同樣進位, 故不合法之字串format後仍與輸入不同)再交dayjs; 其餘輸入(其他年份、含時區之字串、非字串、無參數等)與其餘參數原樣交dayjs, 行為與直接呼叫dayjs相同

Source:

• _dayjs.mjs, line 24

Parameters:

Returns:

Type

Object

parseInput(command, args, opt) → {Object}

Description:

• execCli之輸入判型與預設值(內部使用), 讀取或判型拋錯(getter拋錯、已撤銷之Proxy等不可讀之輸入)時直接拋出, 由execCli承接

Source:

• execCli.mjs, line 442

Parameters:

Returns:

Type

Object

parseJsEntryFromCmd(cmdPath) → {Object|null}

Description:

• 從.cmd shim中解析出實際入口檔案路徑(可能為JS, 亦可能為原生.exe) npm全域安裝的.cmd格式固定, 末行為: ... "%_prog%" "%dp0%\node_modules...\entry" %* 入口可能為.js / .cjs / .mjs / 無副檔名 / .exe(如opencode的bin/opencode.exe), 故一律抓引號內node_modules後的相對路徑, 再以isFileStat驗證實體檔存在 (只匹配.js會讓無副檔名入口落入cmd.exe fallback, 破壞多行prompt) 回傳後由buildSpawnArgs依副檔名決定: .exe直接spawn, 其餘交給node

  入口不存在時不回傳null(與「不是npm shim」區分), 而回傳exists為false; 是否據以判定為「未能啟動」另看isExecLine: 僅當入口出現於cmd-shim之執行行(行首或&之後, 可前置"%_prog%"與shebang參數, 以%*結尾)時為true, 自訂批次檔於IF EXIST等判斷句內引用同樣式者為false, 仍交cmd.exe退路

Source:

• execCliCore.mjs, line 238

Parameters:

Returns:

Type

Object | null

parseLsof(text) → {Object}

Description:

• 解析lsof -t之輸出(每行一個PID)

  含非數字之字詞視為無法解析

Source:

• _execPortPids.mjs, line 293

Parameters:

Returns:

Type

Object

parseNetstat(text, port) → {Object}

Description:

• 解析netstat -ano之輸出，取本地埠為port之監聽列PID

  欄位依空白切開: 第1欄協定、第2欄本地位址、第3欄遠端位址、最後一欄PID，狀態欄(可能缺漏、錯誤或為在地化文字)不使用； 輸出內完全沒有TCP或UDP列(含表頭以外皆亂碼、空輸出)視為無法解析

Source:

• _execPortPids.mjs, line 90

Parameters:

Returns:

Type

Object

parseNumOpt(opt, spec) → {Object}

Description:

• isenum與iseint共用之opt解析(單一擁有者)

  規格: 主控dspec〈輸入參數之檢測機制〉K3(非預期之輸入視為未給, 改用預設; opt.debug警告)、§4 V4~V7、V11、§6 V20、§7.1

  opt為選填之設定, 非預期之輸入一律視為未給、改用預設, 不拋錯(使用者 2026-10-31: 「isenum/iseint 自己的 opt 也是給預設」): opt為undefined或null視為未給(呼叫端不進入本函數) opt須為一般物件(原型為Object.prototype或null, 不含陣列、類別實例、包裝物件、Date等), 否則整份視為{} 各鍵為undefined或null視為未給; 給了而不屬該鍵之種類者視為未給(use改用預設) 未宣告之鍵忽略(本函數不轉傳opt, 故於debug時提示, 如誤拼之minExlusive) 每個鍵只讀一次(快照), 讀取拋錯(存取器)視為該鍵無效 範圍為空(含與use之交集為空)時, 明確給定之界值(min、max、gt、lt)皆視為未給, use保留

  opt.debug(布林, 預設false; 非布林視為false): 為true時, 非預期之輸入另輸出警告, 說明哪個鍵因非預期已改用預設: 警告出口: opt.funLog為函數者交funLog(msg, info), 否則console.warn(msg); 出口拋錯一律忽略 警告為固定詞彙, 只含函數名、鍵名(僅短識別字)、種類描述與所採之預設(程式常數), 不含傳入之值(K9、V20) 同一函數、同一鍵、同一原因每個行程只警告一次(逐筆呼叫之判斷函數不洗版); 去重表有上限, 滿了即不再警告 opt本身非一般物件時整份視為{}, 讀不到debug, 故不警告

Source:

• _numOpt.mjs, line 27

Parameters:

Returns:

Type

Object

parsePs(text, port) → {Object}

Description:

• 解析buildPsScript之腳本輸出，取本地埠為port之監聽列PID

  須有開始與結束標記，其間每個非空行須為R <本地埠> <遠端位址> <遠端埠> <PID>，否則視為無法解析；開始標記之前的行(含WSEMI-PORTPIDS-VIA api|cmdlet)略過。遠端位址可為IPv4點分、IPv6(含壓縮與::ffff:對映形)或Get-NetTCPConnection顯示之字串，只有0.0.0.0與::且遠端埠0之列成立為監聽列

Source:

• _execPortPids.mjs, line 241

Parameters:

Returns:

Type

Object

parseVersion(v) → {Array|null}

Description:

• 自字串解析版本號(取第一個「數字.數字.數字」)

Source:

• strCompareForVersion.mjs, line 10

Parameters:

Returns:

Type

Array | null

(generator) plan(port, platform, useBoth)

Description:

• 判定流程(兩版共用)，以generator逐一交出要執行之資料來源，接收classify之結果，最後回傳{ ok, src, pids, msg }

  Windows: 先netstat，查到即採用(useBoth為true時仍續查)；netstat查無或失敗時以PowerShell(作業系統API GetExtendedTcpTable，其失敗時退回Get-NetTCPConnection，見buildPsScript；對本流程而言同為'powershell'來源)確認，其查無才判無人； 因netstat之查無不採信(系統回報之狀態錯誤時整列漏列)，netstat之失敗與查無同樣轉查PowerShell，最終之查無以其結果為準；PowerShell查詢失敗即整體失敗； useBoth為true時兩者皆查並取聯集，PowerShell查詢失敗即整體失敗(不以netstat之部分結果代替)。 其他平台: lsof，失敗即整體失敗

Source:

• _execPortPids.mjs, line 618

Parameters:

pmMarkHandled(v)

Description:

• 對原生Promise預先掛上無作用之拒絕處理，使其標記為已處理，內部共用不對外

  用於接收先行產生之Promise陣列而依序或限量取用者(pmSeries、pmMap未給fun時)：排在後面之Promise先reject時，若尚未被取用即成為未處理之rejection(Node預設即結束行程)，預先標記後其結果仍由原流程取用

  以品牌判定原生Promise：直接以載入時之Promise.prototype.then執行(call)，非原生Promise者於then之品牌檢查(內部槽位)即拋TypeError而忽略，不讀其任何屬性、不觸發Proxy之陷阱、不呼叫一般thenable之then； 故跨realm(vm新context、iframe)之原生Promise、原型為null或原型被改之原生Promise與子類別之實例皆標記；不經instanceof(其不認跨realm者與原型為null者，且對Proxy會觸發getPrototypeOf陷阱)

  原始值直接略過；util.types.isPromise可用時先以之預檢(非Promise者不進then，免建例外之成本)，結果與只用then之品牌檢查相同

  then取得衍生Promise之建構子(species)時會讀原生Promise之constructor與其Symbol.species，子類別或被改寫者其建構子或getter為使用端程式(同instanceof時之既有行為)；任何拋錯皆忽略

Source:

• _pmMarkHandled.mjs, line 40

Parameters:

pmReadItems(rs, onlyArrayopt) → {Object|null}

Description:

• 於進入時讀取呼叫端之容器(陣列或鍵值物件)為內部陣列，pmMap、pmSeries、pmChain共用，內部共用不對外(R-PM-SETTLE-01規則17、R-OBJ-ITER-01)

  真陣列(Array.isArray)以索引迴圈複製為明確建立之普通陣列(不使用slice：其結果由使用端之Symbol.species決定，且保留空洞語意)； 鍵值物件(isobj為真，或isarr為真而非真陣列者即以Symbol.toStringTag偽稱Array之物件)依自有可列舉字串鍵(Object.keys)展開為[{ k, v }]，length與其他鍵同為一般鍵，不依其length迭代； 判定或讀取拋錯(元素getter拋錯、已撤銷Proxy、Symbol.toStringTag讀取即拋錯等)時，已讀到之元素若為先行產生之原生Promise則先標記已處理(其後不會被取用，否則其reject成為未處理之rejection)，再將該錯誤拋出，由呼叫端以reject回報

Source:

• _pmReadItems.mjs, line 18

Parameters:

Throws:

Returns:

Type

Object | null

pmSettleByState(pm, state, msg)

Description:

• 依pmConvertResolve之結果(state與msg)決定Promise之resolve或reject，內部共用，不對外

  state為success則resolve(msg)，為cancelled則reject({ reason: 'cancelled' })，其餘reject(msg)

  使用端: pmQueue、pmThrottle、pmInvResolve，三者之取消一律以{ reason: 'cancelled' }傳出，不得以pmConvertResolve之msg(空字串)傳出

Source:

• _pmSettleByState.mjs, line 12

Parameters:

rangeVal(v, def, name, kind) → {Number}

Description:

• 隨機系範圍參數(vstart、vend)之檢測(單一擁有者), 供random*、pseudoRandom*共10個函數共用, 不各自手寫

  規格: 主控dspec〈輸入參數之檢測機制〉§11 Q1-b(使用者2026-11-12定: C10隨機範圍無效即同步拋錯, 如randomIntRange('a', 2)不再回0)、K4(檢測之值即使用之值)、K9(不回顯輸入值)、§6 V19(訊息格式)

  規則: v為undefined或null視為未給, 回傳預設(各函數JSDoc之[vstart=0]、[vend=100]等, 範圍參數仍可省略) 有給則依kind判定: 'eint'以iseint(v, { use: 'safe' })判定(安全整數), 'enum'以isenum(v)判定(有效數字, 無範圍限制) 有效回傳Number(v)(數字字串去頭尾空白後取值, 其後只用轉換值) 非有效(整數系之小數、超出安全整數範圍、Infinity、'0x10'、包裝物件、非數字字串、布林、物件、陣列等)throw Error(invalid ${name}: must be an integer或invalid ${name}: must be a valid number), 訊息不帶輸入值

Source:

• _rangeVal.mjs, line 25

Parameters:

Returns:

Type

Number

readInput(port, opt, execDef) → {Object}

Description:

• 讀取輸入，opt之讀取與判型一律於try內(getter拋錯、已撤銷之Proxy以失敗訊息回報，不拋錯)

Source:

• _execPortPids.mjs, line 475

Parameters:

Returns:

Type

Object

realErrorToStr(v) → {*}

Description:

• 序列化時把真Error轉為字串，內部共用不對外

  真Error(判定見_isRealError)呼叫其toString；toString恰為Object預設者(會得'[object Object]'而失去name與message)或無可呼叫之toString者(如以null為原型、toString被設為非函數)，以Error.prototype.toString之語意得'名稱: 訊息'(讀不到name時名稱為'Error'，message為空時只有名稱)；非真Error者回傳原值

  讀取toString、name、message或呼叫toString時拋出之值不在此攔截，由使用端序列化之catch回報

  使用端: obj2stru8arr、obj2str之replacer

  只匯入_isRealError(其不匯入任何模組): 本模組供基礎轉換函數使用, 匯入其他模組即可能形成循環匯入

Source:

• _realErrorToStr.mjs, line 18

Parameters:

Returns:

Type

*

resolveCommand(cmd, cwdopt, envopt) → {String}

Description:

• 找到命令的實際路徑(.cmd / .exe) 未帶副檔名者同where: 先搜本進程之工作目錄再搜本進程之PATH, 並依PATHEXT補副檔名 只給檔名之.cmd/.bat同cmd.exe(退路即由cmd.exe搜尋): 先搜子進程之工作目錄(子進程env有NoDefaultCurrentDirectoryInExePath時不搜)再搜子進程env之PATH, 不補副檔名 含目錄(絕對或相對)者原樣回傳

Source:

• execCliCore.mjs, line 135

Parameters:

Returns:

Type

String

runCmd(prog, args, o) → {Promise}

Description:

• 非同步版之預設執行函數，回傳與child_process.spawnSync同形之結果

  隱藏視窗、不經shell、stdin不開啟；逾時或stdout超過上限即強制結束子程序(SIGKILL，netstat與powershell不另建子程序)，error之code為ETIMEDOUT或ENOBUFS；本函數不reject

Source:

• _execPortPids.mjs, line 357

Parameters:

Returns:

Type

Promise

runCmdSync(prog, args, o) → {Object}

Description:

• 同步版之預設執行函數(child_process.spawnSync)，回傳{ status, stdout, error }

  隱藏視窗、不經shell、stdin不開啟；逾時或輸出超過上限時spawnSync強制結束子程序(SIGKILL)，error之code為ETIMEDOUT或ENOBUFS；同步拋錯轉為error，本函數不拋錯

Source:

• _execPortPids.mjs, line 452

Parameters:

Returns:

Type

Object

splitArrs()

Description:

• 廣義數字陣列之計算(arrAdd、arrMulti、arrAccum、arrProduct、arrNorm)共用之opt.base與「每個陣列至少1個有效數字」(單一擁有者)

  規格: 主控dspec〈輸入參數之檢測機制〉§11 第221項待決第15項(使用者2026-10-31) 基於廣義數字之陣列, 於計算處理時, 僅針對[有效數字類]處理, 非有效數字一律以該函數之基準值opt.base代入(arrAdd 0、arrMulti 1、arrAccum 0、arrProduct 0、arrNorm 0); 每個輸入陣列各自至少要有1個有效數字(含空陣列, 皆視為0個), 否則throw Error(invalid <名稱>: must contain a valid number), 多陣列帶索引如invalid arrs[1] opt.base以isenum判定, 非預期(K3)視為未給、改用預設, opt.debug為true時警告

  規格: 主控dspec〈輸入參數之檢測機制〉§11 第221項第6項(使用者2026-11-03), 空陣列為合法資料, 不因其為空而報錯, 但由陣列算出單一數值者, 空陣列算不出而報錯 逐項處理而回陣列者(arrAdd、arrMulti、arrAccum): 空進空出, 空陣列回[](reduceArrs於n=0時回[]; arrAccum自行回[]); 有元素但無有效數字者仍throw 由陣列算出單一數值者(arrMax、arrMin、arrNorm、arrProduct): 空陣列throw(arrNorm經chkValid視空陣列為0個有效數字; arrProduct另以chkNotEmpty使任一邊為空即throw; arrMax與arrMin不使用本模組, 各自檢查)

Source:

• _arrNum.mjs, line 25

toResultError(err) → {Error|String}

Description:

• 結果物件之error值正規化且保證不拋錯，內部共用不對外

  捕捉之值為Error物件(真Error，經_isRealError判定，含跨realm與無原型之Error，同R-CODEC-ERR-01之1)或非空字串者原樣回傳；其餘(null、undefined、一般物件、已撤銷之Proxy等)經_errToStr轉字串，仍為空字串者為'unknown error'，故回傳值恆為truthy(R-FS-RESULT-01之5)

  使用端: 回傳結果物件之fs函數之catch，如fsWriteJson、fsReadTextCore、fsWriteTextCore、fsCreateFileCore、fsCopyFileCore、fsCopyFolderCore、fsCreateFolderCore、fsDeleteFileCore、fsDeleteFolderCore、fsRenameFileCore、fsRenameFolderCore、fsCleanFolderCore

Source:

• _toResultError.mjs, line 15

Parameters:

Returns:

Type

Error | String

whereList(cmd, o) → {Array}

Description:

• 依序列出命令之實體路徑: 先搜dirFirst(有給時)再依序搜PATH各目錄, 每個目錄先比對原名再依PATHEXT逐一補上副檔名 不呼叫where.exe: 其輸出為系統字碼頁(如Big5), 以utf-8解碼時含非ASCII字元之路徑(如中文使用者名稱下之%APPDATA%\npm, 或於中文資料夾內npm run時所加入之node_modules.bin)會成亂碼而解析失敗; 亦免每次解析都啟動子程序(參考cross-spawn以which於JS內搜尋PATH)

Source:

• execCliCore.mjs, line 78

Parameters:

Returns:

Type

Array