w-orm-lmdb 1.0.18 → 1.0.20

package/docs/WOrmLmdb.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmLmdb.html">WOrmLmdb</a><ul class='methods'><li data-type='method'><a href="WOrmLmdb.html#.del">del</a></li><li data-type='method'><a href="WOrmLmdb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmLmdb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmLmdb.html#.save">save</a></li><li data-type='method'><a href="WOrmLmdb.html#.select">select</a></li><li data-type='method'><a href="WOrmLmdb.html#.selectByPk">selectByPk</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmLmdb.html">WOrmLmdb</a><ul class='methods'><li data-type='method'><a href="WOrmLmdb.html#.del">del</a></li><li data-type='method'><a href="WOrmLmdb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmLmdb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmLmdb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmLmdb.html#.save">save</a></li><li data-type='method'><a href="WOrmLmdb.html#.select">select</a></li><li data-type='method'><a href="WOrmLmdb.html#.selectByPk">selectByPk</a></li></ul></li></ul>
     
 </nav>
 
@@ -45,7 +45,7 @@
     
     <section>
         <article>
-            <pre class="prettyprint source linenums"><code>import { open } from 'lmdb'
+            <pre class="prettyprint source linenums"><code>import { open, ABORT } from 'lmdb'
 // import mingo from 'mingo' //mingo內未更新import寫法, 會導致ERR_UNSUPPORTED_DIR_IMPORT, 故須改用require引入使用
 import mingo from './reqMingo.js'
 import size from 'lodash-es/size.js'
@@ -75,13 +75,13 @@ import waitFun from 'wsemi/src/waitFun.mjs'
  * 故不監聽亦能取得完整資訊，且監聽與否不改變任何操作之回傳值。
  *
  * change事件，參數為(mode, data, res)，於資料實際異動成功後發出：
- * mode為操作別字串，可為'insert'、'save'、'del'、'delAll'；save內若逐筆走自動插入則該筆另發出mode為'insert'之事件。
+ * mode為操作別字串，可為'insert'、'insertBulk'、'save'、'del'、'delAll'；save內若逐筆走自動插入則該筆另發出mode為'insert'之事件。
  * data為本次操作之輸入數據，delAll固定為null。
  * res為本次操作之回傳結果。
  * 逐筆函數以整批為單位發出一次而不逐筆發出，select與selectByPk不發出本事件。
  *
  * error事件，參數為(mode, data, err)，於操作發生錯誤時發出：
- * mode為操作別字串，可為'select'、'selectByPk'、'insert'、'save'、'del'、'delAll'。
+ * mode為操作別字串，可為'select'、'selectByPk'、'insert'、'insertBulk'、'save'、'del'、'delAll'。
  * data為本次操作之輸入數據，無輸入數據者為null。
  * err為錯誤訊息字串，內容與正規管道所送出者一致。
  * 整批性錯誤於reject之前發出；逐筆失敗於該筆結果定案後發出，每筆一次。
@@ -173,13 +173,25 @@ function WOrmLmdb(opt = {}) {
     }
 
     //waitOpen, 等待client開啟, 因getRange與get於client關閉時會拋錯
+    //closed為終態: LMDB env一旦關閉不會自行回到open, 續等必然逾時, 故直接拋出而非空轉至逾時
+    //各函數入口已有procClosed守門, 此處之終態判斷為縱深防禦, 攔[操作進行中被close]之競態
+    //等待參數收斂: 開啟中為毫秒級過渡, 50次x200ms=10秒已極寬裕, 不使非終態之等待拖至waitFun預設之200秒
     let waitOpen = async () => {
+        if (client.status === 'closed') {
+            throw new Error('client is closed, instance can not be used after close()')
+        }
         await waitFun(() => {
-            if (client.status === 'closed') {
-                console.log(`client.status[${client.status}], level is closed`)
-            }
             return client.status === 'open'
-        })
+        }, { attemptNum: 50, timeInterval: 200 })
+    }
+
+    //procClosed, 各函數入口之終態守門: close()後再操作屬整批性錯誤, 立即reject令誤用當場可見
+    //不可靜默回正常空值(如null或未命中), 否則[已關閉]與[查無資料]同形,
+    //去重類呼叫端將把每筆判為未存在而fail-open, 整批重送下游昂貴動作
+    let procClosed = (mode, data) => {
+        let msg = `can not ${mode} by closed client, instance can not be used after close()`
+        emitError(mode, data, msg)
+        return Promise.reject(new Error(msg))
     }
 
     //emitChange, 資料實際異動成功後發出, 事件僅為附加通知不承擔回傳義務
