w-orm-mongodb 1.1.38 → 1.1.40

package/docs/WOrmMongodb.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmMongodb.html">WOrmMongodb</a><ul class='methods'><li data-type='method'><a href="WOrmMongodb.html#.del">del</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAllGfs">delAllGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.delGfs">delGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmMongodb.html#.insertGfs">insertGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.save">save</a></li><li data-type='method'><a href="WOrmMongodb.html#.select">select</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectById">selectById</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByIdGfs">selectByIdGfs</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmMongodb.html">WOrmMongodb</a><ul class='methods'><li data-type='method'><a href="WOrmMongodb.html#.del">del</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAllGfs">delAllGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.delGfs">delGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmMongodb.html#.insertGfs">insertGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.save">save</a></li><li data-type='method'><a href="WOrmMongodb.html#.select">select</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPk">selectByPk</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPkGfs">selectByPkGfs</a></li></ul></li></ul>
     
 </nav>
 
@@ -74,13 +74,16 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>操作資料庫(MongoDB)</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>操作資料庫(MongoDB)</p>
+<p>本套件之主鍵欄位固定為id，尚未支援由呼叫端指定。id為無業務語義之識別碼。
+opt.autoGenPk預設為true，insert、save與insertGfs於輸入未帶有效id時自動產生；del於任一設定下皆不補值。
+opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋出，且id之唯一性與格式皆由呼叫端自負。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line30">line 30</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line36">line 36</a>
     </li></ul></dd>
     
 
@@ -336,6 +339,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>輸入是否於輸入未帶有效主鍵時自動產生主鍵值，預設true。為false時主鍵須由呼叫端自備，屬依賴注入之定位，主鍵之唯一性、格式與是否與既有資料衝突皆由呼叫端自負。本設定為建構層設定，不得於insert與save之option逐次覆寫</p></td>
+        </tr>
+
+    
     </tbody>
 </table>
 
@@ -431,7 +474,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line644">line 644</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line681">line 681</a>
     </li></ul></dd>
     
 
@@ -593,7 +636,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line756">line 756</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line793">line 793</a>
     </li></ul></dd>
     
 
@@ -773,7 +816,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1178">line 1178</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1215">line 1215</a>
     </li></ul></dd>
     
 
@@ -953,7 +996,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1050">line 1050</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1087">line 1087</a>
     </li></ul></dd>
     
 
@@ -1110,13 +1153,14 @@
     <dt class="tag-description">Description:</dt>
     <dd class="tag-description"><ul class="dummy"><li><p>插入數據，僅於id不存在時寫入，已存在者跳過且不覆寫
 由MongoDB於唯一索引上原子完成[檢查id未存在]與[寫入]，併發時同一id僅有一次成功
-註: n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果</p></li></ul></dd>
+註: n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果
+註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line342">line 342</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line388">line 388</a>
     </li></ul></dd>
     
 
@@ -1272,14 +1316,15 @@
     
     <dt class="tag-description">Description:</dt>
     <dd class="tag-description"><ul class="dummy"><li><p>使用GridFS，插入數據，僅於id不存在時寫入，已存在者跳過且不覆寫
-數據物件形狀為{ id, u8a }，id未給時自動產生，u8a須為Uint8Array
-註: n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果</p></li></ul></dd>
+數據物件形狀為{ id, u8a }，u8a須為Uint8Array
+註: n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果
+註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line814">line 814</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line852">line 852</a>
     </li></ul></dd>
     
 
@@ -1436,13 +1481,14 @@
     <dt class="tag-description">Description:</dt>
     <dd class="tag-description"><ul class="dummy"><li><p>儲存數據，以id為準更新既有數據，未給之欄位會保留；id不存在且option.autoInsert為true時改為插入
 註: n為id命中筆數，命中或經插入而產生皆為1；[內容相同]之判定基準為將待儲存物件合併進現值後結果與現值相同，
-相同者不寫入而nModified為0；本筆失敗不中斷整批，該筆以ok為0並附err回報</p></li></ul></dd>
+相同者不寫入而nModified為0；本筆失敗不中斷整批，該筆以ok為0並附err回報
+註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line564">line 564</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line606">line 606</a>
     </li></ul></dd>
     
 
@@ -1729,7 +1775,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line233">line 233</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line277">line 277</a>
     </li></ul></dd>
     
 
@@ -1891,7 +1937,7 @@
 
     
 
-    <h4 class="name" id=".selectById"><span class="type-signature type-signature-async, static">(async, static) </span>selectById<span class="signature">(id)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+    <h4 class="name" id=".selectByPk"><span class="type-signature type-signature-async, static">(async, static) </span>selectByPk<span class="signature">(pk)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
 
     
 
