w-orm-mongodb 1.1.41 → 1.1.43

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#.selectByPk">selectByPk</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPkGfs">selectByPkGfs</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#.insertBulk">insertBulk</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>
 
@@ -83,7 +83,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line36">line 36</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line37">line 37</a>
     </li></ul></dd>
     
 
@@ -474,7 +474,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line729">line 729</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line936">line 936</a>
     </li></ul></dd>
     
 
@@ -636,7 +636,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line857">line 857</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1064">line 1064</a>
     </li></ul></dd>
     
 
@@ -816,7 +816,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line1311">line 1311</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1518">line 1518</a>
     </li></ul></dd>
     
 
@@ -996,7 +996,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line1167">line 1167</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1374">line 1374</a>
     </li></ul></dd>
     
 
@@ -1160,7 +1160,175 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line421">line 421</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line426">line 426</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+
+
+
+
+
+
+
+
+    <h5 class="h5-parameters">Parameters:</h5>
+    
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Name</th>
+        
+
+        <th>Type</th>
+
+        
+
+        
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    
+
+        <tr>
+            
+                <td class="name"><code>data</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+|
+
+<span class="param-type">Array</span>
+
+
+
+            
+            </td>
+
+            
+
+            
+
+            <td class="description last"><p>輸入數據物件或陣列</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h5 class="h5-returns">Returns:</h5>
+
+        
+<div class="param-desc">
+    <p>回傳Promise，resolve回傳插入結果，reject回傳錯誤訊息</p>
+</div>
+
+
+
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
+        
+<span class="param-type">Promise</span>
+
+
+
+    </dd>
+</dl>
+
+    
+
+
+
+        
+            
+
+    
+
+    <h4 class="name" id=".insertBulk"><span class="type-signature type-signature-async, static">(async, static) </span>insertBulk<span class="signature">(data)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+
+    
+
+
+
+
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>批次插入數據，全批視為一個單位：全部插入成功，或一筆都不寫入
+任一筆之id已存在(含同批含重複id)即以reject拋出整批性錯誤，且不寫入任何一筆
+註: 本函數非insert之加速版，兩者衝突政策不同——insert跳過已存在者而整批ok為1，
+本函數則整批reject；需要逐筆處置者改用insert
+註: n為輸入筆數，nInserted於成功時恆等於n；不提供逐筆結果，故不出現ok為0與err
+註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入
+註: 全有全無之達成方式依部署而異——具replica set或分片叢集者以交易包覆，
+standalone無交易可用而以補償動作達成，其限制詳見_insertBulkByCompensate</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#line638">line 638</a>
     </li></ul></dd>
     
 
@@ -1324,7 +1492,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line921">line 921</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1128">line 1128</a>
     </li></ul></dd>
     
 
@@ -1488,7 +1656,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line649">line 649</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line856">line 856</a>
     </li></ul></dd>
     
 
@@ -1775,7 +1943,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line300">line 300</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line305">line 305</a>
     </li></ul></dd>
     
 
@@ -1955,7 +2123,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line357">line 357</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line362">line 362</a>
     </li></ul></dd>
     
 
@@ -2116,7 +2284,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
     
     <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#line1031">line 1031</a>
+        <a href="WOrmMongodb.mjs.html">WOrmMongodb.mjs</a>, <a href="WOrmMongodb.mjs.html#line1238">line 1238</a>
     </li></ul></dd>
     
 
@@ -2273,7 +2441,7 @@ opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋
 <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:49:55 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 11:28:35 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#.selectByPk">selectByPk</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPkGfs">selectByPkGfs</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#.insertBulk">insertBulk</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>
 
@@ -49,13 +49,14 @@
 import stream from 'stream'
 import cloneDeep from 'lodash-es/cloneDeep.js'
 import every from 'lodash-es/every.js'
+import filter from 'lodash-es/filter.js'
 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 genIDSeq from 'wsemi/src/genIDSeq.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import isarr from 'wsemi/src/isarr.mjs'
@@ -110,6 +111,10 @@ function WOrmMongodb(opt = {}) {
     let _indexGfsReady = false
 
 
+    //_canUseTx, 拓樸判定只須一次, 以旗標記錄避免每次操作皆多一次round-trip
+    let _canUseTx = null
+
+
     //ee, 採wsemi之evem(即eventemitter3), 其於'error'無監聽者時僅回傳false而不拋出,
     //故本套件之操作行為不因呼叫端有無註冊監聽而改變; Node內建之EventEmitter具該拋出語義, 不可用
     let ee = evem()
@@ -201,8 +206,8 @@ function WOrmMongodb(opt = {}) {
                 throw new Error(`invalid data[${k}].id, autoGenPk is false`)
             }
 
-            //genID
-            v.id = genID()
+            //genIDSeq
+            v.id = genIDSeq()
 
         }
 
