w-orm-mongodb 1.1.38 → 1.1.40

package/g-unique.mjs

@@ -28,12 +28,12 @@ async function test() {
         { id: 'id-uniq', name: 'uniq' },
     ])
     console.log('insert with duplicated id', ri)
-    console.log('selectById(id-dup)', await wo.selectById('id-dup'))
+    console.log('selectByPk(id-dup)', await wo.selectByPk('id-dup'))
 
     //insert, 對已存在id再插入則跳過而不覆寫
     let re = await wo.insert({ id: 'id-dup', name: 'dup-3' })
     console.log('insert existed id', re)
-    console.log('selectById(id-dup)', await wo.selectById('id-dup'))
+    console.log('selectByPk(id-dup)', await wo.selectByPk('id-dup'))
 
     //insert, 併發對同一id插入10次, nInserted總和為1
     let rc = await Promise.all(Array.from({ length: 10 }, (v, k) => {
@@ -48,19 +48,19 @@ async function test() {
     }))
     console.log('count of nInserted===1 by 5 concurrent save', rs.filter((v) => v[0].nInserted === 1).length)
     console.log('records of id-new', (await wo.select({ id: 'id-new' })).length)
-    console.log('selectById(id-new)', await wo.selectById('id-new'))
+    console.log('selectByPk(id-new)', await wo.selectByPk('id-new'))
 
 }
 test()
 // insert with duplicated id { n: 3, nInserted: 2, ok: 1 }
-// selectById(id-dup) { id: 'id-dup', name: 'dup-1' }
+// selectByPk(id-dup) { id: 'id-dup', name: 'dup-1' }
 // insert existed id { n: 1, nInserted: 0, ok: 1 }
-// selectById(id-dup) { id: 'id-dup', name: 'dup-1' }
+// selectByPk(id-dup) { id: 'id-dup', name: 'dup-1' }
 // sum of nInserted by 10 concurrent insert 1
 // records of id-race 1
 // count of nInserted===1 by 5 concurrent save 1
 // records of id-new 1
-// selectById(id-new) { id: 'id-new', f0: 0, f1: 1, f2: 2, f4: 4, f3: 3 }
+// selectByPk(id-new) { id: 'id-new', f0: 0, f1: 1, f2: 2, f4: 4, f3: 3 }
 // 註: 併發儲存之各欄位皆會保留, 惟欄位順序取決於各次儲存之完成順序, 故每次執行不盡相同
 
 //node g-unique.mjs

package/package.json

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

package/src/WOrmMongodb.mjs

@@ -9,6 +9,7 @@ import omit from 'lodash-es/omit.js'
 import size from 'lodash-es/size.js'
 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'
@@ -20,11 +21,16 @@ import pmSeries from 'wsemi/src/pmSeries.mjs'
 /**
  * 操作資料庫(MongoDB)
  *
+ * 本套件之主鍵欄位固定為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 = {}) {
@@ -42,6 +48,13 @@ function WOrmMongodb(opt = {}) {
     }
 
 
+    //autoGenPk, 預設開啟, 為false時主鍵一律由呼叫端自備, 套件不產生亦不補救
+    let autoGenPk = get(opt, 'autoGenPk')
+    if (!isbol(autoGenPk)) {
+        autoGenPk = true
+    }
+
+
     //_indexReady, 唯一索引只須建立一次, 以旗標記錄避免每次操作皆多一次round-trip
     let _indexReady = false
 
@@ -96,6 +109,37 @@ function WOrmMongodb(opt = {}) {
     }
 
 
+    /**
+     * 檢查並補齊單筆數據之主鍵
+     * 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)，批次插入時須全部寫入錯誤皆為重複鍵才算
      *
@@ -274,19 +318,20 @@ function WOrmMongodb(opt = {}) {
 
 
     /**
-     * 由id查詢單筆數據，因由MongoDB查找且僅回傳單筆，不需如select提取全部符合數據再處理，故數據量大時效能較佳
+     * 由主鍵查詢單筆數據，因由MongoDB查找且僅回傳單筆，不需如select提取全部符合數據再處理，故數據量大時效能較佳
+     * 註: 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定
      * 註: 本函數不得有副作用，故不建立唯一索引
      *
      * @memberOf WOrmMongodb
-     * @param {String} id 輸入id字串
-     * @returns {Promise} 回傳Promise，resolve回傳數據物件，若無此id或id無效則回傳null，reject回傳錯誤訊息
+     * @param {String} pk 輸入主鍵值字串，即數據之id
+     * @returns {Promise} 回傳Promise，resolve回傳數據物件，若無此主鍵或主鍵值無效則回傳null，reject回傳錯誤訊息
      */
