w-orm-postgresql 1.0.12 → 1.0.14

package/src/WOrmPostgresql.mjs

@@ -252,7 +252,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
@@ -274,8 +274,9 @@ function WOrmPostgresql(opt = {}) {
 
         try {
 
-            //nIns
+            //nIns, rows
             let nIns = 0
+            let rows = []
 
             //each batch
             for (let dt of ltdata) {
@@ -292,6 +293,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)
@@ -299,12 +304,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) {
 
@@ -316,6 +329,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倚賴主鍵之唯一約束達成原子性，
@@ -655,20 +712,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,
@@ -726,13 +801,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,
+                }
             }
 
         }
@@ -842,7 +923,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 = {

package/test/api-postgresql.test.mjs

@@ -4,6 +4,7 @@ import path from 'path'
 import pg from 'pg'
 import { execFile, spawn } from 'child_process'
 import { promisify } from 'util'
+import isarr from 'wsemi/src/isarr.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import WOrm from '../src/WOrmPostgresql.mjs'
 
@@ -1934,6 +1935,197 @@ describe('insertBulk', function() {
 })
 
 
+describe('insert returnList', function() {
+    let vans = {}
+    let vget = {}
+
+    before(async function() {
+        this.timeout(180000)
+
+        //wo
+        let cl = 'retlist'
+        let wo = WOrm(genOpt(cl))
+
+        //createTable
+        await wo.createTable(cl, null, {
+            time: '2000-01-01T00:00:00Z',
+            name: 'abc',
+            value: 0.1,
+        }).catch(() => {})
+        await wo.delAll()
+
+        //genRec
+        let genRec = (k) => {
+            return {
+                time: new Date(Date.UTC(2025, 9, 1, 0, 0, 0) + k * 1000).toISOString(),
+                name: `n${k}`,
+                value: k,
+            }
+        }
+
+        //evChange
+        let evChange = []
+        wo.on('change', (mode, data, res) => {
+            evChange.push(res)
+        })
+
+        //先插入第1與第3筆, 令後續之批次呈現[新,舊,新,舊,新]之交錯
+        await wo.insert([genRec(1), genRec(3)])
+
+        //returnList為true, 須與輸入等長保序且對位正確
+        evChange = []
+        vget[1] = await wo.insert([genRec(0), genRec(1), genRec(2), genRec(3), genRec(4)], { returnList: true })
+        vget[2] = vget[1].map((v) => v.nInserted)
+        vget[3] = vget[1].length
+        vget[4] = Object.keys(vget[1][0]).sort()
+        vget[5] = vget[1].filter((v) => v.nInserted === 1).length
+
+        //change事件之res即本次實際回傳值
+        vget[6] = isarr(evChange[0]) ? evChange[0].length : null
+
+        //聚合模式之nInserted須等於逐筆模式之filter計數
+        await wo.delAll()
+        await wo.insert([genRec(1), genRec(3)])
+        vget[7] = await wo.insert([genRec(0), genRec(1), genRec(2), genRec(3), genRec(4)])
+
+        //同批含重複主鍵, 僅首次出現者之nInserted為1
+        await wo.delAll()
+        vget[8] = (await wo.insert([genRec(10), genRec(10), genRec(11)], { returnList: true })).map((v) => v.nInserted)
+
+        //輸入無效, returnList為true回傳空陣列, 為false回傳聚合物件
+        vget[9] = await wo.insert(null, { returnList: true })
+        vget[10] = await wo.insert(null)
+
+        //單一物件輸入亦回傳長度1之陣列
+        await wo.delAll()
+        vget[11] = await wo.insert(genRec(20), { returnList: true })
+
+        //returnList為false時形狀不變
+        vget[12] = await wo.insert(genRec(21))
+
+        //文字主鍵之型別分流, 主鍵非時間戳者不得誤判
+        let clC = 'retlistcode'
+        let woC = WOrm({
+            ...genOpt(clC),
+            pk: 'code',
+        })
+        await woC.createTable(clC, null, {
+            code: 'abc',
+            name: 'abc',
+            value: 0.1,
+        }).catch(() => {})
+        await woC.delAll()
+        await woC.insert([
+            { code: 'c1', name: 'n1', value: 1 },
+            { code: 'c3', name: 'n3', value: 3 },
+        ])
+        vget[13] = (await woC.insert([
+            { code: 'c0', name: 'n0', value: 0 },
+            { code: 'c1', name: 'n1', value: 1 },
+            { code: 'c2', name: 'n2', value: 2 },
+            { code: 'c3', name: 'n3', value: 3 },
+            { code: 'c4', name: 'n4', value: 4 },
+        ], { returnList: true })).map((v) => v.nInserted)
+
+        //文字主鍵而值形如日期者, 不得因正規化而碰撞
+        let clD = 'retlistdate'
+        let woD = WOrm({
+            ...genOpt(clD),
+            pk: 'code',
+        })
+        await woD.createTable(clD, null, {
+            code: 'abc',
+            name: 'abc',
+            value: 0.1,
+        }).catch(() => {})
+        await woD.delAll()
+        await woD.insert({ code: '2025', name: 'y', value: 1 })
+        vget[14] = (await woD.insert([
+            { code: '2025', name: 'y', value: 1 },
+            { code: '2025-01-01', name: 'd', value: 2 },
+        ], { returnList: true })).map((v) => v.nInserted)
+
+    })
+
+    vans[1] = [
+        { n: 1, nInserted: 1, ok: 1 },
+        { n: 1, nInserted: 0, ok: 1 },
+        { n: 1, nInserted: 1, ok: 1 },
+        { n: 1, nInserted: 0, ok: 1 },
+        { n: 1, nInserted: 1, ok: 1 },
+    ]
+    it(`should get ${JSON.stringify(vans[1])} for insert with returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[1], vans[1])
+    })
+
+    vans[2] = [1, 0, 1, 0, 1]
+    it(`should get ${JSON.stringify(vans[2])} for nInserted in order by insert with returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[2], vans[2])
+    })
+
+    vans[3] = 5
+    it(`should get ${JSON.stringify(vans[3])} for length of insert with returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[3], vans[3])
+    })
+
+    vans[4] = ['n', 'nInserted', 'ok']
+    it(`should get ${JSON.stringify(vans[4])} for keys of each element by insert with returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[4], vans[4])
+    })
+
+    vans[5] = 3
+    it(`should get ${JSON.stringify(vans[5])} for count of nInserted===1 by insert with returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[5], vans[5])
+    })
+
+    vans[6] = 5
+    it(`should get ${JSON.stringify(vans[6])} for length of res in change event by insert with returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[6], vans[6])
+    })
+
+    vans[7] = { n: 5, nInserted: 3, ok: 1 }
+    it(`should get ${JSON.stringify(vans[7])} for insert without returnList on same input`, async function() {
+        assert.strict.deepStrictEqual(vget[7], vans[7])
+    })
+
+    vans[8] = [1, 0, 1]
+    it(`should get ${JSON.stringify(vans[8])} for duplicated pk in same batch by insert with returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[8], vans[8])
+    })
+
+    vans[9] = []
+    it(`should get ${JSON.stringify(vans[9])} for insert with invalid data and returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[9], vans[9])
+    })
+
+    vans[10] = { n: 0, nInserted: 0, ok: 1 }
+    it(`should get ${JSON.stringify(vans[10])} for insert with invalid data and without returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[10], vans[10])
+    })
+
+    vans[11] = [{ n: 1, nInserted: 1, ok: 1 }]
+    it(`should get ${JSON.stringify(vans[11])} for insert with single object and returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[11], vans[11])
+    })
+
+    vans[12] = { n: 1, nInserted: 1, ok: 1 }
+    it(`should get ${JSON.stringify(vans[12])} for insert with single object and without returnList`, async function() {
+        assert.strict.deepStrictEqual(vget[12], vans[12])
+    })
+
+    vans[13] = [1, 0, 1, 0, 1]
+    it(`should get ${JSON.stringify(vans[13])} for insert with returnList by custom text pk`, async function() {
+        assert.strict.deepStrictEqual(vget[13], vans[13])
+    })
+
+    vans[14] = [0, 1]
+    it(`should get ${JSON.stringify(vans[14])} for insert with returnList by text pk looking like date`, async function() {
+        assert.strict.deepStrictEqual(vget[14], vans[14])
+    })
+
+})
+
+
 //runProc, 另起行程對同一資料表操作, 用於驗證跨行程之原子性
 //子行程以--input-type=module執行, 並以pathToFileURL轉換src路徑, 避免專案路徑含非ASCII字元而無法import
 function runProc(tag, opt, mode, payload) {

package/toolg/gDistRollup.mjs

@@ -7,7 +7,7 @@ let fdTar = './dist'
 
 
 rollupFiles({
-    fns: getFiles(fdSrc),
+    fns: 'WOrmPostgresql.mjs',
     fdSrc,
     fdTar,
     nameDistType: 'kebabCase',