@@ -1901,14 +1947,15 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>由id查詢單筆數據，因由MongoDB查找且僅回傳單筆，不需如select提取全部符合數據再處理，故數據量大時效能較佳
+    <dd class="tag-description"><ul class="dummy"><li><p>由主鍵查詢單筆數據，因由MongoDB查找且僅回傳單筆，不需如select提取全部符合數據再處理，故數據量大時效能較佳
+註: 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定
 註: 本函數不得有副作用，故不建立唯一索引</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line284">line 284</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line329">line 329</a>
     </li></ul></dd>
     
 
@@ -1980,7 +2027,7 @@
 
         <tr>
             
-                <td class="name"><code>id</code></td>
+                <td class="name"><code>pk</code></td>
             
 
             <td class="type">
@@ -1997,7 +2044,7 @@
 
             
 
-            <td class="description last"><p>輸入id字串</p></td>
+            <td class="description last"><p>輸入主鍵值字串，即數據之id</p></td>
         </tr>
 
     
@@ -2023,7 +2070,7 @@
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳數據物件，若無此id或id無效則回傳null，reject回傳錯誤訊息</p>
+    <p>回傳Promise，resolve回傳數據物件，若無此主鍵或主鍵值無效則回傳null，reject回傳錯誤訊息</p>
 </div>
 
 
@@ -2050,7 +2097,7 @@
 
     
 
-    <h4 class="name" id=".selectByIdGfs"><span class="type-signature type-signature-async, static">(async, static) </span>selectByIdGfs<span class="signature">(id)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+    <h4 class="name" id=".selectByPkGfs"><span class="type-signature type-signature-async, static">(async, static) </span>selectByPkGfs<span class="signature">(pk)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
 
     
 
@@ -2060,15 +2107,16 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>使用GridFS，由id查詢單筆數據
-註: 查無數據或id無效時回傳null，判定基準與selectById一致
+    <dd class="tag-description"><ul class="dummy"><li><p>使用GridFS，由主鍵查詢單筆數據
+註: 查無數據或主鍵值無效時回傳null，判定基準與selectByPk一致
+註: 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定
 本函數不得有副作用，故不建立唯一索引</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line920">line 920</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line957">line 957</a>
     </li></ul></dd>
     
 
@@ -2140,7 +2188,7 @@
 
         <tr>
             
-                <td class="name"><code>id</code></td>
+                <td class="name"><code>pk</code></td>
             
 
             <td class="type">
@@ -2157,7 +2205,7 @@
 
             
 
-            <td class="description last"><p>輸入查詢id字串</p></td>
+            <td class="description last"><p>輸入主鍵值字串，即數據之id</p></td>
         </tr>
 
     
@@ -2183,7 +2231,7 @@
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳數據物件{ id, u8a }，若無此id或id無效則回傳null，reject回傳錯誤訊息</p>
+    <p>回傳Promise，resolve回傳數據物件{ id, u8a }，若無此主鍵或主鍵值無效則回傳null，reject回傳錯誤訊息</p>
 </div>
 
 
@@ -2225,7 +2273,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 22:37:44 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 07:33:48 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WOrmMongodb.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmMongodb.html">WOrmMongodb</a><ul class='methods'><li data-type='method'><a href="WOrmMongodb.html#.del">del</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAllGfs">delAllGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.delGfs">delGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmMongodb.html#.insertGfs">insertGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.save">save</a></li><li data-type='method'><a href="WOrmMongodb.html#.select">select</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectById">selectById</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByIdGfs">selectByIdGfs</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmMongodb.html">WOrmMongodb</a><ul class='methods'><li data-type='method'><a href="WOrmMongodb.html#.del">del</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAllGfs">delAllGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.delGfs">delGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmMongodb.html#.insertGfs">insertGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.save">save</a></li><li data-type='method'><a href="WOrmMongodb.html#.select">select</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPk">selectByPk</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPkGfs">selectByPkGfs</a></li></ul></li></ul>
     
 </nav>
 
@@ -56,6 +56,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'
@@ -67,11 +68,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 = {}) {
@@ -89,6 +95,13 @@ function WOrmMongodb(opt = {}) {
     }
 
 
+    //autoGenPk, 預設開啟, 為false時主鍵一律由呼叫端自備, 套件不產生亦不補救
+    let autoGenPk = get(opt, 'autoGenPk')
+    if (!isbol(autoGenPk)) {
+        autoGenPk = true
+    }
+
+
     //_indexReady, 唯一索引只須建立一次, 以旗標記錄避免每次操作皆多一次round-trip
     let _indexReady = false
 
@@ -143,6 +156,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)，批次插入時須全部寫入錯誤皆為重複鍵才算
      *
@@ -321,19 +365,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
         }
 
