w-orm-postgresql 1.0.11 → 1.0.12

package/docs/WOrmPostgresql.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByPk">selectByPk</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByPk">selectByPk</a></li></ul></li></ul>
     
 </nav>
 
@@ -514,7 +514,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line259">line 259</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line330">line 330</a>
     </li></ul></dd>
     
 
@@ -771,7 +771,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1094">line 1094</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1262">line 1262</a>
     </li></ul></dd>
     
 
@@ -934,7 +934,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1255">line 1255</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1423">line 1423</a>
     </li></ul></dd>
     
 
@@ -1115,7 +1115,174 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line595">line 595</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line666">line 666</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回傳插入結果物件{n,nInserted,ok}，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>批次插入數據，全批視為一個單位，全部插入成功或一筆都不寫入</p>
+<p>本函數非insert之加速版，兩者衝突政策不同：insert於主鍵已存在時跳過該筆且整批ok為1，
+本函數則於任一筆之主鍵已存在時整批reject且不寫入任何一筆，同批含重複主鍵者亦視為衝突。
+n為輸入筆數，nInserted為實際插入筆數且成功時恆等於n。
+不提供逐筆結果，故不出現ok:0與err，需要逐筆處置者改用insert。
+因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報，
+且主鍵檢查於任何寫入之前一次完成，故整批reject時同批之有效筆數亦不會被寫入。</p></li></ul></dd>
+    
+
+    
+    <dt class="tag-source">Source:</dt>
+    <dd class="tag-source"><ul class="dummy"><li>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line784">line 784</a>
     </li></ul></dd>
     
 
@@ -1270,7 +1437,7 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>儲存數據，以主鍵time為準更新既有數據，未給之欄位保留</p>
+    <dd class="tag-description"><ul class="dummy"><li><p>儲存數據，以主鍵為準更新既有數據，未給之欄位保留</p>
 <p>回傳陣列恆與輸入等長，輸入單一物件亦回傳長度1之陣列。
 各筆之n為主鍵命中筆數，值為0或1，命中(不論內容有無變更)或經插入而產生皆為1；
 nInserted與nModified恆同時出現，無對應行為時填0。
@@ -1283,7 +1450,7 @@ nInserted與nModified恆同時出現，無對應行為時填0。
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line735">line 735</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line903">line 903</a>
     </li></ul></dd>
     
 
@@ -1570,7 +1737,7 @@ nInserted與nModified恆同時出現，無對應行為時填0。
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line359">line 359</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line430">line 430</a>
     </li></ul></dd>
     
 
@@ -1791,7 +1958,7 @@ nInserted與nModified恆同時出現，無對應行為時填0。
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line462">line 462</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line533">line 533</a>
     </li></ul></dd>
     
 
@@ -1954,7 +2121,7 @@ nInserted與nModified恆同時出現，無對應行為時填0。
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 17 2026 09:06:32 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:51:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WOrmPostgresql.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByPk">selectByPk</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByPk">selectByPk</a></li></ul></li></ul>
     
 </nav>
 
@@ -292,6 +292,77 @@ function WOrmPostgresql(opt = {}) {
         _cache[key] = cloneDeep(data) //與外部使用數據脫勾
     }
 
