wsemi 1.9.13 → 1.9.15

package/src/execProcess.mjs

@@ -3,15 +3,17 @@ import codec from './_execProcessCodec.mjs'
 import cp from 'child_process'
 import get from 'lodash-es/get.js'
 import genPm from './genPm.mjs'
-import isearr from './isearr.mjs'
+import isarr from './isarr.mjs'
 import isbol from './isbol.mjs'
 import isfun from './isfun.mjs'
+import isstr from './isstr.mjs'
 import isestr from './isestr.mjs'
 import isnum from './isnum.mjs'
 import strleft from './strleft.mjs'
 import strright from './strright.mjs'
 import arrHas from './arrHas.mjs'
 import execProcessKillPid from './execProcessKillPid.mjs'
+import execSpawnError from './_execSpawnError.mjs'
 
 
 /**
@@ -20,15 +22,15 @@ import execProcessKillPid from './execProcessKillPid.mjs'
  * Unit Test: {@link https://github.com/yuda-lyu/wsemi/blob/master/test/execProcess.test.mjs Github}
  * @memberOf wsemi
  * @param {String} prog 輸入執行檔或程式語言位置字串，若為註冊系統的全域指令，例如可直接給'Python'，腳本需自行接收呼叫引數，並將回傳資料轉json字串後print/log到dos視窗，即可由nodejs接收
- * @param {String|Array} args 輸入腳本檔案位置字串或參數
+ * @param {String|Array} args 輸入參數陣列或字串，例如腳本檔案位置字串，空陣列或空字串代表無參數；非陣列亦非字串時reject錯誤訊息(不拋錯)
  * @param {Object} [opt={}] 輸入設定物件
- * @param {String} [opt.mode='spawn'] 輸入執行模式字串，可選'spawn'、'exec'、'execFile'，預設'spawn'。'spawn'不經shell直接執行，輸出以串流處理，適合大量輸出或長時間執行，prog與args不需也不可加引號；'exec'經shell執行，prog與args以空白串接成指令字串，適合須用到shell語法之情形，陣列型args之元素含空白且未含雙引號者會自動以雙引號包住，prog含空白亦同，已含雙引號者視為呼叫端自行處理而原樣串接，字串型args視為呼叫端已自組之指令列，原樣串接不加引號；'execFile'不經shell直接執行可執行檔，args須為陣列，給字串會被當成單一參數。三種模式之stdout與stderr皆以Buffer接收後走同一條解碼路徑
- * @param {Function} [opt.cbStdout=null] 輸入回調stdout函數，預設null。收到的是經串流解碼之字串，多位元組字元跨chunk時會等到完整才給，故不會收到空字串；codeCmd為'auto'時回調為盡力判定，該串流首次遇到非utf-8位元組後才改用系統字碼頁，之前已回調之字串不追溯，最終結果以resolve或reject之字串為準
+ * @param {String} [opt.mode='spawn'] 輸入執行模式字串，可選'spawn'、'exec'、'execFile'，預設'spawn'。'spawn'不經shell直接執行，輸出以串流處理，適合大量輸出或長時間執行，prog與args不需也不可加引號；'exec'經shell執行，prog與args以空白串接成指令字串，適合須用到shell語法之情形，陣列型args之元素含空白且未含雙引號者會自動以雙引號包住，prog含空白亦同，已含雙引號者視為呼叫端自行處理而原樣串接，字串型args視為呼叫端已自組之指令列，原樣串接不加引號；'execFile'不經shell直接執行可執行檔，args須為陣列，給字串會被當成單一參數。三種模式之stdout與stderr皆以Buffer接收後走同一條解碼路徑；惟'exec'與'execFile'之stdout或stderr超過1MB(node之maxBuffer預設值)時子程序會被node終止，reject為`code[null]:\n訊息`，大量輸出請用'spawn'
+ * @param {Function} [opt.cbStdout=null] 輸入回調stdout函數，預設null。收到的是經串流解碼之字串，多位元組字元跨chunk時會等到完整才給，故不會收到空字串；codeCmd為'auto'時回調為盡力判定，該串流首次遇到非utf-8位元組後才改用系統字碼頁，之前已回調之字串不追溯，最終結果以resolve或reject之字串為準。回調內拋出之錯誤不會被攔截，將成為未捕捉例外，請於回調內自行處理
  * @param {Function} [opt.cbStderr=null] 輸入回調stderr函數，預設null，行為同cbStdout
  * @param {String} [opt.codeCmd='utf8'] 輸入解碼stdout與stderr之編碼字串，預設'utf8'。可給TextDecoder支援之標籤，例如'utf8'、'big5'、'gbk'、'gb18030'、'shift_jis'、'euc-kr'、'euc-jp'、'latin1'、'utf-16le'，亦可給Windows字碼頁編號寫法如'cp950'、'950'、'cp936'、'cp932'、'cp949'、'cp437'、'cp1252'；給'system'表示用當前作業系統字碼頁，win32以chcp查詢一次後快取，其他平台為utf-8；給'auto'表示先以utf-8嚴格解碼，遇非utf-8位元組之串流改用系統字碼頁，適合不確定子程序輸出編碼之情形，例如Windows原生指令與以ANSI字碼頁輸出之打包程式。非有效字串視為未設定而用預設值，有效字串但不支援之編碼則於執行前reject並帶該標籤。輸出開頭之utf-8 BOM會被移除
  * @param {Boolean} [opt.useChcp=false] 輸入是否於指令前置chcp 65001，僅'exec'模式生效，預設false。可使主控台工具改以utf-8輸出，副作用是其訊息語言可能變為英文；使用時codeCmd請維持預設'utf8'或給'auto'，不要搭配'system'
  * @param {Number} [opt.timeout=null] 輸入逾時毫秒數，預設null表示不限制；逾時觸發時會調用execProcessKillPid強制關閉子進程及其子孫程序，並reject回傳逾時訊息
- * @returns {Promise} 回傳Promise，resolve回傳stdout與stderr依到達順序合併之字串，不另加換行，子程序自己的換行原樣保留；reject回傳錯誤訊息，離開碼非0時為`code[N]:\n訊息`，逾時為`timeout[Nms]:\n訊息`
+ * @returns {Promise} 回傳Promise，resolve回傳stdout與stderr依到達順序合併之字串，不另加換行，子程序自己的換行原樣保留；reject回傳錯誤訊息字串：離開碼非0時為`code[N]:\n訊息`，訊息為子程序之輸出，子程序因訊號結束時N為null；逾時為`timeout[Nms]:\n訊息`；無法啟動子程序時(找不到執行檔、權限不足、非有效執行檔、參數過長、參數含空字元、系統資源用盡等)為`spawn[錯誤碼]:\n訊息`，訊息為node之錯誤說明(可含執行檔路徑)，不含args之內容；args型別不符、codeCmd不支援或spawn模式prog含引號時為說明字串
  * @example
  * //need test in nodejs
  *
@@ -45,6 +47,7 @@ import execProcessKillPid from './execProcessKillPid.mjs'
  *
  * if (true) {
  *     //execFile與spawn之args須為陣列, 每個元素為一個參數; 給字串會被當成單一參數而失敗
+ *     //密碼置於命令列參數時同機其他使用者可由程序列表看到; 失敗訊息不含args, 但子程序自身之輸出可能回顯
  *     let prog = `C:\\Program Files\\7-Zip\\7z.exe`
  *     let pw = 'AbcD1234'
  *     let args = ['a', 'abc.7z', 'abc.txt', `-p${pw}`]
@@ -60,15 +63,6 @@ import execProcessKillPid from './execProcessKillPid.mjs'
  */
 function execProcess(prog, args, opt = {}) {
 
-    //check
-    if (!isearr(args) && !isestr(args)) {
-        throw new Error(`args is not an effective array or string`)
-    }
-    let bArgsStr = isestr(args) //字串型args於exec模式視為呼叫端已自組之指令列
-    if (isestr(args)) {
-        args = [args]
-    }
-
     //mode
     // spawn: 非同步執行命令，適合處理大量資料或長時間執行的程式，輸出以串流方式處理。spawnSync 為 spawn 的同步版本。
     // exec: 在 shell 中非同步執行命令，輸出被緩衝，適合輸出量較小的情況。execSync 為 exec 的同步版本。
@@ -107,6 +101,19 @@ function execProcess(prog, args, opt = {}) {
     //pm
     let pm = genPm()
 
+    //check args, 須為陣列(可為空陣列)或字串(可為空字串), 空陣列與空字串代表無參數; 其餘型別以reject回報, 不同步拋錯, 訊息不帶args之值
+    if (!isarr(args) && !isstr(args)) {
+        pm.reject(`args is not an array or string`)
+        return pm
+    }
+    let bArgsStr = isestr(args) //非空字串型args於exec模式視為呼叫端已自組之指令列
+    if (isestr(args)) {
+        args = [args]
+    }
+    else if (isstr(args)) {
+        args = [] //空字串代表無參數
+    }
+
     //check
     if (!arrHas(mode, ['spawn', 'exec', 'execFile'])) {
         pm.reject(`invalid mode[${mode}]`)
@@ -121,16 +128,21 @@ function execProcess(prog, args, opt = {}) {
     //start, 建立子進程並接線, labelSystem為系統字碼頁標籤, 僅codeCmd為'auto'或'system'時需要
     let start = (labelSystem) => {
 
+        //spawn不經shell, prog含引號會被當成檔名之一部分, 於啟動前reject
+        if (mode === 'spawn') {
+            let cr = strleft(prog, 1)
+            let cl = strright(prog, 1)
+            if (cr === `"` || cl === `"` || cr === `'` || cl === `'`) {
+                pm.reject(`prog[${prog}] of spawn does not need to add quotes`)
+                return
+            }
+        }
+
         //r
         let r = null
         try {
             if (mode === 'spawn') {
                 // console.log('mode',mode)
-                let cr = strleft(prog, 1)
-                let cl = strright(prog, 1)
-                if (cr === `"` || cl === `"` || cr === `'` || cl === `'`) {
-                    throw new Error('prog of spawn doens not need to add quotes')
-                }
                 r = cp.spawn(prog, args, {
                     windowsHide: true, //執行的主程序若沒有主控台調用執行程序就不會有視窗, 但若通過pm2執行會有, 須設定windowsHide=true
                     shell: false,
@@ -167,10 +179,26 @@ function execProcess(prog, args, opt = {}) {
             }
         }
         catch (err) {
-            pm.reject(err)
+            //同步拋錯(EPERM、UNKNOWN、ENAMETOOLONG、參數檢查錯誤等), 轉為不含參數值之字串
+            let e = execSpawnError(err)
+            pm.reject(`spawn[${e.code}]:\n${e.message}`)
             return
         }
 
+        //timer, bTimeout, 逾時計時器於下方設定, 先宣告供error與close使用
+        let timer = null
+        let bTimeout = false
+
+        //error, 須於存取stdout與stderr前監聽: node對EMFILE、ENFILE不建立stdio即於nextTick發出'error', 先存取會拋TypeError且'error'無人監聽而拉倒程序
+        //  可能為'找不到可執行檔','權限不足','系統資源用盡'等, node所附之spawnargs含完整參數(exec模式為整條指令列), 故轉為不含參數值之字串
+        r.on('error', (err) => {
+            if (timer !== null) {
+                clearTimeout(timer)
+            }
+            let e = execSpawnError(err)
+            pm.reject(`spawn[${e.code}]:\n${e.message}`)
+        })
+
         //decOut, decErr, stdout與stderr各持一個串流解碼器, 多位元組字元跨chunk時由解碼器暫存, 不會被切成U+FFFD
         let label = cc.label
         if (cc.mode === 'system') {
@@ -201,11 +229,15 @@ function execProcess(prog, args, opt = {}) {
             }
         }
 
-        //stdout data
-        r.stdout.on('data', onData('out', decOut, cbStdout))
+        //stdout data, EMFILE、ENFILE時node未建立stdio(undefined), 由上方error回報
+        if (r.stdout) {
+            r.stdout.on('data', onData('out', decOut, cbStdout))
+        }
 
         //stderr data, 太多程式把warning或log輸出到stderr, 已無法視為有err發生
-        r.stderr.on('data', onData('err', decErr, cbStderr))
+        if (r.stderr) {
+            r.stderr.on('data', onData('err', decErr, cbStderr))
+        }
 
         //buildMsg, 於close時收尾: 各解碼器flush, 'auto'且已改判之串流以全新解碼器重播原始chunk, 最後依到達順序合併, 不另加換行(chunk切點由作業系統決定, 附加換行會落在子程序輸出的任意位置)
         let buildMsg = () => {
@@ -257,8 +289,6 @@ function execProcess(prog, args, opt = {}) {
         // })
 
         //timer, 若有設定timeout, 逾時觸發時調用execProcessKillPid殺整棵程序樹
-        let timer = null
-        let bTimeout = false
         if (timeout !== null) {
             timer = setTimeout(() => {
                 bTimeout = true
@@ -288,14 +318,6 @@ function execProcess(prog, args, opt = {}) {
             }
         })
 
-        //error, 監聽(例如執行spawn本身)錯誤訊息, 可能為'找不到可執行檔','權限不足','系統資源用盡'等
-        r.on('error', (err) => {
-            if (timer !== null) {
-                clearTimeout(timer)
-            }
-            pm.reject(err)
-        })
-
     }
 
     //系統字碼頁僅'auto'與'system'需要, 首次會等chcp查詢完才啟動子進程, 之後為快取; 固定標籤同步啟動, 與既有時序相同
@@ -306,7 +328,8 @@ function execProcess(prog, args, opt = {}) {
         codec.getSystemCodePage()
             .then(start)
             .catch((err) => {
-                pm.reject(err)
+                let e = execSpawnError(err)
+                pm.reject(`spawn[${e.code}]:\n${e.message}`)
             })
     }
 

package/src/execProcessKillPid.mjs

@@ -1,5 +1,6 @@
 import treeKill from 'tree-kill'
 import genPm from './genPm.mjs'
+import getErrorMessage from './getErrorMessage.mjs'
 
 
 /**
@@ -8,7 +9,7 @@ import genPm from './genPm.mjs'
  * Unit Test: {@link https://github.com/yuda-lyu/wsemi/blob/master/test/execProcessKillPid.test.mjs Github}
  * @memberOf wsemi
  * @param {Number|String} pid 輸入程序pid
- * @returns {Promise} 回傳Promise，resolve回傳成功訊息，reject回傳錯誤訊息
+ * @returns {Promise} 回傳Promise，resolve回傳成功訊息`pid[N] killed`，reject回傳錯誤訊息字串`pid[N] kill failed: 訊息`；Windows下訊息含taskkill之輸出，其為系統字碼頁而可能無法正確顯示
  * @example
  * //need test in nodejs
  *
@@ -40,9 +41,10 @@ function execProcessKillPid(pid) {
     let pm = genPm()
 
     //treeKill, Windows內部呼叫「taskkill /pid PID /T /F」, Linux/macOS則以ps/pgrep遞迴尋找子pid後逐一發signal
+    //失敗時tree-kill給Error物件(pid非數字、taskkill失敗等), 轉為錯誤訊息字串, 與resolve之訊息格式對稱
     treeKill(Number(pid), 'SIGKILL', (err) => {
         if (err) {
-            pm.reject(err)
+            pm.reject(`pid[${pid}] kill failed: ${getErrorMessage(err)}`)
         }
         else {
             pm.resolve(`pid[${pid}] killed`)

package/test/_execSpawnError.test.mjs

@@ -0,0 +1,81 @@
+import assert from 'assert'
+import cp from 'child_process'
+import execSpawnError from '../src/_execSpawnError.mjs'
+
+
+describe(`_execSpawnError`, function() {
+
+    let SA = 'SECRET_ARG_7d1f' //機密標記
+
+    //mkErr, 依node之錯誤形狀造Error物件, 不實際spawn
+    let mkErr = (props) => {
+        return Object.assign(new Error(props.message), props)
+    }
+
+    it(`should keep the message and code of a system error that has errno`, function() {
+        //P01a: 有errno之系統錯誤, message為「syscall 錯誤碼」不含參數, 原樣使用; 不讀spawnargs
+        let err = mkErr({ message: 'spawn C:/x.exe ENOENT', code: 'ENOENT', errno: -4058, syscall: 'spawn C:/x.exe', path: 'C:/x.exe', spawnargs: ['a', SA] })
+        assert.strict.deepStrictEqual(execSpawnError(err), { code: 'ENOENT', message: 'spawn C:/x.exe ENOENT' })
+    })
+
+    it(`should strip the Received value of node argument validation errors and keep the argument name`, function() {
+        //P01b: 無errno之參數檢查錯誤, 去除「. Received 值」起之尾段
+        let e1 = mkErr({ message: `The argument 'args[2]' must be a string without null bytes. Received '${SA}\\x00x'`, code: 'ERR_INVALID_ARG_VALUE' })
+        let e2 = mkErr({ message: `The "file" argument must be of type string. Received undefined`, code: 'ERR_INVALID_ARG_TYPE' })
+        let e3 = mkErr({ message: `The property 'options.env['K']' must be a string without null bytes. Received '${SA}\\x00'\nline2`, code: 'ERR_INVALID_ARG_VALUE' })
+        let r = [e1, e2, e3].map(execSpawnError)
+        assert.strict.deepStrictEqual(r, [
+            { code: 'ERR_INVALID_ARG_VALUE', message: `The argument 'args[2]' must be a string without null bytes` },
+            { code: 'ERR_INVALID_ARG_TYPE', message: `The "file" argument must be of type string` },
+            { code: 'ERR_INVALID_ARG_VALUE', message: `The property 'options.env['K']' must be a string without null bytes` },
+        ])
+    })
+
+    it(`should not contain the argument value for the real error thrown by node spawn with a null byte`, function() {
+        //P01b: 以node實際拋出之錯誤驗證訊息格式, node若改變格式致值外露即失敗
+        let err = null
+        try {
+            cp.spawn(process.execPath, ['-e', '1', SA + '\u0000x'])
+        }
+        catch (e) {
+            err = e
+        }
+        assert.strict.deepStrictEqual(err !== null && String(err.message).includes(SA), true) //前提: node原訊息含值
+        let r = execSpawnError(err)
+        assert.strict.deepStrictEqual(r.code, 'ERR_INVALID_ARG_VALUE')
+        assert.strict.deepStrictEqual(r.message.includes(SA), false)
+        assert.strict.deepStrictEqual(r.message.includes('Received'), false)
+        assert.strict.deepStrictEqual(r.message.includes(`'args[2]'`), true)
+    })
+
+    it(`should fall back to UNKNOWN when code is missing and to code when message is empty`, function() {
+        //P01c、P01e
+        let r1 = execSpawnError(new Error('spawn x'))
+        let r2 = execSpawnError(mkErr({ message: '', code: 'EPERM', errno: -4048 }))
+        assert.strict.deepStrictEqual([r1, r2], [{ code: 'UNKNOWN', message: 'spawn x' }, { code: 'EPERM', message: 'EPERM' }])
+    })
+
+    it(`should not throw for non-object input or throwing getters`, function() {
+        //P01d: 任何輸入皆不拋錯
+        let px = new Proxy({}, {
+            get() {
+                throw new Error('boom')
+            },
+        })
+        let rs = []
+        assert.doesNotThrow(() => {
+            for (let v of [undefined, null, 'str', 123, {}, px]) {
+                rs.push(execSpawnError(v))
+            }
+        })
+        assert.strict.deepStrictEqual(rs.map((r) => [typeof r.code, typeof r.message, r.code]), [
+            ['string', 'string', 'UNKNOWN'],
+            ['string', 'string', 'UNKNOWN'],
+            ['string', 'string', 'UNKNOWN'],
+            ['string', 'string', 'UNKNOWN'],
+            ['string', 'string', 'UNKNOWN'],
+            ['string', 'string', 'UNKNOWN'],
+        ])
+    })
+
+})

package/test/alive.test.mjs

@@ -1,4 +1,5 @@
 import assert from 'assert'
+import { spawnSync } from 'child_process'
 import alive from '../src/alive.mjs'
 
 
@@ -65,4 +66,204 @@ describe(`alive`, function() {
         assert.strict.deepStrictEqual(JSON.stringify(ms), r1)
     })
 
+    function test2() {
+        return new Promise((resolve, reject) => {
+            let ms = []
+
+            let oAL = alive({ timeAlive: 1500 })
+
+            oAL.on('message', function({ eventName, key }) {
+                ms.push(eventName + '|' + key)
+            })
+
+            oAL.trigger('a', { data: 123 })
+
+            setTimeout(() => {
+                oAL.trigger('b', { data: '34.56' })
+                let r = oAL.clear() //b剛trigger尚未發出enter, 故只回傳a, 且b之enter不再發出
+                ms.push('clear|' + r.map((v) => v.key).join(','))
+            }, 500)
+
+            setTimeout(() => {
+                resolve(ms)
+            }, 2500)
+
+        })
+    }
+    let r2 = '["enter|a","clear|a"]'
+    it(`should return '${r2}' when run test2'`, async function() {
+        let ms = await test2()
+        assert.strict.deepStrictEqual(JSON.stringify(ms), r2)
+    })
+
+    describe(`key`, function() {
+
+        let sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+        //trigger之key為任意非空字串, 每個key皆須於首次trigger時enter、逾時leave、存活期間列於get
+        //__proto__與Object原型之屬性名(constructor、toString等)亦同, 不得被誤判為已存在或改掉佇列之原型
+        let keys = ['__proto__', 'data', 'time', 'constructor', 'toString', 'hasOwnProperty', 'valueOf', 'isPrototypeOf', '__defineGetter__']
+
+        it(`should treat __proto__ and names on Object.prototype as ordinary keys`, async function() {
+            let ms = []
+            let o = alive({ timeAlive: 100, timeDetect: 20 })
+            o.on('message', (m) => ms.push(m.eventName + '|' + m.key))
+            for (let k of keys) {
+                o.trigger(k, { k })
+            }
+            await sleep(30)
+            assert.strict.deepStrictEqual(o.get(), keys.map((k) => ({ key: k, data: { k } })))
+            await sleep(300)
+            assert.strict.deepStrictEqual(ms, [...keys.map((k) => 'enter|' + k), ...keys.map((k) => 'leave|' + k)])
+            assert.strict.deepStrictEqual(o.get(), [])
+        })
+
+        it(`should return __proto__ and names on Object.prototype from clear`, async function() {
+            let o = alive({ timeAlive: 300 })
+            o.trigger('__proto__', 1)
+            o.trigger('constructor', 2)
+            await sleep(30)
+            assert.strict.deepStrictEqual(o.clear(), [{ key: '__proto__', data: 1 }, { key: 'constructor', data: 2 }])
+        })
+
+    })
+
+    describe(`clear`, function() {
+
+        let sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+        let create = (opt) => {
+            let ms = []
+            let errs = []
+            let o = alive(opt)
+            o.on('error', (e) => errs.push(e))
+            o.on('message', (m) => ms.push(m.eventName + '|' + m.key))
+            return { o, ms, errs }
+        }
+
+        it(`should return entered units, emit nothing afterwards and get [] (two units entered then clear)`, async function() {
+            let { o, ms } = create({ timeAlive: 300 })
+            o.trigger('a', { x: 1 })
+            o.trigger('b', { x: 2 })
+            await sleep(30)
+            let r = o.clear()
+            assert.strict.deepStrictEqual(r, [{ key: 'a', data: { x: 1 } }, { key: 'b', data: { x: 2 } }])
+            await sleep(500) //逾timeAlive仍不得發leave
+            assert.strict.deepStrictEqual(ms, ['enter|a', 'enter|b'])
+            assert.strict.deepStrictEqual(o.get(), [])
+        })
+
+        it(`should return [] and cancel the enter when cleared right after trigger`, async function() {
+            let { o, ms } = create({ timeAlive: 300 })
+            o.trigger('a', 1)
+            let r = o.clear()
+            await sleep(400)
+            assert.strict.deepStrictEqual(r, [])
+            assert.strict.deepStrictEqual(ms, [])
+        })
+
+        it(`should return only units whose enter was emitted`, async function() {
+            let { o, ms } = create({ timeAlive: 300 })
+            o.trigger('a', 1)
+            await sleep(30)
+            o.trigger('b', 2)
+            let r = o.clear()
+            await sleep(400)
+            assert.strict.deepStrictEqual(r, [{ key: 'a', data: 1 }])
+            assert.strict.deepStrictEqual(ms, ['enter|a'])
+        })
+
+        it(`should not return a unit that left and was triggered again but not yet re-entered`, async function() {
+            let { o, ms } = create({ timeAlive: 100, timeDetect: 20 })
+            o.trigger('a', 1)
+            await sleep(300) //a已enter且已leave
+            o.trigger('a', 2)
+            let r = o.clear()
+            await sleep(100)
+            assert.strict.deepStrictEqual(r, [])
+            assert.strict.deepStrictEqual(ms, ['enter|a', 'leave|a'])
+        })
+
+        it(`should not throw and return [] when called repeatedly or before any trigger`, function() {
+            let o = alive()
+            assert.strict.deepStrictEqual(o.clear(), [])
+            assert.strict.deepStrictEqual(o.clear(), [])
+        })
+
+        it(`should ignore trigger after clear`, async function() {
+            let { o, ms } = create({ timeAlive: 300 })
+            o.trigger('a', 1)
+            await sleep(30)
+            o.clear()
+            o.trigger('b', 2)
+            o.trigger('a', 3)
+            await sleep(400)
+            assert.strict.deepStrictEqual(ms, ['enter|a'])
+            assert.strict.deepStrictEqual(o.get(), [])
+            assert.strict.deepStrictEqual(o.clear(), [])
+        })
+
+        it(`should return the unit being dispatched and stop pending enters when cleared in an enter listener`, async function() {
+            let { o, ms, errs } = create({ timeAlive: 300 })
+            let rc = null
+            o.on('message', (m) => {
+                if (m.key === 'a' && rc === null) {
+                    rc = o.clear()
+                }
+            })
+            o.trigger('a', 1)
+            o.trigger('b', 2)
+            await sleep(400)
+            assert.strict.deepStrictEqual(rc, [{ key: 'a', data: 1 }])
+            assert.strict.deepStrictEqual(ms, ['enter|a'])
+            assert.strict.deepStrictEqual(errs, [])
+        })
+
+        it(`should stop the eviction round without throwing when cleared in a leave listener`, async function() {
+            //三單元同一輪逾時, 第一則leave中clear: 其餘二單元不再發leave且由clear回傳; 未防護時同輪下一單元會讀到已清空之佇列而拋錯
+            let { o, ms, errs } = create({ timeAlive: 100, timeDetect: 20 })
+            let rc = null
+            o.on('message', (m) => {
+                if (m.eventName === 'leave' && rc === null) {
+                    rc = o.clear()
+                }
+            })
+            o.trigger('a', 1)
+            o.trigger('b', 2)
+            o.trigger('c', 3)
+            await sleep(400)
+            assert.strict.deepStrictEqual(ms, ['enter|a', 'enter|b', 'enter|c', 'leave|a'])
+            assert.strict.deepStrictEqual(rc, [{ key: 'b', data: 2 }, { key: 'c', data: 3 }])
+            assert.strict.deepStrictEqual(errs, [])
+        })
+
+        it(`should leave no active timer so the process exits at once (child process)`, function() {
+            //於呼叫clear之計時器回呼結束後(setImmediate)才查資源, 回呼內該計時器自身仍會列出
+            let url = new URL('../src/alive.mjs', import.meta.url).href
+            let code = `
+                import alive from '${url}'
+                let t0 = Date.now()
+                let o = alive()
+                o.trigger('a', 1)
+                o.trigger('b', 2)
+                setTimeout(() => {
+                    let r = o.clear()
+                    setImmediate(() => {
+                        let res = process.getActiveResourcesInfo().filter((x) => x !== 'TTYWrap' && x !== 'Immediate')
+                        process.on('exit', () => {
+                            console.log(JSON.stringify({ r, res, ms: Date.now() - t0 }))
+                        })
+                    })
+                }, 100)
+            `
+            let p = spawnSync(process.execPath, ['--input-type=module', '-e', code], { encoding: 'utf8', timeout: 20000 })
+            assert.strict.deepStrictEqual(p.status, 0, p.stderr)
+            let o = JSON.parse(p.stdout.trim())
+            assert.strict.deepStrictEqual(o.r, [{ key: 'a', data: 1 }, { key: 'b', data: 2 }])
+            assert.strict.deepStrictEqual(o.res, [])
+            assert.strict.deepStrictEqual(o.ms < 2000, true, `exit after ${o.ms}ms`) //未clear時須逾timeAlive(預設10000)才結束
+        })
+
+    })
+
 })

package/test/cache.test.mjs

@@ -706,4 +706,30 @@ describe(`cache`, function() {
         assert.strict.deepStrictEqual(r, { defIsolated: true, getFalseSame: true, setFalseSame: true, overrideCloned: true, invalidUseSet: true, waitTrueIsolated: true, waitFalseSame: true, proxySame: true })
     })
 
+    //key為任意字串, __proto__與Object原型之屬性名(constructor、toString等)亦為一般key: 未set視為無效key、不得寫到原型上之物件, set後可取回
+    it(`should treat __proto__ and names on Object.prototype as ordinary keys`, async function() {
+        let had = Object.prototype.hasOwnProperty.call(Object, 'value')
+        try {
+            let oc = cache()
+            for (let k of ['__proto__', 'constructor', 'toString', 'hasOwnProperty', 'valueOf']) {
+                assert.strict.deepStrictEqual(await oc.get(k), null, `get ${k} before set`)
+            }
+            oc.update('constructor', 5) //未set之key不得寫入, 一般物件時會寫到Object本身
+            oc.clear('constructor')
+            assert.strict.deepStrictEqual(Object.prototype.hasOwnProperty.call(Object, 'value'), had)
+            oc.set('constructor', { fun: async () => 1 })
+            oc.set('__proto__', { fun: async () => 2 })
+            assert.strict.deepStrictEqual(await oc.get('constructor'), 1)
+            assert.strict.deepStrictEqual(await oc.get('__proto__'), 2)
+            assert.strict.deepStrictEqual(await oc.get('needExec'), null) //set __proto__不得使未set之key被視為存在
+            oc.remove('constructor')
+            assert.strict.deepStrictEqual(await oc.get('constructor'), null)
+        }
+        finally {
+            if (!had) {
+                delete Object.value //修正前之版本會寫入Object.value, 測試後還原以免影響同檔其他測試
+            }
+        }
+    })
+
 })

package/test/cacheSt.test.mjs

@@ -256,4 +256,44 @@ describe(`cacheSt`, function() {
         assert.strict.deepStrictEqual(ms, ms9)
     })
 
+    //key為任意字串, __proto__與Object原型之屬性名(constructor、toString等)亦為一般key: 未set不存在、set後可取回、不影響其他key
+    it(`should treat __proto__ and names on Object.prototype as ordinary keys`, async function() {
+        let cs = cacheSt({ timeDetect: 1000 })
+        try {
+            let names = ['__proto__', 'constructor', 'toString', 'hasOwnProperty', 'valueOf']
+            for (let k of names) {
+                assert.strict.deepStrictEqual(await cs.check(k), false, `check ${k} before set`)
+                assert.strict.deepStrictEqual(await cs.get(k), null, `get ${k} before set`)
+            }
+            assert.strict.deepStrictEqual(cs.checkWithSet('toString'), true)
+            assert.strict.deepStrictEqual(await cs.check('toString'), true)
+            await cs.set('__proto__', 'v')
+            assert.strict.deepStrictEqual(await cs.get('__proto__'), 'v')
+            assert.strict.deepStrictEqual(await cs.check('value'), false) //set __proto__不得使未set之key被視為存在
+            assert.strict.deepStrictEqual(await cs.check('time'), false)
+            await cs.set('constructor', 1)
+            assert.strict.deepStrictEqual(await cs.get('constructor'), 1)
+            await cs.del('constructor')
+            assert.strict.deepStrictEqual(await cs.check('constructor'), false)
+            await cs.del('__proto__')
+            assert.strict.deepStrictEqual(await cs.check('__proto__'), false)
+        }
+        finally {
+            cs.clear()
+        }
+    })
+
+    it(`should expire __proto__ like other keys`, async function() {
+        let cs = cacheSt({ timeExpire: 100, timeDetect: 50 })
+        try {
+            await cs.set('__proto__', 1)
+            assert.strict.deepStrictEqual(await cs.check('__proto__'), true)
+            await delay(300)
+            assert.strict.deepStrictEqual(await cs.check('__proto__'), false)
+        }
+        finally {
+            cs.clear()
+        }
+    })
+
 })