w-orm-postgresql 1.0.9 → 1.0.10

package/src/WOrmPostgresql.mjs

@@ -26,11 +26,16 @@ import pmSeries from 'wsemi/src/pmSeries.mjs'
 /**
  * 操作資料庫(PostgreSQL)
  *
+ * 本套件之主鍵欄位由opt.pk指定，預設為time，select以外之五函數皆以此欄位認定主鍵。
+ * 因主鍵得為承載業務語義之欄位(如時序資料之觀測時間)，insert與save於輸入未帶有效主鍵值時不自動補值，
+ * 一律以reject回報；del亦不補值，該筆回ok:0與err。
+ *
  * @class
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {String} [opt.url='postgresql://127.0.0.1:5432'] 輸入連接資料庫字串，預設'postgresql://127.0.0.1:5432'
  * @param {String} [opt.db='worm'] 輸入使用資料庫名稱字串，預設'worm'
  * @param {String} [opt.cl='test'] 輸入使用資料表名稱字串，預設'test'
+ * @param {String} [opt.pk='time'] 輸入主鍵欄位名字串，預設'time'
  * @param {Boolean} [opt.useCache=false] 輸入是否使用select快取，適用於單程序操作，預設false
  * @returns {Object} 回傳操作資料庫物件，各事件功能詳見說明
  */
@@ -63,6 +68,26 @@ function WOrmPostgresql(opt = {}) {
         useCache = false
     }
 
