w-orm-lmdb 1.0.16 → 1.0.18

package/docs/WOrmLmdb.html

@@ -74,13 +74,27 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>操作資料庫(LMDB)</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>操作資料庫(LMDB)</p>
+<p>回傳物件為EventEmitter，除各操作函數外另發出change與error兩事件，供呼叫端於單一處集中觀察資料異動與失敗。
+事件僅為附加通知，其所送出之資訊皆另有正規管道(操作結果經resolve、整批性錯誤經reject、逐筆失敗經該筆之err欄位)，
+故不監聽亦能取得完整資訊，且監聽與否不改變任何操作之回傳值。</p>
+<p>change事件，參數為(mode, data, res)，於資料實際異動成功後發出：
+mode為操作別字串，可為'insert'、'save'、'del'、'delAll'；save內若逐筆走自動插入則該筆另發出mode為'insert'之事件。
+data為本次操作之輸入數據，delAll固定為null。
+res為本次操作之回傳結果。
+逐筆函數以整批為單位發出一次而不逐筆發出，select與selectByPk不發出本事件。</p>
+<p>error事件，參數為(mode, data, err)，於操作發生錯誤時發出：
+mode為操作別字串，可為'select'、'selectByPk'、'insert'、'save'、'del'、'delAll'。
+data為本次操作之輸入數據，無輸入數據者為null。
+err為錯誤訊息字串，內容與正規管道所送出者一致。
+整批性錯誤於reject之前發出；逐筆失敗於該筆結果定案後發出，每筆一次。
+註: 逐筆失敗時整批仍resolve，故收到本事件不表示該次呼叫失敗；正常結果(如查無數據、主鍵未命中、全數已存在)不發出本事件。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line34">line 34</a>
+        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line52">line 52</a>
     </li></ul></dd>
     
 
@@ -376,6 +390,46 @@
         </tr>
 
     
+
+        <tr>
+            
+                <td class="name"><code>autoGenPk</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Boolean</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>true</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入insert與save於數據未帶有效主鍵(本套件為id欄位)時是否自動產生主鍵值，預設true；給false代表主鍵改由呼叫端自備，套件不產生亦不檢查其唯一性與格式，未帶有效主鍵者將reject</p></td>
+        </tr>
+
+    
     </tbody>
 </table>
 
@@ -469,7 +523,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line562">line 562</a>
+        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line620">line 620</a>
     </li></ul></dd>
     
 
@@ -630,7 +684,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line686">line 686</a>
+        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line751">line 751</a>
     </li></ul></dd>
     
 
@@ -808,7 +862,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line249">line 249</a>
+        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line325">line 325</a>
     </li></ul></dd>
     
 
@@ -969,7 +1023,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line352">line 352</a>
+        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line419">line 419</a>
     </li></ul></dd>
     
 
@@ -1256,7 +1310,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line146">line 146</a>
+        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line214">line 214</a>
     </li></ul></dd>
     
 
@@ -1435,7 +1489,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line201">line 201</a>
+        <a href="WOrmLmdb.mjs.html">WOrmLmdb.mjs</a>, <a href="WOrmLmdb.mjs.html#line273">line 273</a>
     </li></ul></dd>
     
 
@@ -1592,7 +1646,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 16 2026 23:35:59 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 08:38:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WOrmLmdb.mjs.html

