w-orm-postgresql 1.0.12 → 1.0.14

package/docs/WOrmPostgresql.html

@@ -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#line330">line 330</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line387">line 387</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#line1262">line 1262</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1344">line 1344</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#line1423">line 1423</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1505">line 1505</a>
     </li></ul></dd>
     
 
@@ -1096,7 +1096,7 @@
 
     
 
-    <h4 class="name" id=".insert"><span class="type-signature type-signature-async, static">(async, static) </span>insert<span class="signature">(data)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+    <h4 class="name" id=".insert"><span class="type-signature type-signature-async, static">(async, static) </span>insert<span class="signature">(data, option<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
 
     
 
@@ -1107,15 +1107,19 @@
     
     <dt class="tag-description">Description:</dt>
     <dd class="tag-description"><ul class="dummy"><li><p>插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫</p>
-<p>n為輸入筆數，即本次嘗試插入之基準；nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果，
-不視為錯誤。同批含重複主鍵時僅首筆計入nInserted。
-因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。</p></li></ul></dd>
+<p>預設回傳單一聚合物件，n為輸入筆數即本次嘗試插入之基準；nInserted為實際插入筆數，
+全數已存在而nInserted為0屬正常結果，不視為錯誤。同批含重複主鍵時僅首筆計入nInserted。
+因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。</p>
+<p>option.returnList為true時改回傳與輸入等長且保序之逐筆陣列，令呼叫端得知[是哪幾筆]為新數據，
+而非僅知[有幾筆]。各元素之n恆為1、ok恆為1，因insert之任何錯誤皆屬整批性錯誤而reject，
+故逐筆元素不出現ok:0與err；同批含重複主鍵者以首次出現者之nInserted為1，其餘為0。
+兩種取值下之不變式為陣列長度等於輸入筆數，且nInserted為1者之筆數等於聚合模式之nInserted。</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#line666">line 666</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line731">line 731</a>
     </li></ul></dd>
     
 
@@ -1175,8 +1179,12 @@
         <th>Type</th>
 
         
+        <th>Attributes</th>
+        
 
         
+        <th>Default</th>
+        
 
         <th class="last">Description</th>
     </tr>
@@ -1204,13 +1212,135 @@
             </td>
 
             
+                <td class="attributes">
+                
+
+                
+
+                
+                </td>
+            
 
             
+                <td class="default">
+                
+                </td>
+            
 
             <td class="description last"><p>輸入數據物件或陣列</p></td>
         </tr>
 
     
+
+        <tr>
+            
+                <td class="name"><code>option</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>{}</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入設定物件，預設為{}</p>
+                <h6>Properties</h6>
+                
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Name</th>
+        
+
+        <th>Type</th>
+
+        
+        <th>Attributes</th>
+        
+
+        
+        <th>Default</th>
+        
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    
+
+        <tr>
+            
+                <td class="name"><code>returnList</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Boolean</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>false</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入是否改回傳逐筆結果陣列，預設為false</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+            </td>
+        </tr>
+
+    
     </tbody>
 </table>
 
@@ -1233,7 +1363,8 @@
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，reject回傳錯誤訊息</p>
+    <p>回傳Promise，resolve於returnList為false時回傳插入結果物件{n,nInserted,ok}，
+為true時回傳逐筆結果陣列[{n,nInserted,ok}]，reject回傳錯誤訊息</p>
 </div>
 
 
@@ -1282,7 +1413,7 @@ n為輸入筆數，nInserted為實際插入筆數且成功時恆等於n。
     
     <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>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line865">line 865</a>
     </li></ul></dd>
     
 
@@ -1450,7 +1581,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#line903">line 903</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line985">line 985</a>
     </li></ul></dd>
     
 
@@ -1737,7 +1868,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#line430">line 430</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line487">line 487</a>
     </li></ul></dd>
     
 
@@ -1958,7 +2089,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#line533">line 533</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line590">line 590</a>
     </li></ul></dd>
     
 
@@ -2121,7 +2252,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 11:51:27 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 Tue Aug 18 2026 12:15:18 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WOrmPostgresql.mjs.html

@@ -299,7 +299,7 @@ function WOrmPostgresql(opt = {}) {
     //兩函數之衝突政策由useConflict區分, 語句各自獨立:
     //  true : 添加ON CONFLICT DO NOTHING, 已存在主鍵者跳過而不中斷整批, 為insert之語義
     //  false: 不添加, 任一筆撞主鍵之唯一約束即整句失敗且不寫入任何一筆, 為insertBulk之全有全無語義
-    let insertBatches = async (client, data, useConflict) => {
+    let insertBatches = async (client, data, useConflict, returnPk = false) => {
 
         //nCols, 取各筆欄位數之最大值
         let nCols = 1
@@ -321,8 +321,9 @@ function WOrmPostgresql(opt = {}) {
 
         try {
 
-            //nIns
+            //nIns, rows
             let nIns = 0
+            let rows = []
 
             //each batch
             for (let dt of ltdata) {
@@ -339,6 +340,10 @@ function WOrmPostgresql(opt = {}) {
                 if (useConflict) {
                     sql = `${sql} ON CONFLICT (${pkName}) DO NOTHING`
                 }
+                if (returnPk) {
+                    //RETURNING僅回傳實際插入之列, 供逐筆結果映回輸入序
+                    sql = `${sql} RETURNING ${pkName}`
+                }
 
                 //insert
                 let r = await client.query(sql, mr.values)
@@ -346,12 +351,20 @@ function WOrmPostgresql(opt = {}) {
                 //nIns
                 nIns += r.rowCount
 
+                //rows, 分批時逐批收集再串接
+                if (returnPk) {
+                    rows = rows.concat(get(r, 'rows', []))
+                }
+
             }
 
             //commit
             await client.query('COMMIT')
 
-            return nIns
+            return {
+                nIns,
+                rows,
+            }
         }
         catch (err) {
 
@@ -363,6 +376,50 @@ function WOrmPostgresql(opt = {}) {
 
     }
 
+    //genInsertList, 依RETURNING所回傳之主鍵值映回輸入序, 產生與輸入等長且保序之逐筆結果
+    //後端回傳之型別未必與輸入相同(如TIMESTAMPTZ欄位輸入字串而回傳Date物件), 直接比對必然落空,
+    //故依回傳值之實際型別決定正規化方式, 且兩側共用同一函數
+    //不採[一律嘗試解析為日期]之通用寫法, 因主鍵為文字欄位而值形如'2025'與'2025-01-01'者
+    //將正規化為同值而誤判, 依實際型別分流則無此問題
+    //同批含重複主鍵時RETURNING僅回傳一次, 故以首次出現者為已插入, 其餘視為已存在而跳過
+    let genInsertList = (data, rows) => {
+
+        //isDateCol, 以回傳值之實際型別判定
+        let isDateCol = size(rows) > 0 && rows[0][pkName] instanceof Date
+
+        //normPk
+        let normPk = (v) => {
+            if (isDateCol) {
+                return new Date(v).toISOString()
+            }
+            return String(v)
+        }
+
+        //setIns, 實際插入之主鍵
+        let setIns = new Set()
+        rows.forEach(function(v) {
+            setIns.add(normPk(get(v, pkName)))
+        })
+
+        //ltres
+        let setSeen = new Set()
+        return map(data, function(v) {
+
+            //pkv
+            let pkv = normPk(get(v, pkName))
+
+            //inserted
+            let inserted = setIns.has(pkv) && !setSeen.has(pkv)
+            setSeen.add(pkv)
+
+            return {
+                n: 1,
+                nInserted: inserted ? 1 : 0,
+                ok: 1,
+            }
+        })
+    }
+
     /**
      * 創建資料表
      * 註: pk未給時採建構時之opt.pk。因insert與save倚賴主鍵之唯一約束達成原子性，
@@ -702,20 +759,38 @@ function WOrmPostgresql(opt = {}) {
     /**
      * 插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫
      *
-     * n為輸入筆數，即本次嘗試插入之基準；nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果，
-     * 不視為錯誤。同批含重複主鍵時僅首筆計入nInserted。
+     * 預設回傳單一聚合物件，n為輸入筆數即本次嘗試插入之基準；nInserted為實際插入筆數，
+     * 全數已存在而nInserted為0屬正常結果，不視為錯誤。同批含重複主鍵時僅首筆計入nInserted。
      * 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。
      *
+     * option.returnList為true時改回傳與輸入等長且保序之逐筆陣列，令呼叫端得知[是哪幾筆]為新數據，
+     * 而非僅知[有幾筆]。各元素之n恆為1、ok恆為1，因insert之任何錯誤皆屬整批性錯誤而reject，
+     * 故逐筆元素不出現ok:0與err；同批含重複主鍵者以首次出現者之nInserted為1，其餘為0。
+     * 兩種取值下之不變式為陣列長度等於輸入筆數，且nInserted為1者之筆數等於聚合模式之nInserted。
+     *
      * @memberOf WOrmPostgresql
      * @param {Object|Array} data 輸入數據物件或陣列
-     * @returns {Promise} 回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，reject回傳錯誤訊息
+     * @param {Object} [option={}] 輸入設定物件，預設為{}
+     * @param {Boolean} [option.returnList=false] 輸入是否改回傳逐筆結果陣列，預設為false
+     * @returns {Promise} 回傳Promise，resolve於returnList為false時回傳插入結果物件{n,nInserted,ok}，
+     * 為true時回傳逐筆結果陣列[{n,nInserted,ok}]，reject回傳錯誤訊息
      */
-    async function insert(data) {
+    async function insert(data, option = {}) {
         let isErr = false
         let res = null
 
+        //returnList
+        let returnList = get(option, 'returnList', false)
+        if (!isbol(returnList)) {
+            returnList = false
+        }
+
         //check
+        //輸入無效時, returnList為true者回傳空陣列以對齊save與del之規定
         if (!iseobj(data) && !isearr(data)) {
+            if (returnList) {
+                return []
+            }
             return {
                 n: 0,
                 nInserted: 0,
@@ -773,13 +848,19 @@ function WOrmPostgresql(opt = {}) {
             //由PostgreSQL於單一語句內原子完成[檢查主鍵未存在]與[寫入], 併發時同一主鍵僅有一次成功,
             //同批含重複主鍵時亦僅首筆成功, 故不須逐筆插入即可取得實際插入筆數
             //筆數過多而超出綁定參數上限者由insertBatches分批送出, 主鍵認定與genConflictSQL一致
-            let nIns = await insertBatches(client, data, true)
+            //returnList為true時另附RETURNING, 以實際插入之主鍵映回輸入序而得逐筆結果
+            let { nIns, rows } = await insertBatches(client, data, true, returnList)
 
             //res
-            res = {
-                n: nAll,
-                nInserted: nIns,
-                ok: 1,
+            if (returnList) {
+                res = genInsertList(data, rows)
+            }
+            else {
+                res = {
+                    n: nAll,
+                    nInserted: nIns,
+                    ok: 1,
+                }
             }
 
         }
@@ -889,7 +970,8 @@ function WOrmPostgresql(opt = {}) {
 
             //insertBulk, 不添加conflict, 令任一筆撞主鍵之唯一約束即整句失敗且不寫入任何一筆,
             //同批含重複主鍵者亦於此被偵測為衝突; 筆數過多者由insertBatches分批送出並以交易維持全有全無
-            let nIns = await insertBatches(client, data, false)
+            //不附RETURNING, 因成功時逐筆恆為已插入而nInserted恆等於n, 取回主鍵值無資訊量
+            let { nIns } = await insertBatches(client, data, false)
 
             //res
             res = {
@@ -1600,7 +1682,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 11:51:27 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 Tue Aug 18 2026 12:15:18 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 Mon Aug 17 2026 11:51:27 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 Tue Aug 18 2026 12:15:18 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-basic.mjs

@@ -123,6 +123,19 @@ let rsb = [
     },
 ]
 
+let rsr = [
+    { //已存在, 為前次insertBulk所插入
+        time: '2025-01-01T00:20:00Z',
+        name: 'bulk-1',
+        value: 201,
+    },
+    { //不存在須新增
+        time: '2025-01-01T00:22:00Z',
+        name: 'ret-new',
+        value: 203,
+    },
+]
+
 async function test() {
 
     //wo
@@ -185,6 +198,15 @@ async function test() {
             console.log('insertBulk by pk existed catch', `${msg}`) //reject回傳Error物件, 以樣板字串取其訊息以免印出堆疊
         })
 
+    //insert by returnList, 改回傳與輸入等長且保序之逐筆結果, 令呼叫端得知是哪幾筆為新數據
+    await wo.insert(rsr, { returnList: true })
+        .then(function(msg) {
+            console.log('insert by returnList then', msg)
+        })
+        .catch(function(msg) {
+            console.log('insert by returnList catch', `${msg}`)
+        })
+
     //save
     await wo.save(rsm, { autoInsert: false })
         .then(function(msg) {
@@ -345,6 +367,8 @@ test()
 // insertBulk then { n: 2, nInserted: 2, ok: 1 }
 // error insertBulk duplicate key value violates unique constraint "users_pkey"
 // insertBulk by pk existed catch error: duplicate key value violates unique constraint "users_pkey"
+// change insert
+// insert by returnList then [ { n: 1, nInserted: 0, ok: 1 }, { n: 1, nInserted: 1, ok: 1 } ]
 // change save
 // save then [
 //   { n: 1, nInserted: 0, nModified: 0, ok: 1 },
@@ -366,6 +390,7 @@ test()
 //   { time: 2025-01-01T00:09:00.000Z, name: 'peter', value: 127 },
 //   { time: 2025-01-01T00:20:00.000Z, name: 'bulk-1', value: 201 },
 //   { time: 2025-01-01T00:21:00.000Z, name: 'bulk-2', value: 202 },
+//   { time: 2025-01-01T00:22:00.000Z, name: 'ret-new', value: 203 },
 //   {
 //     time: 2025-01-01T00:10:00.000Z,
 //     name: 'rosemary(modify)',
@@ -403,6 +428,7 @@ test()
 //   { time: 2025-01-01T00:08:00.000Z, name: 'kettle', value: 524 },
 //   { time: 2025-01-01T00:20:00.000Z, name: 'bulk-1', value: 201 },
 //   { time: 2025-01-01T00:21:00.000Z, name: 'bulk-2', value: 202 },
+//   { time: 2025-01-01T00:22:00.000Z, name: 'ret-new', value: 203 },
 //   {
 //     time: 2025-01-01T00:11:00.000Z,
 //     name: 'kettle(modify)',
@@ -447,6 +473,7 @@ test()
 //   { time: 2025-01-01T00:07:00.000Z, name: 'rosemary', value: 124.76 },
 //   { time: 2025-01-01T00:20:00.000Z, name: 'bulk-1', value: 201 },
 //   { time: 2025-01-01T00:21:00.000Z, name: 'bulk-2', value: 202 },
+//   { time: 2025-01-01T00:22:00.000Z, name: 'ret-new', value: 203 },
 //   {
 //     time: 2025-01-01T00:10:00.000Z,
 //     name: 'rosemary(modify)',

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "w-orm-postgresql",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "main": "dist/w-orm-postgresql.umd.js",
   "dependencies": {
     "mongo-sql": "^6.2.0",
     "pg": "^8.23.0",
-    "wsemi": "^1.8.70"
+    "wsemi": "^1.8.73"
   },
   "devDependencies": {
     "w-package-tools": "^1.1.12"