Global

Members

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之前自行夾制。 夾制後兩環境行為一致(皆為正常排程至上限), 環境差異消失。

  【為何是夾制而非退回預設值或拋錯】

  呼叫端給出超大值時, 其意圖顯然是「很久」或「幾乎不觸發」, 夾至 24.8 天最接近該意圖; 退回預設值(如50ms)會變成高頻輪詢, 與意圖完全相反且更危險; 拋錯則對既有呼叫端為破壞性變更。

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

  ispint(v, { useLimitSafe: true }) 擋的是「非安全整數」(Infinity、1e300、超出 Number.MAX_SAFE_INTEGER 者), 但 2^31 本身【是】合法的安全整數, 只是超過計時器之32位元上限。 故型別與安全整數之檢核【擋不住】本上限, 兩層界線必須各自處理: 第一層 ispint / isp0int 等: 擋型別錯誤與非安全整數 第二層 本常數之夾制: 擋超過計時器上限者

  【用法】

  import cst from './_const.mjs' timeAlive = Math.min(timeAlive, cst.TIMER_TIME_MAX) //須用min, 用max會把正常值放大為上限

Source:

• _const.mjs, line 59

Type:

• Integer

Methods

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 47

Parameters:

Returns:

Type

function | null

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) → {Promise}

Description:

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

Source:

• execCli.mjs, line 111

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

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

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

optNum(opt, key, def, ruleopt) → {Number}

Description:

• 取設定物件之數值選項, 無效時回傳預設值; 供各函數之數值選項共用同一套規則, 不各自手寫檢查

  數字與數字字串皆可(isnum), 字串先轉為數字再判定, 例如'12.34'為12.34、'5'為5、' 7 '為7; 空字串、純空白字串、非數字字串、NaN、null、布林等皆非isnum, 一律用預設 以Number轉換後判定, 不用cdbl: cdbl把Infinity轉為有限之Number.MAX_VALUE, 會使有限與否之判定失效 低於下界(min, minOpen為true時須大於min)者用預設, below為'clamp'時改夾至下界 +Infinity依意圖處置: timer之計時器毫秒夾至計時器上限(同delay, 見_const.mjs), inf為'keep'者保留(例如容許誤差之無限大即任何變化皆容許), 其餘用預設; NaN用預設, -Infinity視為低於下界 int為true時須為整數(Infinity依上一條處置) timer為true時有效值再以Math.min夾至計時器上限: 超大值之意圖為「很久」, 夾至上限最接近其意圖, 不視為無效

Source:

• _optNum.mjs, line 31

Parameters:

Returns:

Type

Number

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

Description:

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

Source:

• execCli.mjs, line 385

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

parseVersion(v) → {Array|null}

Description:

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

Source:

• strCompareForVersion.mjs, line 10

Parameters:

Returns:

Type

Array | null

pmMarkHandled(v)

Description:

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

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

  只處理原生Promise(含子類別)，以Promise.prototype.then.call執行，不呼叫一般thenable之then(避免觸發其副作用)，任何拋錯皆忽略

Source:

• _pmMarkHandled.mjs, line 10

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:

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

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