@@ -70,12 +70,30 @@ import waitFun from 'wsemi/src/waitFun.mjs'
 /**
  * 操作資料庫(LMDB)
  *
+ * 回傳物件為EventEmitter，除各操作函數外另發出change與error兩事件，供呼叫端於單一處集中觀察資料異動與失敗。
+ * 事件僅為附加通知，其所送出之資訊皆另有正規管道(操作結果經resolve、整批性錯誤經reject、逐筆失敗經該筆之err欄位)，
+ * 故不監聽亦能取得完整資訊，且監聽與否不改變任何操作之回傳值。
+ *
+ * change事件，參數為(mode, data, res)，於資料實際異動成功後發出：
+ * mode為操作別字串，可為'insert'、'save'、'del'、'delAll'；save內若逐筆走自動插入則該筆另發出mode為'insert'之事件。
+ * data為本次操作之輸入數據，delAll固定為null。
+ * res為本次操作之回傳結果。
+ * 逐筆函數以整批為單位發出一次而不逐筆發出，select與selectByPk不發出本事件。
+ *
+ * error事件，參數為(mode, data, err)，於操作發生錯誤時發出：
+ * mode為操作別字串，可為'select'、'selectByPk'、'insert'、'save'、'del'、'delAll'。
+ * data為本次操作之輸入數據，無輸入數據者為null。
+ * err為錯誤訊息字串，內容與正規管道所送出者一致。
+ * 整批性錯誤於reject之前發出；逐筆失敗於該筆結果定案後發出，每筆一次。
+ * 註: 逐筆失敗時整批仍resolve，故收到本事件不表示該次呼叫失敗；正常結果(如查無數據、主鍵未命中、全數已存在)不發出本事件。
+ *
  * @class
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {String} [opt.url='_db'] 輸入資料庫用資料夾字串，預設'_db'
  * @param {String} [opt.db='worm'] 輸入使用資料庫名稱字串，預設'worm'
  * @param {String} [opt.cl='test'] 輸入使用資料表名稱字串，預設'test'
  * @param {Boolean} [opt.useCache=false] 輸入是否使用select快取，適用於單程序操作，預設false
+ * @param {Boolean} [opt.autoGenPk=true] 輸入insert與save於數據未帶有效主鍵(本套件為id欄位)時是否自動產生主鍵值，預設true；給false代表主鍵改由呼叫端自備，套件不產生亦不檢查其唯一性與格式，未帶有效主鍵者將reject
  * @returns {Object} 回傳操作資料庫物件，各事件功能詳見說明
  */
 function WOrmLmdb(opt = {}) {
@@ -107,6 +125,13 @@ function WOrmLmdb(opt = {}) {
         useCache = false
     }
 
+    //autoGenPk, 主鍵由誰產生為整個資料表之政策, 故為建構層設定, 不可於insert與save之option逐次覆寫,
+    //否則同一資料表將混入兩種來源之主鍵而難以追溯
+    let autoGenPk = get(opt, 'autoGenPk')
+    if (!isbol(autoGenPk)) {
+        autoGenPk = true
+    }
+
     //storage
     let storage = `${url}/${db}/${cl}`
     // console.log('storage',storage)
@@ -157,7 +182,30 @@ function WOrmLmdb(opt = {}) {
         })
     }
 
