w-serv-orm 1.1.16 → 1.1.18

package/src/getMapOrm.mjs

@@ -16,6 +16,7 @@ import isestr from 'wsemi/src/isestr.mjs'
 import isnum from 'wsemi/src/isnum.mjs'
 import clearXSS from 'wsemi/src/clearXSS.mjs'
 import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
+import isOrmFail from './isOrmFail.mjs'
 
 
 function getMsgFail(msg, fails) {
@@ -423,6 +424,119 @@ function getRowId(row) {
 }
 
 
+function hasOwnerUserId(row) {
+    //寫入列上之userId是否為擁有者: 只認自有、可列舉之資料屬性且為非空字串(與getRowId同一認定, 不執行getter), 其餘(缺欄、空字串、非字串、繼承、不可列舉)視為未提供
+    if (typeof row !== 'object' || row === null) {
+        return false
+    }
+    let d = Object.getOwnPropertyDescriptor(row, 'userId')
+    return d !== undefined && d.enumerable && !isAcc(d) && typeof d.value === 'string' && d.value !== ''
+}
+
+
+//procOrm第5參數opt允許之鍵(R-ONLYMOD-01、R-KEEPUSER-01), 皆為布林
+const OPT_KEYS_PROC = ['mustExist', 'keepUserId']
+
+//mustExist之存在檢查每次select之主鍵數上限(R-ONLYMOD-01 規則 11)
+const EXIST_CHUNK = 1000
+
+
+function getOptProc(mode, opt) {
+    //procOrm之第5參數opt: 未給(undefined、null)為空設定; 否則須為純物件且只含mustExist、keepUserId(皆布林), 其餘鍵、存取器、非布林者於任何讀寫之前reject
+    //拼錯之鍵(如mustexist)若被靜默忽略, 會令只改不增失效而重新長出已刪之列(keepUserId拼錯則擁有者被覆寫成操作者), 故fail-closed; 訊息不回顯呼叫端之值
+    //mustExist只適用save與del; keepUserId只適用insert(save現行即不覆寫userId, mix之新增為內部步驟不開放); 先逐一驗型別再驗mode, 結果與鍵之次序無關
+    let bad = (err) => ({ err, mustExist: false, keepUserId: false })
+    if (opt === undefined || opt === null) {
+        return { err: null, mustExist: false, keepUserId: false }
+    }
+    if (!isPlainObj(opt)) {
+        return bad('invalid opt of procOrm, need an object')
+    }
+    for (let k of Reflect.ownKeys(opt)) {
+        if (OPT_KEYS_PROC.indexOf(k) < 0) {
+            return bad('invalid opt of procOrm, unsupported key')
+        }
+    }
+    let flags = { mustExist: false, keepUserId: false }
+    for (let key of OPT_KEYS_PROC) {
+        let d = Object.getOwnPropertyDescriptor(opt, key)
+        if (d !== undefined) {
+            if (isAcc(d) || typeof d.value !== 'boolean') {
+                return bad(`invalid opt of procOrm, ${key} needs a boolean`)
+            }
+            flags[key] = d.value
+        }
+    }
+    if (flags.mustExist && mode !== 'save' && mode !== 'del') {
+        return bad('invalid opt of procOrm, mustExist supports only save and del')
+    }
+    if (flags.keepUserId && mode !== 'insert') {
+        return bad('invalid opt of procOrm, keepUserId supports only insert')
+    }
+    return { err: null, mustExist: flags.mustExist, keepUserId: flags.keepUserId }
+}
+
+
+async function hasMissingRow(wo, rows) {
+    //rows(寫入或刪除之列)是否有任一列不存在於資料表(含無有效主鍵者: 無從識別即視為不存在), 以select(id $in)分批查詢; true為有缺
+    //只認自有可列舉之資料屬性之id(getRowId), 與寫入與刪除實際使用之id同一; 比對以字串形式(整數主鍵與其字串視為同一)
+    //此讀取為ORM之select, ORM開啟useCache時可能非新鮮, 屬部署前提(單一行程、同表同一ORM實例、不經快取), 見規則帳本R-ONLYMOD-01
+    let ids = []
+    let seen = new Set()
+    for (let v of (isArr(rows) ? rows : [rows])) {
+        let id = getRowId(v)
+        if (!((typeof id === 'string' && id !== '') || isIdNumFinite(id))) {
+            return true
+        }
+        if (!seen.has(String(id))) {
+            seen.add(String(id))
+            ids.push(id)
+        }
+    }
+    //分批查詢: 各w-orm-*共用之條件檢核(wsemi cvOrmFind)限$in之元素數(預設10000, 只可下調), 超過者整批reject; 每批EXIST_CHUNK個, 任一批有缺即止
+    for (let k = 0; k < ids.length; k += EXIST_CHUNK) {
+        let part = ids.slice(k, k + EXIST_CHUNK)
+        let rs = await wo.select({ id: { $in: part } })
+        let found = new Set(map(isArr(rs) ? rs : [], (r) => String(get(r, 'id'))))
+        if (part.some((id) => !found.has(String(id)))) {
+            return true
+        }
+    }
+    return false
+}
+
+
+function getItemsDupId(rows) {
+    //mustExist之del: 同批重複之有效主鍵(第2次以後出現者)之位置[{k}]; 無效主鍵者不計(由存在檢查處置)
+    //重複者若放行, 第1筆刪除後第2筆必未命中, 事後偵測雖會reject卻已刪除, 違反[任一列不存在即零刪除], 故於刪除之前整批拒絕
+    let seen = new Set()
+    let rs = []
+    let arr = isArr(rows) ? rows : [rows]
+    for (let k = 0; k < arr.length; k++) {
+        let id = getRowId(arr[k])
+        if (!((typeof id === 'string' && id !== '') || isIdNumFinite(id))) {
+            continue
+        }
+        let s = String(id)
+        if (seen.has(s)) {
+            rs.push({ k })
+        }
+        else {
+            seen.add(s)
+        }
+    }
+    return rs
+}
+
+
+function hasNoHit(r, keyDel) {
+    //ORM之逐筆結果是否有已正常處理(ok非0)而未命中者(n為0; keyDel非null者另認該鍵為0, 如del之nDeleted): 表鎖紀律被破壞(檢查後、寫入前列被他方刪除)時之事後偵測
+    return (isArr(r) ? r : [r]).some((x) => {
+        return x !== null && typeof x === 'object' && x.ok !== 0 && (x.n === 0 || (keyDel !== null && x[keyDel] === 0))
+    })
+}
+
+
 function firstBadIndex(a) {
     //陣列首個空洞或存取器索引, 回傳[索引, 'sparse'|'accessor'], 無則null; 成本為該索引之位置, 稀疏巨陣列於索引0即返回
     //索引為存取器者, 其後各步驟(each、map以array[index]讀取)會執行使用端程式並可每次回傳不同列(外審 sol F01)
@@ -922,7 +1036,7 @@ function setOwnData(o, k, v) {
 }
 
 
-function adjustData(ds, woName, userId, data, mode = 'save') { //mode: 'insert', 'save', 'insert+save'
+function adjustData(ds, woName, userId, data, mode = 'save', keepUserId = false) { //mode: 'insert', 'save', 'insert+save'; keepUserId只由insert傳true(R-KEEPUSER-01)
 
     //check
     if (!iseobj(ds)) {
@@ -946,9 +1060,12 @@ function adjustData(ds, woName, userId, data, mode = 'save') { //mode: 'insert',
     //userId, timeCreate
     if (mode.indexOf('insert') >= 0) {
 
-        //userId
+        //userId, keepUserId者(opt.keepUserId, 列上userId為擁有者而非建立者)逐列保留自有非空字串之userId, 其餘以操作者補; userIdUpdate不受影響, 恆為操作者
         if (keys.indexOf('userId') >= 0) {
             each(data, (v, k) => {
+                if (keepUserId && hasOwnerUserId(data[k])) {
+                    return
+                }
                 setOwnData(data[k], 'userId', userId)
             })
         }
@@ -1028,11 +1145,11 @@ function adjustData(ds, woName, userId, data, mode = 'save') { //mode: 'insert',
 }
 
 
-async function mapOrm(ds, woItems, userId, woName, mode, input) {
+async function mapOrm(ds, woItems, userId, woName, mode, input, opt) {
     //邊界保證(R-ERR-01 規則5): execMapOrm之檢查、轉型與ORM呼叫階段, 非字串之例外(RangeError、使用端物件之Proxy陷阱/toString拋錯、woItems之非ORM值等)
     //一律console.log原文後以固定字串reject, 不轉出例外物件與其拋出之值; 字串(各處之固定訊息)原樣轉出
     try {
-        return await execMapOrm(ds, woItems, userId, woName, mode, input)
+        return await execMapOrm(ds, woItems, userId, woName, mode, input, opt)
     }
     catch (e) {
         if (typeof e === 'string') {
@@ -1044,7 +1161,7 @@ async function mapOrm(ds, woItems, userId, woName, mode, input) {
 }
 
 
-async function execMapOrm(ds, woItems, userId, woName, mode, input) {
+async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
     //由woName自動綁定至woItems內的ORM物件
     let err = null
     let r
@@ -1065,6 +1182,12 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
     //idCast, 主鍵之有限數字以其字串形式處置(R-ID-02), 寫入、刪除與查詢條件共用同一判定
     let idCast = isIdCast(ds, woName)
 
+    //optProc, 第5參數opt(只改不增、刪除回報未命中, R-ONLYMOD-01), 於任何讀寫之前檢查
+    let optProc = getOptProc(mode, opt)
+    if (optProc.err !== null) {
+        return Promise.reject(optProc.err)
+    }
+
     if (mode === 'select') {
 
         //check, 條件若給予須為一般物件且不含自有__proto__鍵(R-INPUT-01 規則3、R-OBJ-01 規則3), 於轉型與查詢之前
@@ -1130,7 +1253,7 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
 
         //adjustData
         try {
-            input = adjustData(ds, woName, userId, input, mode)
+            input = adjustData(ds, woName, userId, input, mode, optProc.keepUserId)
         }
         catch (e) {
             console.log(`${woName}.adjustData catch`, e.toString())
@@ -1138,6 +1261,23 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
             return Promise.reject(err)
         }
 
+        //exist, 只改不增(opt.mustExist, R-ONLYMOD-01): 寫入之前檢查全部列(含補主鍵後)皆已存在, 任一列不存在(含無主鍵之列)即整批reject 'rowNotFound'而不寫入任何一筆
+        //檢查與寫入非原子, 呼叫端須已持有該表之表鎖(withTabLocks、guardWrite)
+        if (mode === 'save' && optProc.mustExist) {
+            let missing = await hasMissingRow(wo, input)
+                .catch((msg) => {
+                    console.log(`${woName}.save exist check catch`, msg)
+                    err = 'failed to save data'
+                })
+            if (isestr(err)) {
+                return Promise.reject(err)
+            }
+            if (missing) {
+                console.log(`${woName}.save row not found`)
+                return Promise.reject('rowNotFound')
+            }
+        }
+
         //save
         if (mode === 'insert') {
             r = await wo.insert(input)
@@ -1147,7 +1287,8 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
                 })
         }
         else if (mode === 'save') {
-            r = await wo.save(input)
+            //只改不增者轉傳autoInsert:false(各ORM於未命中時不寫入); 其餘維持單參數呼叫
+            r = await (optProc.mustExist ? wo.save(input, { autoInsert: false }) : wo.save(input))
                 .catch((msg) => {
                     console.log(`${woName}.save catch`, msg)
                     err = 'failed to save data'
@@ -1159,14 +1300,31 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
             return Promise.reject(err)
         }
 
+        //check, insert之錯誤皆屬整批性而reject, 其回傳為聚合物件且ok恆為1; 聚合結果ok為0或逐筆陣列任一筆ok為0者(ORM違約, 見isOrmFail)視為失敗, 不可回成功, 以固定字串整批reject
+        if (mode === 'insert' && isOrmFail(r)) {
+            console.log(`${woName}.insert fail`, r)
+            return Promise.reject('failed to insert data')
+        }
+
         //check, save單筆失敗時整批仍resolve並以該筆ok為0回報, 須逐筆檢查
-        //insert之錯誤皆屬整批性而reject, 其回傳為聚合物件而非逐筆陣列, 故不須檢查
         if (mode === 'save') {
             let fails = getItemsFail(r, input)
             if (size(fails) > 0) {
                 console.log(`${woName}.save fail`, fails)
                 return Promise.reject(getMsgFail('failed to save data', getItemsFail(r, inputOrig)))
             }
+
+            //check, 回傳聚合物件而ok為0(非契約形狀)者無從逐筆列出, 仍視為失敗, 固定字串reject(R-ORM-RESULT-01); 陣列形之失敗已於上方列出
+            if (isOrmFail(r)) {
+                console.log(`${woName}.save fail`, r)
+                return Promise.reject('failed to save data')
+            }
+
+            //check, 只改不增者之事後偵測: 逐筆n為0表檢查後、寫入前該列被他方刪除(表鎖紀律被破壞), 已寫入之筆無從回復, 仍回報rowNotFound
+            if (optProc.mustExist && hasNoHit(r, null)) {
+                console.log(`${woName}.save row not found after check`)
+                return Promise.reject('rowNotFound')
+            }
         }
 
         //僅回傳id避免大量數據時造成負擔
@@ -1195,6 +1353,31 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
             input = castIdRows(input)
         }
 
+        //exist, 刪除回報未命中(opt.mustExist, R-ONLYMOD-01): 刪除之前檢查全部列皆存在, 任一列不存在(含無主鍵之列)即整批reject 'rowNotFound'而不刪除任何一筆
+        //檢查與刪除非原子, 呼叫端須已持有該表之表鎖(withTabLocks、guardWrite)
+        if (optProc.mustExist) {
+
+            //check, 同批重複主鍵整批拒絕, 訊息列其位置而不回顯主鍵(同R-MIX-01)
+            let failsDup = getItemsDupId(input)
+            if (size(failsDup) > 0) {
+                console.log(`${woName}.del duplicate id`, failsDup)
+                return Promise.reject(getMsgFail('invalid input of del, duplicate id', failsDup))
+            }
+
+            let missing = await hasMissingRow(wo, input)
+                .catch((msg) => {
+                    console.log(`${woName}.del exist check catch`, msg)
+                    err = 'failed to delete data'
+                })
+            if (isestr(err)) {
+                return Promise.reject(err)
+            }
+            if (missing) {
+                console.log(`${woName}.del row not found`)
+                return Promise.reject('rowNotFound')
+            }
+        }
+
         //del
         r = await wo.del(input)
             .catch((msg) => {
@@ -1209,6 +1392,17 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
                 console.log(`${woName}.del fail`, fails)
                 err = getMsgFail('failed to delete data', fails)
             }
+            else if (isOrmFail(r)) {
+                //回傳聚合物件而ok為0(非契約形狀)者無從逐筆列出, 仍視為失敗, 固定字串(R-ORM-RESULT-01)
+                console.log(`${woName}.del fail`, r)
+                err = 'failed to delete data'
+            }
+        }
+
+        //check, 刪除回報未命中者之事後偵測: 逐筆nDeleted或n為0表檢查後、刪除前該列被他方刪除(表鎖紀律被破壞), 已刪除之筆無從回復, 仍回報rowNotFound
+        if (!isestr(err) && optProc.mustExist && hasNoHit(r, 'nDeleted')) {
+            console.log(`${woName}.del row not found after check`)
+            err = 'rowNotFound'
         }
 
     }
@@ -1228,6 +1422,12 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
                 err = 'failed to delete data'
             })
 
+        //check, delAll契約為聚合物件且ok恆為1(錯誤皆整批reject); ok為0或逐筆陣列任一筆ok為0者(ORM違約, 見isOrmFail)視為失敗, 不可回成功(R-ORM-RESULT-01)
+        if (!isestr(err) && isOrmFail(r)) {
+            console.log(`${woName}.delAll fail`, r)
+            err = 'failed to delete data'
+        }
+
     }
     else if (mode === 'mix') {
 
@@ -1362,7 +1562,7 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
             }
 
             //insert
-            await wo.insert(add)
+            let rsAdd = await wo.insert(add)
                 .catch((msg) => {
                     console.log(`${woName}.insert catch`, msg)
                     err = 'failed to insert data'
@@ -1373,6 +1573,12 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
                 return Promise.reject(err)
             }
 
+            //check, 同單獨insert, 回報失敗者(isOrmFail)視為整批性失敗, 立即reject, 後續步驟不執行
+            if (isOrmFail(rsAdd)) {
+                console.log(`${woName}.insert fail`, rsAdd)
+                return Promise.reject('failed to insert data')
+            }
+
             //r
             rt = map(add, (v) => {
                 return { id: v.id } //僅回傳id避免大量數據時造成負擔
@@ -1401,6 +1607,11 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
                 console.log(`${woName}.del fail`, fails)
                 msgsFail.push(getMsgFail('failed to delete data', fails))
             }
+            else if (isOrmFail(rs)) {
+                //回傳聚合物件而ok為0(非契約形狀)者無從逐筆列出, 視為該步驟整批性失敗, 立即reject, 後續步驟不執行(R-ORM-RESULT-01)
+                console.log(`${woName}.del fail`, rs)
+                return Promise.reject('failed to delete data')
+            }
 
             //r
             rt = map(del, (v) => {
@@ -1436,6 +1647,11 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
                 console.log(`${woName}.save fail`, fails)
                 msgsFail.push(getMsgFail('failed to update data', getItemsFail(rs, diffOrig)))
             }
+            else if (isOrmFail(rs)) {
+                //同上, 回傳聚合物件而ok為0(非契約形狀)者立即reject(R-ORM-RESULT-01)
+                console.log(`${woName}.save fail`, rs)
+                return Promise.reject('failed to update data')
+            }
 
             //r
             rt = map(diff, (v) => {
@@ -1465,11 +1681,12 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input) {
 
 
 function getMapOrm(ds, woItems) {
-    //每次呼叫各自綁定ds與woItems並回傳新函數, 令同一行程內之多個實例互不干擾; 回傳函數之參數形狀維持(userId, woName, mode, input)
-    return async (userId, woName, mode, input) => {
-        return mapOrm(ds, woItems, userId, woName, mode, input)
+    //每次呼叫各自綁定ds與woItems並回傳新函數, 令同一行程內之多個實例互不干擾; 回傳函數之參數形狀為(userId, woName, mode, input, opt), 前四個維持, opt為選用(R-ONLYMOD-01)
+    return async (userId, woName, mode, input, opt) => {
+        return mapOrm(ds, woItems, userId, woName, mode, input, opt)
     }
 }
 
 
+export { getOptProc }
 export default getMapOrm

package/src/getProc.mjs

@@ -2,6 +2,7 @@ import iseobj from 'wsemi/src/iseobj.mjs'
 import pmSeries from 'wsemi/src/pmSeries.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import checkOptRemoved from './checkOptRemoved.mjs'
+import { getOptProc } from './getMapOrm.mjs'
 
 
 function addFun(fs, f, name, useGuard = false) {
@@ -28,11 +29,18 @@ function addFun(fs, f, name, useGuard = false) {
 }
 
 
-async function procOrm(st, userId, woName, mode, input) {
+async function procOrm(st, userId, woName, mode, input, opt) {
     //封裝mapOrm, 依序執行擴充檢查、前處理、ORM操作與後處理, st為該實例之狀態
     //不做授權: 不檢查使用者亦不依使用者過濾數據, userId只供寫入稽核欄位與交給擴充函數; 開放給前端時須由開放處負責授權
     //st.mapOrm已於getProc建立st時驗證為函數, 且st不外露, 故此處不再檢查
 
+    //opt(第5參數: mustExist, R-ONLYMOD-01; keepUserId, R-KEEPUSER-01)先於任何擴充函數驗證: 無效之opt以固定字串拒收, 不得先執行擴充函數(其可能有寫入等副作用, 且check拋錯會遮蔽固定拒收字串);
+    //mapOrm內仍會再驗(直接使用getMapOrm者), 結果相同; opt不交給擴充函數(其參數物件形狀維持)
+    let optProc = getOptProc(mode, opt)
+    if (optProc.err !== null) {
+        return Promise.reject(optProc.err)
+    }
+
     //funChecks, 擴充檢查, 提供給各 mOrm[OOO].mjs 檢查
     await pmSeries(st.funChecks, (v) => {
         return v({ woName, userId, mode, input })
@@ -50,7 +58,8 @@ async function procOrm(st, userId, woName, mode, input) {
     }
 
     //output
-    let output = await st.mapOrm(userId, woName, mode, input)
+    //opt(第5參數, R-ONLYMOD-01、R-KEEPUSER-01)交給mapOrm使用
+    let output = await st.mapOrm(userId, woName, mode, input, opt)
 
     //funPostProcessing, 擴充後處理output, 提供給各 mOrm[OOO].mjs 後處理
     //逐一呼叫, 各後處理皆收新建之參數物件, output為前一個之回傳值, 回傳值成為新output; 迭代前先取快照
@@ -96,8 +105,8 @@ function getProc(mapOrm, opt = {}) {
             //由外部添加擴充後置處理函數
             addFun(st.funPostProcessing, f, 'addFunPostProcessing')
         },
-        procOrm: async (userId, woName, mode, input) => {
-            return procOrm(st, userId, woName, mode, input)
+        procOrm: async (userId, woName, mode, input, opt) => {
+            return procOrm(st, userId, woName, mode, input, opt)
         },
     }
 }

package/src/isOrmFail.mjs

@@ -0,0 +1,30 @@
+import size from 'lodash-es/size.js'
+import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
+
+
+/**
+ * 判斷ORM寫入類函數(insert、save、del、delAll)之回傳結果是否回報失敗
+ *
+ * 依w-orm系列規格，insert與delAll回傳聚合物件且ok恆為1，save與del回傳逐筆陣列，錯誤皆整批reject；單筆失敗者(save、del)於該筆以ok為0回報。
+ * 本函數不論函數與形狀一律判讀：回傳為聚合物件(非null、非陣列之物件)而ok為0者(ORM違約或他種後端)視為失敗；
+ * 回傳為逐筆陣列而任一筆ok為0者(同getItemsFail之判讀)視為失敗。
+ * 其餘(undefined、null、無ok鍵之物件、空陣列、元素皆ok非0或非物件之陣列、ok為1含略過既有主鍵或未命中之n為0)不視為失敗，維持舊行為。
+ * 讀取函數(select)之回傳為數據列，列內欄位可能名為ok，不得以本函數判讀。
+ * 供procOrm之寫入類各模式、mix之各步驟、備份還原與測試數據寫入共用。
+ *
+ * @param {*} r 輸入ORM寫入類函數之回傳結果
+ * @returns {Boolean} 回傳是否回報失敗
+ */
+function isOrmFail(r) {
+
+    //check, 逐筆陣列
+    if (Array.isArray(r)) {
+        return size(getItemsFail(r, [])) > 0
+    }
+
+    //check, 聚合物件
+    return r !== null && typeof r === 'object' && r.ok === 0
+}
+
+
+export default isOrmFail