+    //pkName, 主鍵欄位名, select以外之五函數皆以此欄位認定主鍵, 預設為time
+    let pkName = get(opt, 'pk')
+    if (!isestr(pkName)) {
+        pkName = 'time'
+    }
+
+    //checkPk, 判定主鍵值是否有效
+    //因主鍵欄位得由呼叫端指定, 其型別隨欄位而異, 故此處僅要求有給值而不限定型別,
+    //型別與欄位不符者由PostgreSQL回報, 各函數再依其規格處置
+    function checkPk(pkv) {
+        return isestr(pkv) || isnum(pkv) || isbol(pkv) || isDate(pkv)
+    }
+
+    //isErrPkType, 判定錯誤是否為[主鍵值型別與欄位不符]
+    //22P02為invalid_text_representation, 22007為invalid_datetime_format
+    function isErrPkType(err) {
+        let code = get(err, 'code')
+        return code === '22P02' || code === '22007'
+    }
+
     //getValueType
     function getValueType(value) {
         if (isstr(value)) {
@@ -115,7 +140,7 @@ function WOrmPostgresql(opt = {}) {
         let allKeys = keys(obj)
 
         //conflictKeys
-        let conflictKeys = ['time']
+        let conflictKeys = [pkName]
 
         //updateKeys
         let updateKeys = filter(allKeys, (k) => {
@@ -190,14 +215,22 @@ function WOrmPostgresql(opt = {}) {
 
     /**
      * 創建資料表
+     * 註: pk未給時採建構時之opt.pk。因insert與save倚賴主鍵之唯一約束達成原子性，
+     * 若給予與opt.pk不同之欄位，將建出其餘函數無法正確操作之資料表，故一般應留空或給予相同值
      *
      * @memberOf WOrmPostgresql
      * @param {String} cl 輸入資料表名字串
-     * @param {String} pk 輸入主鍵字串
+     * @param {String} [pk=opt.pk] 輸入主鍵欄位名字串，預設為建構時之opt.pk
      * @param {Array|Object} arr 輸入數據物件陣列或數據物件
      * @returns {Promise} 回傳Promise，resolve回傳成功訊息，reject回傳錯誤訊息
      */
     async function createTable(cl, pk, arr) {
+
+        //pk, 未給時採建構時設定之主鍵欄位
+        if (!isestr(pk)) {
+            pk = pkName
+        }
+
         let isErr = false
         let res = null
 
@@ -368,29 +401,29 @@ function WOrmPostgresql(opt = {}) {
     }
 
     /**
-     * 由主鍵time查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳
+     * 由主鍵查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳
+     * 註: 本套件之主鍵欄位由建構時之opt.pk指定，預設為time
      *
-     * 函數名依主鍵欄位命名為selectByTime而不另掛selectById別名，因本套件之主鍵為具業務語義之time，
-     * 與以無語義識別碼為主鍵者性質不同，該差異須由呼叫端知悉而非由別名掩蓋。
      * 主鍵未命中或主鍵值無效皆回傳null而不reject，命中之判定基準與insert、save、del內對既有數據之認定一致。
+     * 主鍵值之型別與欄位不符時PostgreSQL回報22P02或22007，亦屬主鍵值無效而回傳null。
      *
      * @memberOf WOrmPostgresql
-     * @param {String|Date} time 輸入主鍵time值，本套件以time欄位為主鍵
-     * @returns {Promise} 回傳Promise，resolve回傳數據物件，若無此time則回傳null，reject回傳錯誤訊息
+     * @param {String|Number|Date} pk 輸入主鍵值，即數據之主鍵欄位值
+     * @returns {Promise} 回傳Promise，resolve回傳數據物件，若無此主鍵則回傳null，reject回傳錯誤訊息
      */
-    async function selectByTime(time) {
+    async function selectByPk(pk) {
         let isErr = false
         let res = null
 
         //check
-        if (!isDate(time)) {
-            //未給有效主鍵值視為查無數據, 判定基準與insert、save、del內對time之認定一致
+        if (!checkPk(pk)) {
+            //未給有效主鍵值視為查無數據, 判定基準與insert、save、del內對主鍵之認定一致
             return null
         }
 
-        //find, 本套件以time欄位為主鍵, 與save、del、genConflictSQL之認定一致
+        //find, 以建構時設定之主鍵欄位查找, 與insert、save、del、genConflictSQL之認定一致
         let find = {
-            time,
+            [pkName]: pk,
         }
 
         //cache, 與select共用快取, 因快取鍵值由find與order組成, 故此處等同select(find)之結果
@@ -444,7 +477,7 @@ function WOrmPostgresql(opt = {}) {
 
             //check
             if (!isarr(rows)) {
-                throw new Error(`can not select by time[${time}]`)
+                throw new Error(`can not select by pk[${pk}]`)
             }
 
             //cache
@@ -460,14 +493,22 @@ function WOrmPostgresql(opt = {}) {
                 res = v
             }
             else {
-                //不存在time, 回傳null
+                //不存在主鍵, 回傳null
                 res = null
             }
 
         }
         catch (err) {
-            isErr = true
-            res = err
+
+            //check, 主鍵值之型別與欄位不符者亦屬主鍵值無效, 依規格回傳null而不reject
+            if (isErrPkType(err)) {
+                res = null
+            }
+            else {
+                isErr = true
+                res = err
+            }
+
         }
         finally {
             await client.end()
@@ -484,11 +525,11 @@ function WOrmPostgresql(opt = {}) {
     }
 
     /**
-     * 插入數據，僅於主鍵time不存在時寫入，已存在者跳過且不覆寫
+     * 插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫
      *
      * n為輸入筆數，即本次嘗試插入之基準；nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果，
-     * 不視為錯誤。同批含重複time時僅首筆計入nInserted。
-     * 因主鍵time承載觀測時間之業務意義，未帶有效time時不自動補值，一律以reject回報。
+     * 不視為錯誤。同批含重複主鍵時僅首筆計入nInserted。
+     * 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。
      *
      * @memberOf WOrmPostgresql
      * @param {Object|Array} data 輸入數據物件或陣列
@@ -538,10 +579,10 @@ function WOrmPostgresql(opt = {}) {
                 data = [data]
             }
 
-            //check time
+            //check pk, 因主鍵得承載業務語義故不自動補值, 未帶有效主鍵值者屬整批性錯誤
             data = map(data, function(v, k) {
-                if (!isDate(v.time)) {
-                    throw new Error(`invalid data[${k}].time[${v.time}]`)
+                if (!checkPk(get(v, pkName))) {
+                    throw new Error(`invalid data[${k}].${pkName}[${get(v, pkName)}]`)
                 }
                 return v
             })
@@ -556,10 +597,10 @@ function WOrmPostgresql(opt = {}) {
             // console.log('mr.query', mr.query)
             // console.log('mr.values', mr.values)
 
-            //添加conflict, 令已存在time者跳過而不中斷整批插入, 主鍵認定與genConflictSQL一致
-            //由PostgreSQL於單一語句內原子完成[檢查time未存在]與[寫入], 併發時同一time僅有一次成功,
-            //同批含重複time時亦僅首筆成功, 故不須逐筆插入即可取得實際插入筆數
-            let sql = `${mr.query} ON CONFLICT (time) DO NOTHING`
+            //添加conflict, 令已存在主鍵者跳過而不中斷整批插入, 主鍵認定與genConflictSQL一致
+            //由PostgreSQL於單一語句內原子完成[檢查主鍵未存在]與[寫入], 併發時同一主鍵僅有一次成功,
+            //同批含重複主鍵時亦僅首筆成功, 故不須逐筆插入即可取得實際插入筆數
+            let sql = `${mr.query} ON CONFLICT (${pkName}) DO NOTHING`
 
             //nAll
             let nAll = size(data)
@@ -623,7 +664,7 @@ function WOrmPostgresql(opt = {}) {
      * [內容相同]之判定基準為待寫入物件合併進現值後與現值相同，非待寫入物件與現值全等，
      * 故只給部份欄位且該些欄位值皆與現值相同時，合併結果等於現值，nModified為0，
      * 令nModified忠實反映資料庫端是否真的寫入。
-     * 因主鍵time承載觀測時間之業務意義，未帶有效time時不自動補值，一律以reject回報。
+     * 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。
      *
      * @memberOf WOrmPostgresql
      * @param {Object|Array} data 輸入數據物件或陣列
@@ -674,10 +715,10 @@ function WOrmPostgresql(opt = {}) {
                 data = [data]
             }
 
-            //check time
+            //check pk, 因主鍵得承載業務語義故不自動補值, 未帶有效主鍵值者屬整批性錯誤
             data = map(data, function(v, k) {
-                if (!isDate(v.time)) {
-                    throw new Error(`invalid data[${k}].time[${v.time}]`)
+                if (!checkPk(get(v, pkName))) {
+                    throw new Error(`invalid data[${k}].${pkName}[${get(v, pkName)}]`)
                 }
                 return v
             })
@@ -688,6 +729,9 @@ function WOrmPostgresql(opt = {}) {
                 //rest
                 let rest = null
 
+                //pkv
+                let pkv = get(v, pkName)
+
                 //_v
                 let _v = null
                 if (true) {
@@ -697,7 +741,7 @@ function WOrmPostgresql(opt = {}) {
                         type: 'select',
                         table: cl,
                         where: {
-                            time: v.time,
+                            [pkName]: pkv,
                         },
                         // limit: 10,
                         // order,
@@ -726,7 +770,7 @@ function WOrmPostgresql(opt = {}) {
                 if (iseobj(_v)) {
 
                     //_vt
-                    let _vt = omit(_v, 'time')
+                    let _vt = omit(_v, pkName)
                     // console.log('_vt', _vt)
 
                     //vt, [內容相同]之判定基準為[待寫入物件合併進現值後與現值相同],
@@ -734,7 +778,7 @@ function WOrmPostgresql(opt = {}) {
                     //合併採淺層覆蓋, 與後端以EXCLUDED整欄取代之寫入行為一致
                     let vt = {
                         ..._vt,
-                        ...omit(v, 'time'),
+                        ...omit(v, pkName),
                     }
                     // console.log('vt', vt)
 
@@ -789,11 +833,11 @@ function WOrmPostgresql(opt = {}) {
                     // console.log('mr.query', mr.query)
                     // console.log('mr.values', mr.values)
 
-                    //添加conflict, 僅有time欄位時genConflictSQL無可更新欄位而回傳空字串,
-                    //此時退回DO NOTHING, 以免併發插入同一time者報錯
+                    //添加conflict, 僅有主鍵欄位時genConflictSQL無可更新欄位而回傳空字串,
+                    //此時退回DO NOTHING, 以免併發插入同一主鍵者報錯
                     let conflict = genConflictSQL(v)
                     if (!isestr(conflict)) {
-                        conflict = 'ON CONFLICT (time) DO NOTHING'
+                        conflict = `ON CONFLICT (${pkName}) DO NOTHING`
                     }
 
                     //sql, xmax為0表該列由本語句插入, 非0表係由DO UPDATE更新而來,
@@ -864,15 +908,15 @@ function WOrmPostgresql(opt = {}) {
                 }
                 else {
                     //未開啟autoInsert則僅能更新既有數據, 不可用INSERT以免無中生有,
-                    //由UPDATE...WHERE time原子完成[查找time]與[更新], 併發時不會遺失更新
+                    //由UPDATE...WHERE主鍵原子完成[查找主鍵]與[更新], 併發時不會遺失更新
 
                     //mr
                     let mr = mongoSql.sql({
                         type: 'update',
                         table: cl,
-                        updates: omit(v, 'time'),
+                        updates: omit(v, pkName),
                         where: {
-                            time: v.time,
+                            [pkName]: pkv,
                         },
                     })
                     // console.log('mr', mr)
@@ -967,7 +1011,7 @@ function WOrmPostgresql(opt = {}) {
      *
      * 回傳陣列恆與輸入等長，各筆之n與nDeleted皆為主鍵命中筆數，值為0或1，未命中為0且屬正常結果。
      * 判斷某筆是否真的被刪除一律以nDeleted為準。
-     * 未帶有效time者為該筆之輸入問題，回ok:0與err且不送查詢，不中斷其餘筆數，
+     * 未帶有效主鍵值者為該筆之輸入問題，回ok:0與err且不送查詢，不中斷其餘筆數，
      * 以此與[主鍵未命中]之ok:1區辨。
      *
      * @memberOf WOrmPostgresql
@@ -1024,19 +1068,19 @@ function WOrmPostgresql(opt = {}) {
                 //rest
                 let rest = null
 
-                //time
-                let time = get(v, 'time')
+                //pkv
+                let pkv = get(v, pkName)
 
-                //check time, 未帶有效主鍵者不補值亦不送查詢,
+                //check pk, 未帶有效主鍵者不補值亦不送查詢,
                 //因mongo-sql會將無效值轉為null而誤中其他數據, 故直接視為該筆無法處理
-                if (!isDate(time)) {
+                if (!checkPk(pkv)) {
 
                     //rest
                     rest = {
                         n: 0,
                         nDeleted: 0,
                         ok: 0,
-                        err: `invalid time[${time}]`,
+                        err: `invalid ${pkName}[${pkv}]`,
                     }
 
                     return rest
@@ -1047,7 +1091,7 @@ function WOrmPostgresql(opt = {}) {
                     type: 'delete',
                     table: cl,
                     where: {
-                        time,
+                        [pkName]: pkv,
                     },
                 })
                 // console.log('mr', mr)
@@ -1228,7 +1272,7 @@ function WOrmPostgresql(opt = {}) {
     //save
     ee.createTable = createTable
     ee.select = select
-    ee.selectByTime = selectByTime
+    ee.selectByPk = selectByPk
     ee.insert = insert
     ee.save = save
     ee.del = del

package/test/api-postgresql.test.mjs

@@ -373,47 +373,47 @@ describe('basic', function() {
             })
         vget[6] = rt
 
-        //selectByTime
+        //selectByPk
         rt = null
         // vans[18] = { time: new Date('2025-01-01T00:10:00.000Z'), name: 'rosemary(modify)', value: 113.98 }
-        await wo.selectByTime('2025-01-01T00:10:00Z')
+        await wo.selectByPk('2025-01-01T00:10:00Z')
             .then(function(msg) {
-                // console.log('selectByTime then', msg)
-                // selectByTime { time: 2025-01-01T00:10:00.000Z, name: 'rosemary(modify)', value: 113.98 }
+                // console.log('selectByPk then', msg)
+                // selectByPk { time: 2025-01-01T00:10:00.000Z, name: 'rosemary(modify)', value: 113.98 }
                 rt = msg
             })
             .catch(function(msg) {
-                // console.log('selectByTime catch', msg)
+                // console.log('selectByPk catch', msg)
                 rt = msg.toString()
             })
         vget[18] = rt
 
-        //selectByTime by time not existed
+        //selectByPk by pk not existed
         rt = null
         // vans[19] = null
-        await wo.selectByTime('2024-01-01T00:00:00Z')
+        await wo.selectByPk('2024-01-01T00:00:00Z')
             .then(function(msg) {
-                // console.log('selectByTime by time not existed then', msg)
-                // selectByTime by time not existed null
+                // console.log('selectByPk by pk not existed then', msg)
+                // selectByPk by pk not existed null
                 rt = msg
             })
             .catch(function(msg) {
-                // console.log('selectByTime by time not existed catch', msg)
+                // console.log('selectByPk by pk not existed catch', msg)
                 rt = msg.toString()
             })
         vget[19] = rt
 
-        //selectByTime by time invalid, 未給有效主鍵值視為查無數據
+        //selectByPk by pk invalid, 未給有效主鍵值視為查無數據
         rt = null
         // vans[20] = null
-        await wo.selectByTime('abc')
+        await wo.selectByPk('abc')
             .then(function(msg) {
-                // console.log('selectByTime by time invalid then', msg)
-                // selectByTime by time invalid null
+                // console.log('selectByPk by pk invalid then', msg)
+                // selectByPk by pk invalid null
                 rt = msg
             })
             .catch(function(msg) {
-                // console.log('selectByTime by time invalid catch', msg)
+                // console.log('selectByPk by pk invalid catch', msg)
                 rt = msg.toString()
             })
         vget[20] = rt
@@ -674,30 +674,30 @@ describe('basic', function() {
             })
         vget[17] = rt
 
-        //selectByTime (1st time, 從DB讀取並填入快取)
+        //selectByPk (1st time, 從DB讀取並填入快取)
         rt = null
         // vans[21] = { time: new Date('2025-01-01T00:01:00.000Z'), name: 'rosemary(modify)', value: 654.321 }
-        await woc.selectByTime('2025-01-01T00:01:00Z')
+        await woc.selectByPk('2025-01-01T00:01:00Z')
             .then(function(msg) {
-                // console.log('selectByTime 1st then', msg)
+                // console.log('selectByPk 1st then', msg)
                 rt = msg
             })
             .catch(function(msg) {
-                // console.log('selectByTime 1st catch', msg)
+                // console.log('selectByPk 1st catch', msg)
                 rt = msg.toString()
             })
         vget[21] = rt
 
-        //selectByTime (2nd time, 命中快取, 內容須與第一次相同)
+        //selectByPk (2nd time, 命中快取, 內容須與第一次相同)
         rt = null
         // vans[22] = vans[21]
-        await woc.selectByTime('2025-01-01T00:01:00Z')
+        await woc.selectByPk('2025-01-01T00:01:00Z')
             .then(function(msg) {
-                // console.log('selectByTime 2nd then', msg)
+                // console.log('selectByPk 2nd then', msg)
                 rt = msg
             })
             .catch(function(msg) {
-                // console.log('selectByTime 2nd catch', msg)
+                // console.log('selectByPk 2nd catch', msg)
                 rt = msg.toString()
             })
         vget[22] = rt
@@ -758,19 +758,19 @@ describe('basic', function() {
         assert.strict.deepStrictEqual(vget[6], vans[6])
     })
 
-    //vans[18]~vans[22]為後續新增之selectByTime, 為不更動既有編號故接續於末號之後
+    //vans[18]~vans[22]為後續新增之selectByPk, 為不更動既有編號故接續於末號之後
     vans[18] = { time: new Date('2025-01-01T00:10:00.000Z'), name: 'rosemary(modify)', value: 113.98 }
-    it(`should get ${JSON.stringify(vans[18])} for selectByTime`, async function() {
+    it(`should get ${JSON.stringify(vans[18])} for selectByPk`, async function() {
         assert.strict.deepStrictEqual(vget[18], vans[18])
     })
 
     vans[19] = null
-    it(`should get ${JSON.stringify(vans[19])} for selectByTime by time not existed`, async function() {
+    it(`should get ${JSON.stringify(vans[19])} for selectByPk by pk not existed`, async function() {
         assert.strict.deepStrictEqual(vget[19], vans[19])
     })
 
     vans[20] = null
-    it(`should get ${JSON.stringify(vans[20])} for selectByTime by time invalid`, async function() {
+    it(`should get ${JSON.stringify(vans[20])} for selectByPk by pk invalid`, async function() {
         assert.strict.deepStrictEqual(vget[20], vans[20])
     })
 
@@ -877,12 +877,12 @@ describe('basic', function() {
     })
 
     vans[21] = { time: new Date('2025-01-01T00:01:00.000Z'), name: 'rosemary(modify)', value: 654.321 }
-    it(`should get ${JSON.stringify(vans[21])} for selectByTime (1st, fill cache)`, async function() {
+    it(`should get ${JSON.stringify(vans[21])} for selectByPk (1st, fill cache)`, async function() {
         assert.strict.deepStrictEqual(vget[21], vans[21])
     })
 
     vans[22] = vans[21]
-    it(`should get ${JSON.stringify(vans[22])} for selectByTime (2nd, cache hit)`, async function() {
+    it(`should get ${JSON.stringify(vans[22])} for selectByPk (2nd, cache hit)`, async function() {
         assert.strict.deepStrictEqual(vget[22], vans[22])
     })
 
@@ -954,7 +954,7 @@ describe('insert nInserted', function() {
         vget[7] = ss.length
 
         //同批重複者僅首筆入庫
-        let vdup = await wo.selectByTime('2025-02-01T00:05:00Z')
+        let vdup = await wo.selectByPk('2025-02-01T00:05:00Z')
         vget[8] = vdup.name
 
     })
@@ -1028,7 +1028,7 @@ describe('save concurrency', function() {
             wo.save({ time: tMerge, name: 'merge-name' }),
             wo.save({ time: tMerge, value: 99 }),
         ])
-        vget[1] = await wo.selectByTime(tMerge)
+        vget[1] = await wo.selectByPk(tMerge)
 
         //併發save對全新time, autoInsert僅一次且不得報錯
         let tNew = '2025-03-01T00:01:00Z'
@@ -1048,12 +1048,12 @@ describe('save concurrency', function() {
         let tDiff = '2025-03-01T00:03:00Z'
         await wo.insert({ time: tDiff, name: 'diff', value: 5 })
         vget[6] = await wo.save({ time: tDiff, value: 6 })
-        vget[7] = await wo.selectByTime(tDiff)
+        vget[7] = await wo.selectByPk(tDiff)
 
         //save(autoInsert=false)對不存在之time不得插入
         let tNone = '2025-03-01T00:04:00Z'
         vget[8] = await wo.save({ time: tNone, name: 'none' }, { autoInsert: false })
-        vget[9] = await wo.selectByTime(tNone)
+        vget[9] = await wo.selectByPk(tNone)
 
         //併發save(autoInsert=false)對既有time之不同欄位, 各欄位皆須保留且不得報錯
         let tUpd = '2025-03-01T00:05:00Z'
@@ -1063,7 +1063,7 @@ describe('save concurrency', function() {
             wo.save({ time: tUpd, value: 88 }, { autoInsert: false }),
         ])
         vget[10] = rsu.filter((v) => v[0].ok !== 1).length
-        vget[11] = await wo.selectByTime(tUpd)
+        vget[11] = await wo.selectByPk(tUpd)
 
     })
 
@@ -1148,7 +1148,7 @@ describe('spec compliance', function() {
         let tPart = '2025-04-01T00:00:00Z'
         await wo.insert({ time: tPart, name: 'peter', value: 5 })
         vget[1] = await wo.save({ time: tPart, value: 5 })
-        vget[2] = await wo.selectByTime(tPart)
+        vget[2] = await wo.selectByPk(tPart)
 
         //save單筆失敗不中斷整批, 失敗筆須帶err
         let tOk = '2025-04-01T00:01:00Z'
@@ -1302,6 +1302,138 @@ describe('spec compliance', function() {
 })
 
 
+describe('custom pk', function() {
+    let vans = {}
+    let vget = {}
+
+    before(async function() {
+        this.timeout(120000)
+
+        //wo, 以opt.pk指定主鍵欄位為code, 驗證select以外之五函數皆改以該欄位認定主鍵
+        let cl = 'custompk'
+        let wo = WOrm({
+            ...genOpt(cl),
+            pk: 'code',
+        })
+
+        //createTable, pk留空以驗證採用建構時之opt.pk
+        await wo.createTable(cl, null, {
+            code: 'abc',
+            name: 'abc',
+            value: 0.1,
+        }).catch(() => {})
+        await wo.delAll()
+
+        //insert以code認定主鍵
+        vget[1] = await wo.insert([
+            { code: 'c1', name: 'peter', value: 1 },
+            { code: 'c2', name: 'rosemary', value: 2 },
+        ])
+
+        //insert同code者跳過, 證明ON CONFLICT係以code為衝突目標
+        vget[2] = await wo.insert({ code: 'c1', name: 'other', value: 9 })
+
+        //selectByPk以code查找
+        vget[3] = await wo.selectByPk('c1')
+
+        //selectByPk未命中
+        vget[4] = await wo.selectByPk('notexist')
+
+        //save只給部份欄位且值不同, 未給之欄位須保留
+        vget[5] = await wo.save({ code: 'c1', value: 5 })
+        vget[6] = await wo.selectByPk('c1')
+
+        //save合併後內容相同不更新
+        vget[7] = await wo.save({ code: 'c1', value: 5 })
+
+        //save對不存在之code自動插入
+        vget[8] = await wo.save({ code: 'c3', name: 'sandler' })
+
+        //del以code刪除
+        vget[9] = await wo.del({ code: 'c2' })
+
+        //del未帶有效code
+        let rsd = await wo.del({ name: 'no-code' })
+        vget[10] = {
+            n: rsd[0].n,
+            nDeleted: rsd[0].nDeleted,
+            ok: rsd[0].ok,
+            hasErr: isestr(rsd[0].err),
+        }
+
+        //insert未帶有效code須reject
+        vget[11] = await wo.insert({ name: 'no-code' })
+            .then(() => 'resolved')
+            .catch(() => 'rejected')
+
+        //最終筆數, 僅存c1與c3
+        vget[12] = (await wo.select()).length
+
+    })
+
+    vans[1] = { n: 2, nInserted: 2, ok: 1 }
+    it(`should get ${JSON.stringify(vans[1])} for insert with custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[1], vans[1])
+    })
+
+    vans[2] = { n: 1, nInserted: 0, ok: 1 }
+    it(`should get ${JSON.stringify(vans[2])} for insert with existed custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[2], vans[2])
+    })
+
+    vans[3] = { code: 'c1', name: 'peter', value: 1 }
+    it(`should get ${JSON.stringify(vans[3])} for selectByPk with custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[3], vans[3])
+    })
+
+    vans[4] = null
+    it(`should get ${JSON.stringify(vans[4])} for selectByPk by custom pk not existed`, async function() {
+        assert.strict.deepStrictEqual(vget[4], vans[4])
+    })
+
+    vans[5] = [{ n: 1, nInserted: 0, nModified: 1, ok: 1 }]
+    it(`should get ${JSON.stringify(vans[5])} for save with custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[5], vans[5])
+    })
+
+    vans[6] = { code: 'c1', name: 'peter', value: 5 }
+    it(`should get ${JSON.stringify(vans[6])} for keeping field not given in save with custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[6], vans[6])
+    })
+
+    vans[7] = [{ n: 1, nInserted: 0, nModified: 0, ok: 1 }]
+    it(`should get ${JSON.stringify(vans[7])} for save with same content by custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[7], vans[7])
+    })
+
+    vans[8] = [{ n: 1, nInserted: 1, nModified: 0, ok: 1 }]
+    it(`should get ${JSON.stringify(vans[8])} for save(autoInsert) with custom pk not existed`, async function() {
+        assert.strict.deepStrictEqual(vget[8], vans[8])
+    })
+
+    vans[9] = [{ n: 1, nDeleted: 1, ok: 1 }]
+    it(`should get ${JSON.stringify(vans[9])} for del with custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[9], vans[9])
+    })
+
+    vans[10] = { n: 0, nDeleted: 0, ok: 0, hasErr: true }
+    it(`should get ${JSON.stringify(vans[10])} for del without valid custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[10], vans[10])
+    })
+
+    vans[11] = 'rejected'
+    it(`should get ${JSON.stringify(vans[11])} for insert without valid custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[11], vans[11])
+    })
+
+    vans[12] = 2
+    it(`should get ${JSON.stringify(vans[12])} for records after all operations with custom pk`, async function() {
+        assert.strict.deepStrictEqual(vget[12], vans[12])
+    })
+
+})
+
+
 //runProc, 另起行程對同一資料表操作, 用於驗證跨行程之原子性
 //子行程以--input-type=module執行, 並以pathToFileURL轉換src路徑, 避免專案路徑含非ASCII字元而無法import
 function runProc(tag, opt, mode, payload) {
@@ -1416,7 +1548,7 @@ describe('cross-process concurrency', function() {
         vget[5] = rpss.reduce((sum, v) => sum + (v.nInserted || 0), 0)
 
         //10欄須全數保留且值為各自行程之tag
-        let vSav = await woSav.selectByTime(tSav)
+        let vSav = await woSav.selectByPk(tSav)
         vget[6] = Array.from({ length: 10 }, (v, k) => k)
             .filter((k) => {
                 let tag = k <= 4 ? 'p1' : 'p2'