-    //getErrMsg, 取錯誤訊息字串, 供逐筆結果之err欄位使用
+    //emitChange, 資料實際異動成功後發出, 事件僅為附加通知不承擔回傳義務
+    //一律包try/catch, 令訂閱函數自身拋錯不影響本次操作之結果
+    let emitChange = (mode, data, res) => {
+        try {
+            ee.emit('change', mode, data, res)
+        }
+        catch (err) {
+            console.log(err)
+        }
+    }
+
+    //emitError, 操作發生錯誤時發出, 錯誤訊息一律轉為字串
+    //此try/catch除攔訂閱函數之例外外另有必要: Node之EventEmitter於'error'無監聽者時會將錯誤直接拋出,
+    //若不攔則同一次操作會因呼叫端有無註冊監聽而走向不同結果
+    let emitError = (mode, data, err) => {
+        try {
+            ee.emit('error', mode, data, getErrMsg(err))
+        }
+        catch (errEmit) {
+            console.log(errEmit)
+        }
+    }
+
+    //getErrMsg, 取錯誤訊息字串, 供逐筆結果之err欄位與error事件使用
     let getErrMsg = (err) => {
         let m = get(err, 'message')
         if (isestr(m)) {
@@ -166,6 +214,26 @@ function WOrmLmdb(opt = {}) {
         return String(err)
     }
 
+    //procPk, 依autoGenPk處理各數據之主鍵, 供insert與save共用
+    //autoGenPk為true時補值; 為false時不補值, 未帶有效主鍵者屬呼叫端未履行契約, 拋出為整批性錯誤,
+    //且檢查於任何寫入之前完成, 故不會有部份筆數已寫入而整批失敗之情形
+    let procPk = (data, fnName) => {
+        if (autoGenPk) {
+            return map(data, function(v) {
+                if (!isestr(v.id)) {
+                    v.id = genIDSeq()
+                }
+                return v
+            })
+        }
+        each(data, function(v, k) {
+            if (!isestr(get(v, 'id'))) {
+                throw new Error(`can not ${fnName} by data[${k}] without valid id when autoGenPk is false`)
+            }
+        })
+        return data
+    }
+
     //getValue
     let getValue = async (key) => {
         let value = null
@@ -231,6 +299,10 @@ function WOrmLmdb(opt = {}) {
 
         //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('select', null, res)
+
             return Promise.reject(res)
         }
 
@@ -280,6 +352,10 @@ function WOrmLmdb(opt = {}) {
 
         //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('selectByPk', null, res)
+
             return Promise.reject(res)
         }
 
@@ -318,12 +394,7 @@ function WOrmLmdb(opt = {}) {
             }
 
             //check id
-            data = map(data, function(v) {
-                if (!isestr(v.id)) {
-                    v.id = genIDSeq()
-                }
-                return v
-            })
+            data = procPk(data, 'insert')
 
             //each
             //ifNoExists, 由LMDB於同一寫交易內原子完成[檢查v.id未存在]與[寫入], 併發時同一v.id僅有一次成功,
@@ -368,19 +439,15 @@ function WOrmLmdb(opt = {}) {
 
         //emit, 於change可能須使用select, 故須放在重設快取之後
         if (!isErr) {
-            try {
-
-                //emit
-                ee.emit('change', 'insert', data, res)
-
-            }
-            catch (err) {
-                console.log(err)
-            }
+            emitChange('insert', data, res)
         }
 
         //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('insert', data, res)
+
             return Promise.reject(res)
         }
 
@@ -420,12 +487,7 @@ function WOrmLmdb(opt = {}) {
             }
 
             //check id
-            data = map(data, function(v) {
-                if (!isestr(v.id)) {
-                    v.id = genIDSeq()
-                }
-                return v
-            })
+            data = procPk(data, 'save')
 
             //pmSeries
             res = await pmSeries(data, async(v) => {
@@ -554,16 +616,15 @@ function WOrmLmdb(opt = {}) {
                     //update, 不能保證插入多少, 一律重設快取
                     _cache = null
 
-                    try {
-
-                        //emit
-                        ee.emit('change', 'insert', [v], rest)
+                    //emit
+                    emitChange('insert', [v], rest)
 
-                    }
-                    catch (err) {
-                        console.log(err)
-                    }
+                }
 
+                //emit, 逐筆失敗於該筆結果定案後發出, 每筆一次
+                //此事件之發出不表示整批失敗, 整批仍resolve, 該筆以ok為0回報
+                if (rest.ok === 0) {
+                    emitError('save', [v], rest.err)
                 }
 
                 return rest
@@ -579,20 +640,17 @@ function WOrmLmdb(opt = {}) {
         _cache = null
 
         //emit, 於change可能須使用select, 故須放在重設快取之後
+        //逐筆失敗之error事件已於各筆定案時發出, 故必早於本整批change
         if (!isErr) {
-            try {
-
-                //emit
-                ee.emit('change', 'save', data, res)
-
-            }
-            catch (err) {
-                console.log(err)
-            }
+            emitChange('save', data, res)
         }
 
         //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('save', data, res)
+
             return Promise.reject(res)
         }
 
@@ -641,38 +699,42 @@ function WOrmLmdb(opt = {}) {
                     if (!isestr(id)) {
                         //未給有效v.id視為該筆數據有問題而無法處理, 以ok為0並附err回報,
                         //與[已給v.id但查無數據]之ok為1有別, 二者須可由ok分辨
-                        return {
+                        //註: 此處不可直接return, 否則會跳過本回調末尾之error事件發出
+                        rest = {
                             n: 0,
                             nDeleted: 0,
                             ok: 0,
                             err: `can not delete by invalid id[${id}]`,
                         }
                     }
+                    else {
 
-                    //查找資料表內v.id
-                    let vv = await getValue(id) //不會有catch
+                        //查找資料表內v.id
+                        let vv = await getValue(id) //不會有catch
 
-                    //check
-                    if (iseobj(vv)) {
-                        //已存在v.id則須刪除
+                        //check
+                        if (iseobj(vv)) {
+                            //已存在v.id則須刪除
 
-                        //del
-                        await client.del(id)
+                            //del
+                            await client.del(id)
+
+                            //rest
+                            rest = {
+                                n: 1,
+                                nDeleted: 1,
+                                ok: 1,
+                            }
 
-                        //rest
-                        rest = {
-                            n: 1,
-                            nDeleted: 1,
-                            ok: 1,
                         }
+                        else {
+                            //不存在v.id則不刪除, 未命中故n為0
+                            rest = {
+                                n: 0,
+                                nDeleted: 0,
+                                ok: 1,
+                            }
 
-                    }
-                    else {
-                        //不存在v.id則不刪除, 未命中故n為0
-                        rest = {
-                            n: 0,
-                            nDeleted: 0,
-                            ok: 1,
                         }
 
                     }
@@ -690,6 +752,12 @@ function WOrmLmdb(opt = {}) {
 
                 }
 
+                //emit, 逐筆失敗於該筆結果定案後發出, 每筆一次
+                //此事件之發出不表示整批失敗, 整批仍resolve, 該筆以ok為0回報
+                if (rest.ok === 0) {
+                    emitError('del', [v], rest.err)
+                }
+
                 return rest
             })
 
@@ -703,20 +771,17 @@ function WOrmLmdb(opt = {}) {
         _cache = null
 
         //emit, 於change可能須使用select, 故須放在重設快取之後
+        //逐筆失敗之error事件已於各筆定案時發出, 故必早於本整批change
         if (!isErr) {
-            try {
-
-                //emit
-                ee.emit('change', 'del', data, res)
-
-            }
-            catch (err) {
-                console.log(err)
-            }
+            emitChange('del', data, res)
         }
 
         //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('del', data, res)
+
             return Promise.reject(res)
         }
 
@@ -818,19 +883,15 @@ function WOrmLmdb(opt = {}) {
 
         //emit, 於change可能須使用select, 故須放在重設快取之後
         if (!isErr) {
-            try {
-
-                //emit
-                ee.emit('change', 'delAll', null, res)
-
-            }
-            catch (err) {
-                console.log(err)
-            }
+            emitChange('delAll', null, res)
         }
 
         //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('delAll', null, res)
+
             return Promise.reject(res)
         }
 
@@ -872,7 +933,7 @@ export default WOrmLmdb
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 16 2026 23:35:59 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 08:38:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 16 2026 23:35:59 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 08:38:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-basic.mjs

@@ -62,6 +62,9 @@ async function test() {
     wo.on('change', function(mode, data, res) {
         console.log('change', mode)
     })
+    wo.on('error', function(mode, data, err) {
+        console.log('error', mode, err)
+    })
 
     //delAll
     await wo.delAll()
@@ -145,6 +148,15 @@ async function test() {
             console.log('del catch', msg)
         })
 
+    //del by data without id, 該筆無法處理故ok為0並附err, 整批仍resolve且另發出error事件
+    await wo.del({ name: 'no-id' })
+        .then(function(msg) {
+            console.log('del by data without id then', msg)
+        })
+        .catch(function(msg) {
+            console.log('del by data without id catch', msg)
+        })
+
 }
 test()
 // change delAll
@@ -193,6 +205,9 @@ test()
 // save then [ { n: 1, nInserted: 0, nModified: 1, ok: 1 } ]
 // change del
 // del then [ { n: 1, nDeleted: 1, ok: 1 } ]
+// 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[]' } ]
 
 
 //node g-basic.mjs

package/package.json

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