+    //insertBatches, 分批送出插入語句並以交易包覆, 回傳實際插入筆數, 供insert與insertBulk共用
+    //PostgreSQL之協定以int16記綁定參數個數故上限為65535, 單一語句可送之筆數受欄位數所限,
+    //超出者須分批送出; 分批後單語句之原子性已不足以維持[失敗即不留下部份寫入], 故一律以交易包覆,
+    //令單批與分批之保證來源一致而不因批數而異
+    //兩函數之衝突政策由useConflict區分, 語句各自獨立:
+    //  true : 添加ON CONFLICT DO NOTHING, 已存在主鍵者跳過而不中斷整批, 為insert之語義
+    //  false: 不添加, 任一筆撞主鍵之唯一約束即整句失敗且不寫入任何一筆, 為insertBulk之全有全無語義
+    let insertBatches = async (client, data, useConflict) => {
+
+        //nCols, 取各筆欄位數之最大值
+        let nCols = 1
+        data.forEach(function(v) {
+            nCols = Math.max(nCols, size(keys(v)))
+        })
+
+        //nPerBatch
+        let nPerBatch = Math.max(1, Math.floor(65535 / nCols))
+
+        //ltdata, 分批
+        let ltdata = []
+        for (let i = 0; i &lt; size(data); i += nPerBatch) {
+            ltdata.push(data.slice(i, i + nPerBatch))
+        }
+
+        //transaction
+        await client.query('BEGIN')
+
+        try {
+
+            //nIns
+            let nIns = 0
+
+            //each batch
+            for (let dt of ltdata) {
+
+                //mr
+                let mr = mongoSql.sql({
+                    type: 'insert',
+                    table: cl,
+                    values: dt,
+                })
+
+                //sql
+                let sql = mr.query
+                if (useConflict) {
+                    sql = `${sql} ON CONFLICT (${pkName}) DO NOTHING`
+                }
+
+                //insert
+                let r = await client.query(sql, mr.values)
+
+                //nIns
+                nIns += r.rowCount
+
+            }
+
+            //commit
+            await client.query('COMMIT')
+
+            return nIns
+        }
+        catch (err) {
+
+            //rollback, 令已送出之批次一併回滾
+            await client.query('ROLLBACK').catch(() => {})
+
+            throw err
+        }
+
+    }
+
     /**
      * 創建資料表
      * 註: pk未給時採建構時之opt.pk。因insert與save倚賴主鍵之唯一約束達成原子性，
@@ -695,40 +766,137 @@ function WOrmPostgresql(opt = {}) {
                 return v
             })
 
-            //mr
-            let mr = mongoSql.sql({
-                type: 'insert',
-                table: cl,
-                values: data,
-            })
-            // console.log('mr', mr)
-            // console.log('mr.query', mr.query)
-            // console.log('mr.values', mr.values)
+            //nAll
+            let nAll = size(data)
 
-            //添加conflict, 令已存在主鍵者跳過而不中斷整批插入, 主鍵認定與genConflictSQL一致
+            //insert, 以ON CONFLICT DO NOTHING令已存在主鍵者跳過而不中斷整批插入,
             //由PostgreSQL於單一語句內原子完成[檢查主鍵未存在]與[寫入], 併發時同一主鍵僅有一次成功,
             //同批含重複主鍵時亦僅首筆成功, 故不須逐筆插入即可取得實際插入筆數
-            let sql = `${mr.query} ON CONFLICT (${pkName}) DO NOTHING`
+            //筆數過多而超出綁定參數上限者由insertBatches分批送出, 主鍵認定與genConflictSQL一致
+            let nIns = await insertBatches(client, data, true)
+
+            //res
+            res = {
+                n: nAll,
+                nInserted: nIns,
+                ok: 1,
+            }
+
+        }
+        catch (err) {
+            isErr = true
+            res = err
+        }
+        finally {
+            await client.end()
+            client = null
+        }
+
+        //update
+        if (useCache) {
+            clearCache()
+        }
+
+        //emit
+        if (!isErr) {
+            emitChange('insert', data, res)
+        }
+
+        //check
+        if (isErr) {
+
+            //emit, 整批性錯誤於reject之前發出
+            emitError('insert', data, res)
+
+            return Promise.reject(res)
+        }
+
+        return res
+    }
+
+    /**
+     * 批次插入數據，全批視為一個單位，全部插入成功或一筆都不寫入
+     *
+     * 本函數非insert之加速版，兩者衝突政策不同：insert於主鍵已存在時跳過該筆且整批ok為1，
+     * 本函數則於任一筆之主鍵已存在時整批reject且不寫入任何一筆，同批含重複主鍵者亦視為衝突。
+     * n為輸入筆數，nInserted為實際插入筆數且成功時恆等於n。
+     * 不提供逐筆結果，故不出現ok:0與err，需要逐筆處置者改用insert。
+     * 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報，
+     * 且主鍵檢查於任何寫入之前一次完成，故整批reject時同批之有效筆數亦不會被寫入。
+     *
+     * @memberOf WOrmPostgresql
+     * @param {Object|Array} data 輸入數據物件或陣列
+     * @returns {Promise} 回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，reject回傳錯誤訊息
+     */
+    async function insertBulk(data) {
+        let isErr = false
+        let res = null
+
+        //check
+        if (!iseobj(data) &amp;&amp; !isearr(data)) {
+            return {
+                n: 0,
+                nInserted: 0,
+                ok: 1,
+            }
+        }
+
+        //cloneDeep
+        data = cloneDeep(data)
+
+        //client
+        let client = new PgClient({ connectionString })
+
+        //connect
+        try {
+
+            //connect
+            await client.connect()
+
+        }
+        catch (err) {
+            isErr = true
+            res = err
+            client = null
+        }
+
+        //check
+        if (isErr) {
+
+            //emit, 整批性錯誤於reject之前發出
+            emitError('insertBulk', data, res)
+
+            return Promise.reject(res)
+        }
+
+        try {
+
+            //check
+            if (!isarr(data)) {
+                data = [data]
+            }
+
+            //check pk, 因主鍵得承載業務語義故不自動補值, 未帶有效主鍵值者屬整批性錯誤
+            data = map(data, function(v, k) {
+                if (!checkPk(get(v, pkName))) {
+                    throw new Error(`invalid data[${k}].${pkName}[${get(v, pkName)}]`)
+                }
+                return v
+            })
 
             //nAll
             let nAll = size(data)
 
-            //insert, ON CONFLICT DO NOTHING時rowCount即為實際插入筆數
-            await client.query(sql, mr.values)
-                .then((r) => {
-
-                    //res
-                    res = {
-                        n: nAll,
-                        nInserted: r.rowCount,
-                        ok: 1,
-                    }
+            //insertBulk, 不添加conflict, 令任一筆撞主鍵之唯一約束即整句失敗且不寫入任何一筆,
+            //同批含重複主鍵者亦於此被偵測為衝突; 筆數過多者由insertBatches分批送出並以交易維持全有全無
+            let nIns = await insertBatches(client, data, false)
 
-                })
-                .catch((err) => {
-                    isErr = true
-                    res = err.message
-                })
+            //res
+            res = {
+                n: nAll,
+                nInserted: nIns,
+                ok: 1,
+            }
 
         }
         catch (err) {
@@ -747,14 +915,14 @@ function WOrmPostgresql(opt = {}) {
 
         //emit
         if (!isErr) {
-            emitChange('insert', data, res)
+            emitChange('insertBulk', data, res)
         }
 
         //check
         if (isErr) {
 
             //emit, 整批性錯誤於reject之前發出
-            emitError('insert', data, res)
+            emitError('insertBulk', data, res)
 
             return Promise.reject(res)
         }
@@ -763,7 +931,7 @@ function WOrmPostgresql(opt = {}) {
     }
 
     /**
-     * 儲存數據，以主鍵time為準更新既有數據，未給之欄位保留
+     * 儲存數據，以主鍵為準更新既有數據，未給之欄位保留
      *
      * 回傳陣列恆與輸入等長，輸入單一物件亦回傳長度1之陣列。
      * 各筆之n為主鍵命中筆數，值為0或1，命中(不論內容有無變更)或經插入而產生皆為1；
@@ -1408,6 +1576,7 @@ function WOrmPostgresql(opt = {}) {
     ee.select = select
     ee.selectByPk = selectByPk
     ee.insert = insert
+    ee.insertBulk = insertBulk
     ee.save = save
     ee.del = del
     ee.delAll = delAll
@@ -1431,7 +1600,7 @@ export default WOrmPostgresql
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 17 2026 09:06:32 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:51:27 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="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByPk">selectByPk</a></li></ul></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByPk">selectByPk</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 09:06:32 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:51:27 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>