w-orm-mongodb 1.1.39 → 1.1.41

package/docs/WOrmMongodb.mjs.html

@@ -45,8 +45,7 @@
     
     <section>
         <article>
-            <pre class="prettyprint source linenums"><code>import events from 'events'
-import mongodb from 'mongodb'
+            <pre class="prettyprint source linenums"><code>import mongodb from 'mongodb'
 import stream from 'stream'
 import cloneDeep from 'lodash-es/cloneDeep.js'
 import every from 'lodash-es/every.js'
@@ -54,8 +53,10 @@ import get from 'lodash-es/get.js'
 import map from 'lodash-es/map.js'
 import omit from 'lodash-es/omit.js'
 import size from 'lodash-es/size.js'
+import evem from 'wsemi/src/evem.mjs'
 import genPm from 'wsemi/src/genPm.mjs'
 import genID from 'wsemi/src/genID.mjs'
+import isbol from 'wsemi/src/isbol.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import isarr from 'wsemi/src/isarr.mjs'
 import isearr from 'wsemi/src/isearr.mjs'
@@ -67,14 +68,16 @@ import pmSeries from 'wsemi/src/pmSeries.mjs'
 /**
  * 操作資料庫(MongoDB)
  *
- * 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定。
- * id為無業務語義之識別碼，故insert與save於輸入未帶有效id時自動補值；del不補值。
+ * 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定。id為無業務語義之識別碼。
+ * opt.autoGenPk預設為true，insert、save與insertGfs於輸入未帶有效id時自動產生；del於任一設定下皆不補值。
+ * opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋出，且id之唯一性與格式皆由呼叫端自負。
  *
  * @class
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {String} [opt.url='mongodb://127.0.0.1:27017'] 輸入連接資料庫字串，預設'mongodb://127.0.0.1:27017'
  * @param {String} [opt.db='worm'] 輸入使用資料庫名稱字串，預設'worm'
  * @param {String} [opt.cl='test'] 輸入使用資料表名稱字串，預設'test'
+ * @param {Boolean} [opt.autoGenPk=true] 輸入是否於輸入未帶有效主鍵時自動產生主鍵值，預設true。為false時主鍵須由呼叫端自備，屬依賴注入之定位，主鍵之唯一性、格式與是否與既有資料衝突皆由呼叫端自負。本設定為建構層設定，不得於insert與save之option逐次覆寫
  * @returns {Object} 回傳操作資料庫物件，各事件功能詳見說明
  */
 function WOrmMongodb(opt = {}) {
@@ -92,6 +95,13 @@ function WOrmMongodb(opt = {}) {
     }
 
 
+    //autoGenPk, 預設開啟, 為false時主鍵一律由呼叫端自備, 套件不產生亦不補救
+    let autoGenPk = get(opt, 'autoGenPk')
+    if (!isbol(autoGenPk)) {
+        autoGenPk = true
+    }
+
+
     //_indexReady, 唯一索引只須建立一次, 以旗標記錄避免每次操作皆多一次round-trip
     let _indexReady = false
 
@@ -100,8 +110,9 @@ function WOrmMongodb(opt = {}) {
     let _indexGfsReady = false
 
 
-    //ee
-    let ee = new events.EventEmitter()
+    //ee, 採wsemi之evem(即eventemitter3), 其於'error'無監聽者時僅回傳false而不拋出,
+    //故本套件之操作行為不因呼叫端有無註冊監聽而改變; Node內建之EventEmitter具該拋出語義, 不可用
+    let ee = evem()
 
 
     //MongoClient
@@ -115,7 +126,7 @@ function WOrmMongodb(opt = {}) {
      * @param {Error|String} err 輸入錯誤物件或字串
      * @returns {String} 回傳錯誤訊息字串
      */
-    function genErrMsg(err) {
+    function getErrMsg(err) {
 
         //message
         let message = get(err, 'message')
@@ -146,6 +157,59 @@ function WOrmMongodb(opt = {}) {
     }
 
 
+    /**
+     * 發出error事件，操作發生錯誤時發出，錯誤訊息一律轉為字串
+     * 註: 事件僅為附加通知，所送出之資訊必另有正規管道——整批性錯誤經Promise.reject，逐筆失敗經該筆之err欄位
+     * 註: 訂閱函數拋錯不得影響本次操作之結果，故另包try並自行吞掉
+     * 註: 正常結果不得發出本事件，如insert全數已存在、save合併後內容相同、del主鍵未命中、selectByPk查無數據
+     *
+     * @ignore
+     * @param {String} mode 輸入操作別字串
+     * @param {Array|null} data 輸入本次操作之數據
+     * @param {Error|String} err 輸入錯誤物件或字串
+     * @returns {undefined} 無回傳值
+     */
+    function emitError(mode, data, err) {
+        try {
+            ee.emit('error', mode, data, getErrMsg(err))
+        }
+        catch (errEmit) {
+            console.log(errEmit)
+        }
+    }
+
+
+    /**
+     * 檢查並補齊單筆數據之主鍵
+     * autoGenPk為true時未帶有效id者自動產生，為false時往外拋
+     * 註: 未帶有效id屬呼叫端未履行契約而非某一筆資料本身之問題，故為整批性錯誤而不降級為該筆ok為0，
+     * 若降級為逐筆結果，呼叫端易於整批resolve之下漏看，使[忘了給id]靜默變成[少寫了幾筆]
+     * 註: 本函數須於任何寫入之前一次對全部數據完成，令拋錯時同批之有效筆數亦不會被寫入
+     *
+     * @ignore
+     * @param {Object} v 輸入數據物件
+     * @param {Number} k 輸入數據於陣列內之索引
+     * @returns {Object} 回傳補齊主鍵之數據物件
+     */
+    function procPk(v, k) {
+
+        //check
+        if (!isestr(v.id)) {
+
+            //check, autoGenPk為false時主鍵須由呼叫端自備
+            if (!autoGenPk) {
+                throw new Error(`invalid data[${k}].id, autoGenPk is false`)
+            }
+
+            //genID
+            v.id = genID()
+
+        }
+
+        return v
+    }
+
+
     /**
      * 判定是否為唯一索引重複鍵錯誤(11000)，批次插入時須全部寫入錯誤皆為重複鍵才算
      *
@@ -316,7 +380,12 @@ function WOrmMongodb(opt = {}) {
             client = null
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('select', null, res)
+
             return Promise.reject(res)
         }
         return res
@@ -374,7 +443,12 @@ function WOrmMongodb(opt = {}) {
             client = null
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('selectByPk', null, res)
+
             return Promise.reject(res)
         }
         return res
@@ -385,6 +459,7 @@ function WOrmMongodb(opt = {}) {
      * 插入數據，僅於id不存在時寫入，已存在者跳過且不覆寫
      * 由MongoDB於唯一索引上原子完成[檢查id未存在]與[寫入]，併發時同一id僅有一次成功
      * 註: n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果
+     * 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入
      *
      * @memberOf WOrmMongodb
      * @param {Object|Array} data 輸入數據物件或陣列
@@ -424,13 +499,8 @@ function WOrmMongodb(opt = {}) {
                 data = [data]
             }
 
-            //check id
-            data = map(data, function(v) {
-                if (!isestr(v.id)) {
-                    v.id = genID()
-                }
-                return v
-            })
+            //check id, 須於任何寫入之前一次完成, 令autoGenPk為false而拋錯時同批之有效筆數亦不會被寫入
+            data = map(data, procPk)
 
             //ensureIndex
             await ensureIndex(collection)
@@ -479,7 +549,12 @@ function WOrmMongodb(opt = {}) {
             emitChange('insert', data, res)
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('insert', data, res)
+
             return Promise.reject(res)
         }
         return res
@@ -584,7 +659,7 @@ function WOrmMongodb(opt = {}) {
                     nInserted: 0,
                     nModified: 0,
                     ok: 0,
-                    err: genErrMsg(err),
+                    err: getErrMsg(err),
                 }
 
                 break
@@ -597,6 +672,11 @@ function WOrmMongodb(opt = {}) {
             emitChange('insert', [v], rest)
         }
 
+        //emit, 逐筆失敗須於該筆結果定案後發出, 每筆一次
+        if (rest.ok === 0) {
+            emitError('save', [v], rest.err)
+        }
+
         return rest
     }
 
@@ -605,6 +685,7 @@ function WOrmMongodb(opt = {}) {
      * 儲存數據，以id為準更新既有數據，未給之欄位會保留；id不存在且option.autoInsert為true時改為插入
      * 註: n為id命中筆數，命中或經插入而產生皆為1；[內容相同]之判定基準為將待儲存物件合併進現值後結果與現值相同，
      * 相同者不寫入而nModified為0；本筆失敗不中斷整批，該筆以ok為0並附err回報
+     * 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入
      *
      * @memberOf WOrmMongodb
      * @param {Object|Array} data 輸入數據物件或陣列
@@ -645,13 +726,8 @@ function WOrmMongodb(opt = {}) {
                 data = [data]
             }
 
-            //check id
-            data = map(data, function(v) {
-                if (!isestr(v.id)) {
-                    v.id = genID()
-                }
-                return v
-            })
+            //check id, 須於任何寫入之前一次完成, 令autoGenPk為false而拋錯時同批之有效筆數亦不會被寫入
+            data = map(data, procPk)
 
             //ensureIndex
             await ensureIndex(collection)
@@ -676,7 +752,12 @@ function WOrmMongodb(opt = {}) {
             emitChange('save', data, res)
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('save', data, res)
+
             return Promise.reject(res)
         }
         return res
@@ -728,49 +809,60 @@ function WOrmMongodb(opt = {}) {
                 //id, del不補值, 未帶有效id者視為本筆無法處理
                 let id = get(v, 'id')
 
+                //rest
+                let rest = null
+
                 //check, 不得將無效id送進查詢條件, 因undefined經序列化為null會誤中id為null之數據
                 if (!isestr(id)) {
-                    return {
+
+                    //rest
+                    rest = {
                         n: 0,
                         nDeleted: 0,
                         ok: 0,
                         err: `invalid id[${id}]`,
                     }
+
                 }
+                else {
 
-                //rest
-                let rest = null
+                    try {
 
-                try {
+                        //deleteOne
+                        let r = await collection.deleteOne({ id })
 
-                    //deleteOne
-                    let r = await collection.deleteOne({ id })
+                        //nDeleted
+                        let nDeleted = get(r, 'deletedCount', 0)
 
-                    //nDeleted
-                    let nDeleted = get(r, 'deletedCount', 0)
+                        //rest, 未命中時nDeleted為0, 屬正常結果
+                        rest = {
+                            n: nDeleted,
+                            nDeleted,
+                            ok: 1,
+                        }
 
-                    //rest, 未命中時nDeleted為0, 屬正常結果
-                    rest = {
-                        n: nDeleted,
-                        nDeleted,
-                        ok: 1,
                     }
+                    catch (err) {
 
-                }
-                catch (err) {
+                        //本筆失敗不中斷整批
 
-                    //本筆失敗不中斷整批
+                        //rest
+                        rest = {
+                            n: 1,
+                            nDeleted: 0,
+                            ok: 0,
+                            err: getErrMsg(err),
+                        }
 
-                    //rest
-                    rest = {
-                        n: 1,
-                        nDeleted: 0,
-                        ok: 0,
-                        err: genErrMsg(err),
                     }
 
                 }
 
+                //emit, 逐筆失敗須於該筆結果定案後發出, 每筆一次
+                if (rest.ok === 0) {
+                    emitError('del', [v], rest.err)
+                }
+
                 return rest
             })
 
@@ -789,7 +881,12 @@ function WOrmMongodb(opt = {}) {
             emitChange('del', data, res)
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('del', data, res)
+
             return Promise.reject(res)
         }
         return res
@@ -846,7 +943,12 @@ function WOrmMongodb(opt = {}) {
             emitChange('delAll', null, res)
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('delAll', null, res)
+
             return Promise.reject(res)
         }
         return res
@@ -855,8 +957,9 @@ function WOrmMongodb(opt = {}) {
 
     /**
      * 使用GridFS，插入數據，僅於id不存在時寫入，已存在者跳過且不覆寫
-     * 數據物件形狀為{ id, u8a }，id未給時自動產生，u8a須為Uint8Array
+     * 數據物件形狀為{ id, u8a }，u8a須為Uint8Array
      * 註: n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果
+     * 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入
      *
      * @memberOf WOrmMongodb
      * @param {Object|Array} data 輸入數據物件或陣列，各數據物件形狀為{ id, u8a }
@@ -906,9 +1009,7 @@ function WOrmMongodb(opt = {}) {
             //u8a無效屬呼叫端給值錯誤且整批函數無從逐筆回報, 故往外拋
             data = map(data, function(v, k) {
                 v = { ...v }
-                if (!isestr(v.id)) {
-                    v.id = genID()
-                }
+                v = procPk(v, k)
                 if (!isu8arr(v.u8a)) {
                     throw new Error(`invalid data[${k}].u8a`)
                 }
@@ -952,7 +1053,12 @@ function WOrmMongodb(opt = {}) {
             emitChange('insertGfs', data, res)
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('insertGfs', data, res)
+
             return Promise.reject(res)
         }
         return res
@@ -1057,13 +1163,19 @@ function WOrmMongodb(opt = {}) {
             client = null
         }
 
+        //check, 查無檔案已於catch內判定為正常結果而未設isErr, 故不會誤發error事件
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('selectByPkGfs', null, res)
+
             return Promise.reject(res)
         }
         return res
     }
 
 
+    //_findGfs, 內部查找函數, 其reject由delGfs與delAllGfs之catch接住並於該處發出error事件, 故本函數不自行發出
     async function _findGfs(find = {}, bucket) {
         let isErr = false
 
@@ -1137,54 +1249,65 @@ function WOrmMongodb(opt = {}) {
                 //id, delGfs不補值, 未帶有效id者視為本筆無法處理
                 let id = get(v, 'id')
 
+                //rest
+                let rest = null
+
                 //check, 判定基準與del一致
                 if (!isestr(id)) {
-                    return {
+
+                    //rest
+                    rest = {
                         n: 0,
                         nDeleted: 0,
                         ok: 0,
                         err: `invalid id[${id}]`,
                     }
+
                 }
+                else {
 
-                //rest
-                let rest = null
+                    try {
 
-                try {
+                        //_findGfs
+                        let ltdt = await _findGfs({ filename: id }, bucket)
 
-                    //_findGfs
-                    let ltdt = await _findGfs({ filename: id }, bucket)
+                        //delete, 建立唯一索引後同一id至多一筆,
+                        //既有數據若尚存重複id則一併刪除並如實回報nDeleted
+                        let nDeleted = 0
+                        for (let vv of ltdt) {
+                            await bucket.delete(vv._id)
+                            nDeleted++
+                        }
 
-                    //delete, 建立唯一索引後同一id至多一筆,
-                    //既有數據若尚存重複id則一併刪除並如實回報nDeleted
-                    let nDeleted = 0
-                    for (let vv of ltdt) {
-                        await bucket.delete(vv._id)
-                        nDeleted++
-                    }
+                        //rest, n為命中與否, 未命中時兩者皆為0且屬正常結果
+                        rest = {
+                            n: nDeleted > 0 ? 1 : 0,
+                            nDeleted,
+                            ok: 1,
+                        }
 
-                    //rest, n為命中與否, 未命中時兩者皆為0且屬正常結果
-                    rest = {
-                        n: nDeleted > 0 ? 1 : 0,
-                        nDeleted,
-                        ok: 1,
                     }
+                    catch (err) {
 
-                }
-                catch (err) {
+                        //本筆失敗不中斷整批
 
-                    //本筆失敗不中斷整批
+                        //rest
+                        rest = {
+                            n: 1,
+                            nDeleted: 0,
+                            ok: 0,
+                            err: getErrMsg(err),
+                        }
 
-                    //rest
-                    rest = {
-                        n: 1,
-                        nDeleted: 0,
-                        ok: 0,
-                        err: genErrMsg(err),
                     }
 
                 }
 
+                //emit, 逐筆失敗須於該筆結果定案後發出, 每筆一次
+                if (rest.ok === 0) {
+                    emitError('delGfs', [v], rest.err)
+                }
+
                 return rest
             })
 
@@ -1203,7 +1326,12 @@ function WOrmMongodb(opt = {}) {
             emitChange('delGfs', data, res)
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('delGfs', data, res)
+
             return Promise.reject(res)
         }
         return res
@@ -1283,7 +1411,12 @@ function WOrmMongodb(opt = {}) {
             emitChange('delAllGfs', null, res)
         }
 
+        //check
         if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('delAllGfs', null, res)
+
             return Promise.reject(res)
         }
         return res
@@ -1322,7 +1455,7 @@ export default WOrmMongodb
 <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:36:47 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:49:55 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:36:47 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:49:55 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-orm-mongodb",
-  "version": "1.1.39",
+  "version": "1.1.41",
   "main": "dist/w-orm-mongodb.umd.js",
   "dependencies": {
     "mongodb": "^7.5.0",