@@ -259,6 +271,11 @@ function WOrmLmdb(opt = {}) {
      * @returns {Promise} 回傳Promise，resolve回傳數據，reject回傳錯誤訊息
      */
     async function select(find = {}) {
+
+        //check client, closed為終態, 於任何檢查與寫入之前先行攔下(T4: 實例已關閉屬整批性錯誤)
+        if (client.status === 'closed') {
+            return procClosed('select', null)
+        }
         let isErr = false
         let res = null
 
@@ -318,6 +335,11 @@ function WOrmLmdb(opt = {}) {
      * @returns {Promise} 回傳Promise，resolve回傳數據物件，若無此主鍵則回傳null，reject回傳錯誤訊息
      */
     async function selectByPk(pk) {
+
+        //check client, closed為終態, 於任何檢查與寫入之前先行攔下(T4: 實例已關閉屬整批性錯誤)
+        if (client.status === 'closed') {
+            return procClosed('selectByPk', null)
+        }
         let isErr = false
         let res = null
 
@@ -367,13 +389,30 @@ function WOrmLmdb(opt = {}) {
      *
      * @memberOf WOrmLmdb
      * @param {Object|Array} data 輸入數據物件或陣列
-     * @returns {Promise} 回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，n為輸入筆數、nInserted為實際插入筆數，reject回傳錯誤訊息
+     * @param {Object} [option={}] 輸入設定物件，預設為{}
+     * @param {Boolean} [option.returnList=false] 輸入是否改回傳逐筆結果布林值，預設false。給true時回傳與輸入等長保序之陣列，各筆為{n,nInserted,ok}，nInserted為1即該筆為新增；聚合計數只回答有幾筆是新的，逐筆結果方能回答是哪幾筆，供下游僅對新資料執行昂貴動作。回傳形式由呼叫點靜態決定，共用之結果處理程式碼不可跨不同取值之呼叫點混用
+     * @returns {Promise} 回傳Promise，resolve依returnList回傳插入結果：預設回傳聚合物件{n,nInserted,ok}，n為輸入筆數、nInserted為實際插入筆數；returnList為true時回傳逐筆陣列，各筆n恆為1(主鍵命中或經插入)、ok恆為1(insert之錯誤皆屬整批性而reject，不進逐筆)；reject回傳錯誤訊息
      */
-    async function insert(data) {
+    async function insert(data, option = {}) {
+
+        //check client, closed為終態, 於任何檢查與寫入之前先行攔下(T4: 實例已關閉屬整批性錯誤)
+        if (client.status === 'closed') {
+            return procClosed('insert', data)
+        }
         let isErr = false
 
+        //returnList
+        let returnList = get(option, 'returnList')
+        if (!isbol(returnList)) {
+            returnList = false
+        }
+
         //check
         if (!iseobj(data) &amp;&amp; !isearr(data)) {
+            if (returnList) {
+                //輸入無效, 對齊save與del之T5規定回傳空陣列
+                return []
+            }
             return {
                 n: 0,
                 nInserted: 0,
@@ -422,9 +461,122 @@ function WOrmLmdb(opt = {}) {
             })
 
             //res
+            if (returnList) {
+                //逐筆結果, 與輸入等長保序, 元素沿用逐筆結果之家族形狀(同save與del之元素)
+                //n恆為1(主鍵命中既有或經插入而產生), ok恆為1(insert之錯誤皆屬整批性而reject, 不進逐筆),
+                //資訊由nInserted承載, filter(v=>v.nInserted===1)之長度必等於聚合模式之nInserted
+                res = map(ltdone, function(done) {
+                    return {
+                        n: 1,
+                        nInserted: done ? 1 : 0,
+                        ok: 1,
+                    }
+                })
+            }
+            else {
+                res = {
+                    n: nAll,
+                    nInserted: nPush,
+                    ok: 1,
+                }
+            }
+
+        }
+        catch (err) {
+            isErr = true
+            res = err
+        }
+
+        //update, 不能保證插入多少, 一律重設快取
+        _cache = null
+
+        //emit, 於change可能須使用select, 故須放在重設快取之後
+        if (!isErr) {
+            emitChange('insert', data, res)
+        }
+
+        //check
+        if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('insert', data, res)
+
+            return Promise.reject(res)
+        }
+
+        return res
+    }
+
+    /**
+     * 批次插入數據，全批視為一個單位，全部插入成功或一筆都不寫入
+     * 註: 本函數非insert之加速版，兩者衝突政策不同。insert於主鍵已存在時跳過該筆而整批ok為1，
+     * 本函數則整批reject且不寫入任何一筆；同批含重複主鍵者亦視為衝突。確無衝突時兩者結果相同
+     * 註: 於本套件不會較insert快，因insert本即以Promise.all一次送出全部條件寫入而非逐筆await，
+     * 提供本函數係為與其他w-orm系列套件維持同一組函數，令呼叫端得於各套件間替換而不須改寫呼叫
+     *
+     * @memberOf WOrmLmdb
+     * @param {Object|Array} data 輸入數據物件或陣列
+     * @returns {Promise} 回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，n為輸入筆數、nInserted成功時恆等於n，任一筆主鍵已存在則reject回傳錯誤訊息
+     */
+    async function insertBulk(data) {
+
+        //check client, closed為終態, 於任何檢查與寫入之前先行攔下(T4: 實例已關閉屬整批性錯誤)
+        if (client.status === 'closed') {
+            return procClosed('insertBulk', data)
+        }
+        let isErr = false
+
+        //check
+        if (!iseobj(data) &amp;&amp; !isearr(data)) {
+            return {
+                n: 0,
+                nInserted: 0,
+                ok: 1,
+            }
+        }
+
+        //cloneDeep, 與外部數據脫勾
+        data = cloneDeep(data)
+
+        //res
+        let res = null
+        try {
+
+            //check
+            if (!isarr(data)) {
+                data = [data]
+            }
+
+            //check id
+            data = procPk(data, 'insertBulk')
+
+            //nAll
+            let nAll = size(data)
+
+            //childTransaction, 全有全無由交易回滾保證
+            //註: 非同步之client.transaction於中止時並不回滾, 實測其內之put仍會落盤, 故此處須用childTransaction
+            //註: 交易內之client.get讀得到同一交易稍早之put, 故同批含重複主鍵者亦會於此被偵測為衝突
+            //註: 存在與否採鍵層判定, 與insert之ifNoExists一致
+            let pkConflict = null
+            await client.childTransaction(() => {
+                for (let v of data) {
+                    if (client.get(v.id) !== undefined) {
+                        pkConflict = v.id
+                        return ABORT
+                    }
+                    client.put(v.id, v)
+                }
+            })
+
+            //check, 衝突則整批視為失敗, 交易已回滾故無任何寫入
+            if (isestr(pkConflict)) {
+                throw new Error(`can not insertBulk by existed id[${pkConflict}]`)
+            }
+
+            //res, 未衝突則全數插入, 故nInserted恆等於n
             res = {
                 n: nAll,
-                nInserted: nPush,
+                nInserted: nAll,
                 ok: 1,
             }
 
@@ -439,14 +591,14 @@ function WOrmLmdb(opt = {}) {
 
         //emit, 於change可能須使用select, 故須放在重設快取之後
         if (!isErr) {
-            emitChange('insert', data, res)
+            emitChange('insertBulk', data, res)
         }
 
         //check
         if (isErr) {
 
             //emit, 整批性錯誤須於reject之前發出
-            emitError('insert', data, res)
+            emitError('insertBulk', data, res)
 
             return Promise.reject(res)
         }
@@ -464,6 +616,11 @@ function WOrmLmdb(opt = {}) {
      * @returns {Promise} 回傳Promise，resolve回傳與輸入等長之儲存結果陣列，各筆為{n,nInserted,nModified,ok}，n為主鍵命中筆數，單筆失敗者ok為0並附err，reject回傳錯誤訊息
      */
     async function save(data, option = {}) {
+
+        //check client, closed為終態, 於任何檢查與寫入之前先行攔下(T4: 實例已關閉屬整批性錯誤)
+        if (client.status === 'closed') {
+            return procClosed('save', data)
+        }
         let isErr = false
 
         //check
@@ -665,6 +822,11 @@ function WOrmLmdb(opt = {}) {
      * @returns {Promise} 回傳Promise，resolve回傳與輸入等長之刪除結果陣列，各筆為{n,nDeleted,ok}，n為主鍵命中筆數，單筆失敗或未給有效id者ok為0並附err，reject回傳錯誤訊息
      */
     async function del(data) {
+
+        //check client, closed為終態, 於任何檢查與寫入之前先行攔下(T4: 實例已關閉屬整批性錯誤)
+        if (client.status === 'closed') {
+            return procClosed('del', data)
+        }
         let isErr = false
 
         //check
@@ -796,6 +958,11 @@ function WOrmLmdb(opt = {}) {
      * @returns {Promise} 回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，n與nDeleted同為實際刪除筆數，reject回傳錯誤訊息
      */
     async function delAll(find = {}) {
+
+        //check client, closed為終態, 於任何檢查與寫入之前先行攔下(T4: 實例已關閉屬整批性錯誤)
+        if (client.status === 'closed') {
+            return procClosed('delAll', null)
+        }
         let isErr = false
 
         //res
@@ -898,7 +1065,8 @@ function WOrmLmdb(opt = {}) {
         return res
     }
 
-    //close, 關閉內部LMDB env並釋放檔案鎖, close後該實例即報廢, 須重新new WOrmLmdb
+    //close, 關閉內部LMDB env並釋放檔案鎖, close後該實例即報廢, 須重新new WOrmLmdb,
+    //再呼叫任何操作函數將立即reject(訊息明示closed), 不與[查無資料]同形
     let close = async () => {
         if (client &amp;&amp; client.status !== 'closed') {
             await client.close() //lmdb root database之close(), 回傳Promise
@@ -909,6 +1077,7 @@ function WOrmLmdb(opt = {}) {
     ee.select = select
     ee.selectByPk = selectByPk
     ee.insert = insert
+    ee.insertBulk = insertBulk
     ee.save = save
     ee.del = del
     ee.delAll = delAll
@@ -933,7 +1102,7 @@ export default WOrmLmdb
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 17 2026 08:38:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 17 2026 17:58:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmLmdb.html">WOrmLmdb</a><ul class='methods'><li data-type='method'><a href="WOrmLmdb.html#.del">del</a></li><li data-type='method'><a href="WOrmLmdb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmLmdb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmLmdb.html#.save">save</a></li><li data-type='method'><a href="WOrmLmdb.html#.select">select</a></li><li data-type='method'><a href="WOrmLmdb.html#.selectByPk">selectByPk</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmLmdb.html">WOrmLmdb</a><ul class='methods'><li data-type='method'><a href="WOrmLmdb.html#.del">del</a></li><li data-type='method'><a href="WOrmLmdb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmLmdb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmLmdb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmLmdb.html#.save">save</a></li><li data-type='method'><a href="WOrmLmdb.html#.select">select</a></li><li data-type='method'><a href="WOrmLmdb.html#.selectByPk">selectByPk</a></li></ul></li></ul>
     
 </nav>
 
@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 17 2026 08:38:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 17 2026 17:58:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-basic.mjs

@@ -157,10 +157,44 @@ async function test() {
             console.log('del by data without id catch', msg)
         })
 
+    //insertBulk, 全批視為一個單位, 無衝突時nInserted恆等於n
+    await wo.insertBulk([{ id: 'id-bulk1', name: 'bulk1' }, { id: 'id-bulk2', name: 'bulk2' }])
+        .then(function(msg) {
+            console.log('insertBulk then', msg)
+        })
+        .catch(function(msg) {
+            console.log('insertBulk catch', msg)
+        })
+
+    //insertBulk by data with existed id, 非insert之加速版而係衝突政策不同
+    //insert於主鍵已存在時跳過該筆而整批ok為1, insertBulk則整批reject且不寫入任何一筆
+    await wo.insertBulk([{ id: 'id-bulk3', name: 'bulk3' }, { id: 'id-peter', name: 'conflict' }])
+        .then(function(msg) {
+            console.log('insertBulk by data with existed id then', msg)
+        })
+        .catch(function(msg) {
+            console.log('insertBulk by data with existed id catch', msg.toString())
+        })
+
+    //select all, 可見id-bulk3因整批reject而未寫入
+    let sb2 = await wo.select()
+    console.log('ids after insertBulk', _.map(_.sortBy(sb2, 'id'), 'id'))
+
+    //insert by returnList, 回傳與輸入等長保序之逐筆結果, nInserted為1即該筆為新增
+    //聚合計數只回答有幾筆是新的, 逐筆結果方能回答是哪幾筆, 供下游僅對新資料執行昂貴動作
+    let rl = await wo.insert([{ id: 'id-peter', name: 'dup' }, { id: 'id-new1', name: 'new1' }], { returnList: true })
+    console.log('insert by returnList', rl)
+
+    //filter, 以逐筆結果對位取出新增之數據
+    let fresh = [{ id: 'id-peter', name: 'dup' }, { id: 'id-new1', name: 'new1' }].filter(function(v, i) {
+        return rl[i].nInserted === 1
+    })
+    console.log('fresh by returnList', _.map(fresh, 'id'))
+
 }
 test()
 // change delAll
-// delAll then { n: 2, nDeleted: 2, ok: 1 }
+// delAll then { n: 5, nDeleted: 5, ok: 1 }
 // change insert
 // insert then { n: 3, nInserted: 3, ok: 1 }
 // change save
@@ -208,6 +242,14 @@ test()
 // error del can not delete by invalid id[]
 // change del
 // del by data without id then [ { n: 0, nDeleted: 0, ok: 0, err: 'can not delete by invalid id[]' } ]
+// change insertBulk
+// insertBulk then { n: 2, nInserted: 2, ok: 1 }
+// error insertBulk can not insertBulk by existed id[id-peter]
+// insertBulk by data with existed id catch Error: can not insertBulk by existed id[id-peter]
+// ids after insertBulk [ 'id-bulk1', 'id-bulk2', 'id-peter', 'id-rosemary' ]
+// change insert
+// insert by returnList [ { n: 1, nInserted: 0, ok: 1 }, { n: 1, nInserted: 1, ok: 1 } ]
+// fresh by returnList [ 'id-new1' ]
 
 
 //node g-basic.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-orm-lmdb",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "main": "dist/w-orm-lmdb.umd.js",
   "dependencies": {
     "lmdb": "^3.5.6",