@@ -561,6 +566,208 @@ function WOrmMongodb(opt = {}) {
     }
 
 
+    /**
+     * 判定本次部署是否支援交易
+     * 註: MongoDB之交易須replica set或分片叢集，standalone不支援
+     * 判定依據為hello回應：replica set帶setName，連至mongos者msg為isdbgrid，standalone兩者皆無
+     *
+     * @ignore
+     * @param {Object} client 輸入MongoClient物件
+     * @returns {Promise} 回傳Promise，resolve回傳是否支援交易布林值，reject回傳錯誤訊息
+     */
+    async function canUseTx(client) {
+
+        //check
+        if (isbol(_canUseTx)) {
+            return _canUseTx
+        }
+
+        //hello
+        let hello = await client.db(opt.db).admin().command({ hello: 1 })
+
+        //_canUseTx
+        _canUseTx = isestr(get(hello, 'setName')) || get(hello, 'msg') === 'isdbgrid'
+
+        return _canUseTx
+    }
+
+
+    /**
+     * 以交易達成insertBulk之全有全無
+     * 交易內任一筆失敗即整批回滾，故不會寫入任何一筆，無須補償動作
+     *
+     * @ignore
+     * @param {Object} client 輸入MongoClient物件
+     * @param {Object} collection 輸入資料表物件
+     * @param {Array} data 輸入數據陣列
+     * @returns {Promise} 回傳Promise，resolve回傳undefined，reject回傳錯誤訊息
+     */
+    async function _insertBulkByTx(client, collection, data) {
+
+        //session
+        let session = client.startSession()
+
+        try {
+
+            //withTransaction, ordered:true令首筆衝突即停止, 由交易回滾保證未寫入任何一筆
+            await session.withTransaction(async () => {
+                await collection.insertMany(data, { session, ordered: true })
+            })
+
+        }
+        finally {
+            await session.endSession()
+        }
+
+    }
+
+
+    /**
+     * 以補償動作達成insertBulk之全有全無，供無交易可用之standalone使用
+     * 註: 補償係刪除本次呼叫已寫入者，其_id由驅動於送出前在用戶端產生，
+     * 與呼叫前既有數據之_id必不相同，故縱使該筆之id已存在亦不會誤刪既有數據；
+     * 刪除未寫入者為無操作，故不須精確得知哪幾筆已寫入
+     * 註: 行程若於補償途中中止(斷電、強制終止)，已寫入之部份可能殘留，此為無交易可用之固有限制
+     *
+     * @ignore
+     * @param {Object} collection 輸入資料表物件
+     * @param {Array} data 輸入數據陣列
+     * @returns {Promise} 回傳Promise，resolve回傳undefined，reject回傳錯誤訊息
+     */
+    async function _insertBulkByCompensate(collection, data) {
+
+        //errIns
+        let errIns = null
+
+        try {
+            await collection.insertMany(data, { ordered: false })
+        }
+        catch (err) {
+            errIns = err
+        }
+
+        //check, 全數插入成功即無須補償
+        if (errIns === null) {
+            return
+        }
+
+        //idDels, 取本次由驅動所產生之全部_id
+        let idDels = map(data, function(v) {
+            return v._id
+        })
+        idDels = filter(idDels, function(v) {
+            return v !== undefined &amp;&amp; v !== null
+        })
+
+        //補償, 刪除本次已寫入者
+        if (size(idDels) > 0) {
+            await collection.deleteMany({ _id: { $in: idDels } })
+        }
+
+        throw errIns
+    }
+
+
+    /**
+     * 批次插入數據，全批視為一個單位：全部插入成功，或一筆都不寫入
+     * 任一筆之id已存在(含同批含重複id)即以reject拋出整批性錯誤，且不寫入任何一筆
+     * 註: 本函數非insert之加速版，兩者衝突政策不同——insert跳過已存在者而整批ok為1，
+     * 本函數則整批reject；需要逐筆處置者改用insert
+     * 註: n為輸入筆數，nInserted於成功時恆等於n；不提供逐筆結果，故不出現ok為0與err
+     * 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入
+     * 註: 全有全無之達成方式依部署而異——具replica set或分片叢集者以交易包覆，
+     * standalone無交易可用而以補償動作達成，其限制詳見_insertBulkByCompensate
+     *
+     * @memberOf WOrmMongodb
+     * @param {Object|Array} data 輸入數據物件或陣列
+     * @returns {Promise} 回傳Promise，resolve回傳插入結果，reject回傳錯誤訊息
+     */
+    async function insertBulk(data) {
+        let isErr = false
+
+        //check
+        if (!iseobj(data) &amp;&amp; !isearr(data)) {
+            return {
+                n: 0,
+                nInserted: 0,
+                ok: 1,
+            }
+        }
+
+        //cloneDeep
+        data = cloneDeep(data)
+
+        //client
+        let client = new MongoClient(opt.url)
+
+        //res
+        let res = null
+        try {
+
+            //connect, 令連線失敗於寫入前即拋出, 屬影響全部數據之整批性錯誤
+            await client.connect()
+
+            //database, collection
+            let database = client.db(opt.db)
+            let collection = database.collection(opt.cl)
+
+            //check
+            if (!isarr(data)) {
+                data = [data]
+            }
+
+            //check id, 須於任何寫入之前一次完成
+            data = map(data, procPk)
+
+            //ensureIndex
+            await ensureIndex(collection)
+
+            //nAll, n之基準為輸入筆數
+            let nAll = size(data)
+
+            //check, 有交易可用者一律優先採用交易, 其回滾即為全有全無之保證
+            let bTx = await canUseTx(client)
+            if (bTx) {
+                await _insertBulkByTx(client, collection, data)
+            }
+            else {
+                await _insertBulkByCompensate(collection, data)
+            }
+
+            //res, 執行至此表全數插入成功, 故nInserted恆等於n
+            res = {
+                n: nAll,
+                nInserted: nAll,
+                ok: 1,
+            }
+
+        }
+        catch (err) {
+            isErr = true
+            res = err
+        }
+        finally {
+            await client.close()
+            client = null
+        }
+
+        //emit
+        if (!isErr) {
+            emitChange('insertBulk', data, res)
+        }
+
+        //check
+        if (isErr) {
+
+            //emit, 整批性錯誤須於reject之前發出
+            emitError('insertBulk', data, res)
+
+            return Promise.reject(res)
+        }
+        return res
+    }
+
+
     /**
      * 儲存單筆數據，由MongoDB於單一updateOne內原子完成[查找id]與[更新或插入]
      * 註: MongoDB單一文件操作本即為原子，故不須開啟transaction(transaction另須replica set，standalone不支援)
@@ -1427,6 +1634,7 @@ function WOrmMongodb(opt = {}) {
     ee.select = select
     ee.selectByPk = selectByPk
     ee.insert = insert
+    ee.insertBulk = insertBulk
     ee.save = save
     ee.del = del
     ee.delAll = delAll
@@ -1455,7 +1663,7 @@ export default WOrmMongodb
 <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:49:55 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 11:28:35 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#.selectByPk">selectByPk</a></li><li data-type='method'><a href="WOrmMongodb.html#.selectByPkGfs">selectByPkGfs</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#.insertBulk">insertBulk</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 Mon Aug 17 2026 08:49:55 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 11:28:35 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-basic.mjs

@@ -46,11 +46,17 @@ async function test() {
     //wo
     let wo = WOrm(opt)
 
-    //on
+    //on change, 資料實際異動成功後發出
     wo.on('change', function(mode, data, res) {
         console.log('change', mode)
     })
 
+    //on error, 操作發生錯誤時發出, 整批性錯誤於reject前、逐筆失敗於該筆定案後
+    //註: 事件僅為附加通知, 錯誤仍可由reject或逐筆之err欄位取得; 正常結果不會發出
+    wo.on('error', function(mode, data, err) {
+        console.log('error', mode, err)
+    })
+
     //delAll
     await wo.delAll()
         .then(function(msg) {

package/g-gfs.mjs

@@ -24,11 +24,17 @@ async function test() {
     //wo
     let wo = WOrm(opt)
 
-    //on
+    //on change, 資料實際異動成功後發出
     wo.on('change', function(mode, data, res) {
         console.log('change', mode)
     })
 
+    //on error, 操作發生錯誤時發出, 整批性錯誤於reject前、逐筆失敗於該筆定案後
+    //註: 事件僅為附加通知, 錯誤仍可由reject或逐筆之err欄位取得; 正常結果不會發出
+    wo.on('error', function(mode, data, err) {
+        console.log('error', mode, err)
+    })
+
     //u8a, 亦可為瀏覽器或nodejs取得之任何Uint8Array
     let u8a = genU8a(1000)
 

package/package.json

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