-    async function selectById(id) {
+    async function selectByPk(pk) {
         let isErr = false
 
         //check
-        if (!isestr(id)) {
-            //未給有效id視為查無數據, 判定基準與insert、save、del內對id之認定一致
+        if (!isestr(pk)) {
+            //未給有效主鍵值視為查無數據, 判定基準與insert、save、del內對id之認定一致
             return null
         }
 
@@ -302,7 +347,7 @@ function WOrmMongodb(opt = {}) {
             let collection = database.collection(opt.cl)
 
             //findOne, 以投影去除_id, 令回傳形狀與select一致
-            let v = await collection.findOne({ id }, { projection: { _id: 0 } })
+            let v = await collection.findOne({ id: pk }, { projection: { _id: 0 } })
 
             //check, 判定基準與insert、save、del內對既有數據之認定一致
             if (iseobj(v)) {
@@ -334,6 +379,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 輸入數據物件或陣列
@@ -373,13 +419,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)
@@ -554,6 +595,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 輸入數據物件或陣列
@@ -594,13 +636,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)
@@ -804,8 +841,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 }
@@ -855,9 +893,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`)
                 }
@@ -909,20 +945,21 @@ function WOrmMongodb(opt = {}) {
 
 
     /**
-     * 使用GridFS，由id查詢單筆數據
-     * 註: 查無數據或id無效時回傳null，判定基準與selectById一致
+     * 使用GridFS，由主鍵查詢單筆數據
+     * 註: 查無數據或主鍵值無效時回傳null，判定基準與selectByPk一致
+     * 註: 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定
      * 本函數不得有副作用，故不建立唯一索引
      *
      * @memberOf WOrmMongodb
-     * @param {String} id 輸入查詢id字串
-     * @returns {Promise} 回傳Promise，resolve回傳數據物件{ id, u8a }，若無此id或id無效則回傳null，reject回傳錯誤訊息
+     * @param {String} pk 輸入主鍵值字串，即數據之id
+     * @returns {Promise} 回傳Promise，resolve回傳數據物件{ id, u8a }，若無此主鍵或主鍵值無效則回傳null，reject回傳錯誤訊息
      */
-    async function selectByIdGfs(id) {
+    async function selectByPkGfs(pk) {
         let isErr = false
 
         //check
-        if (!isestr(id)) {
-            //未給有效id視為查無數據, 判定基準與selectById一致
+        if (!isestr(pk)) {
+            //未給有效主鍵值視為查無數據, 判定基準與selectByPk一致
             return null
         }
 
@@ -979,11 +1016,11 @@ function WOrmMongodb(opt = {}) {
         try {
 
             //core
-            let u8a = await core(id)
+            let u8a = await core(pk)
 
             //res, 形狀與insertGfs所收之數據物件一致
             res = {
-                id,
+                id: pk,
                 u8a,
             }
 
@@ -1240,12 +1277,12 @@ function WOrmMongodb(opt = {}) {
 
     //bind
     ee.select = select
-    ee.selectById = selectById
+    ee.selectByPk = selectByPk
     ee.insert = insert
     ee.save = save
     ee.del = del
     ee.delAll = delAll
-    ee.selectByIdGfs = selectByIdGfs
+    ee.selectByPkGfs = selectByPkGfs
     ee.insertGfs = insertGfs
     ee.delGfs = delGfs
     ee.delAllGfs = delAllGfs