@@ -349,7 +394,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)) {
@@ -381,6 +426,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 輸入數據物件或陣列
@@ -420,13 +466,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)
@@ -601,6 +642,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 輸入數據物件或陣列
@@ -641,13 +683,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)
@@ -851,8 +888,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 }
@@ -902,9 +940,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`)
                 }
@@ -956,20 +992,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
         }
 
@@ -1026,11 +1063,11 @@ function WOrmMongodb(opt = {}) {
         try {
 
             //core
-            let u8a = await core(id)
+            let u8a = await core(pk)
 
             //res, 形狀與insertGfs所收之數據物件一致
             res = {
-                id,
+                id: pk,
                 u8a,
             }
 
@@ -1287,12 +1324,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
@@ -1317,7 +1354,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 22:37:44 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 07:33:48 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="WOrmMongodb.html">WOrmMongodb</a><ul class='methods'><li data-type='method'><a href="WOrmMongodb.html#.del">del</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAllGfs">delAllGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.delGfs">delGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmMongodb.html#.insertGfs">insertGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.save">save</a></li><li data-type='method'><a href="WOrmMongodb.html#.select">select</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectById">selectById</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByIdGfs">selectByIdGfs</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmMongodb.html">WOrmMongodb</a><ul class='methods'><li data-type='method'><a href="WOrmMongodb.html#.del">del</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmMongodb.html#.delAllGfs">delAllGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.delGfs">delGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmMongodb.html#.insertGfs">insertGfs</a></li><li data-type='method'><a href="WOrmMongodb.html#.save">save</a></li><li data-type='method'><a href="WOrmMongodb.html#.select">select</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPk">selectByPk</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPkGfs">selectByPkGfs</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 Sun Aug 16 2026 22:37:44 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 07:33:48 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-basic.mjs

@@ -102,13 +102,13 @@ async function test() {
     let sr = await wo.select({ name: { $regex: 'PeT', $options: 'i' } })
     console.log('selectReg', sr)
 
-    //selectById, 由id直接查找單筆, 不需如select提取全部符合數據再處理
-    let sbi = await wo.selectById('id-rosemary')
-    console.log('selectById', sbi)
+    //selectByPk, 由id直接查找單筆, 不需如select提取全部符合數據再處理
+    let sbi = await wo.selectByPk('id-rosemary')
+    console.log('selectByPk', sbi)
 
-    //selectById by id not existed
-    let sbn = await wo.selectById('id-not-existed')
-    console.log('selectById by id not existed', sbn)
+    //selectByPk by id not existed
+    let sbn = await wo.selectByPk('id-not-existed')
+    console.log('selectByPk by id not existed', sbn)
 
     //del
     let d = ss.filter(function(v) {
@@ -165,8 +165,8 @@ test()
 //   }
 // ]
 // selectReg [ { id: 'id-peter', name: 'peter(modify)', value: 123 } ]
-// selectById { id: 'id-rosemary', name: 'rosemary(modify)', value: 123.456 }
-// selectById by id not existed null
+// selectByPk { id: 'id-rosemary', name: 'rosemary(modify)', value: 123.456 }
+// selectByPk by id not existed null
 // change del
 // del then [ { n: 1, nDeleted: 1, ok: 1 } ]
 

package/g-gfs.mjs

@@ -49,15 +49,15 @@ async function test() {
     let gr = await wo.insertGfs({ id: 'id-file', u8a: genU8a(50) })
     console.log('insertGfs existed id', gr)
 
-    //selectByIdGfs
-    let gs = await wo.selectByIdGfs('id-file')
-    console.log('selectByIdGfs id', gs.id)
-    console.log('selectByIdGfs u8a.length', gs.u8a.length)
-    console.log('selectByIdGfs u8a[0..3]', gs.u8a[0], gs.u8a[1], gs.u8a[2], gs.u8a[3])
+    //selectByPkGfs
+    let gs = await wo.selectByPkGfs('id-file')
+    console.log('selectByPkGfs id', gs.id)
+    console.log('selectByPkGfs u8a.length', gs.u8a.length)
+    console.log('selectByPkGfs u8a[0..3]', gs.u8a[0], gs.u8a[1], gs.u8a[2], gs.u8a[3])
 
-    //selectByIdGfs by id not existed
-    let gn = await wo.selectByIdGfs('id-not-existed')
-    console.log('selectByIdGfs by id not existed', gn)
+    //selectByPkGfs by id not existed
+    let gn = await wo.selectByPkGfs('id-not-existed')
+    console.log('selectByPkGfs by id not existed', gn)
 
     //insertGfs, 一次插入多筆
     let gm = await wo.insertGfs([
@@ -86,10 +86,10 @@ test()
 // insertGfs { n: 1, nInserted: 1, ok: 1 }
 // change insertGfs
 // insertGfs existed id { n: 1, nInserted: 0, ok: 1 }
-// selectByIdGfs id id-file
-// selectByIdGfs u8a.length 1000
-// selectByIdGfs u8a[0..3] 0 1 2 3
-// selectByIdGfs by id not existed null
+// selectByPkGfs id id-file
+// selectByPkGfs u8a.length 1000
+// selectByPkGfs u8a[0..3] 0 1 2 3
+// selectByPkGfs by id not existed null
 // change insertGfs
 // insertGfs multi { n: 2, nInserted: 2, ok: 1 }
 // change delGfs