w-orm-reladb 1.1.6 → 1.1.7

package/src/cvFind.mjs

@@ -0,0 +1,789 @@
+import Sequelize from 'sequelize'
+
+
+//查詢條件(find)之轉譯, 供select與delAll共用, 令同一find於兩函數由同一SQL謂詞決定命中
+//
+//原select內之cvObj以lodash之each迭代並以Op[k]直譯$鍵, 有下列缺陷而不得供破壞性之delAll使用:
+//  1. 不支援之運算子成為鍵'undefined', 運算子物件被交給sequelize之欄位型別stringify:
+//     FLOAT成'NaN'、INTEGER成'[object Object]'、DATE成本地今日00:00, 致靜默無命中或刪錯列
+//  2. 具數值length之物件被當成陣列樣迭代而丟棄全部條件(回全表)、Symbol鍵被丟棄
+//  3. $regex轉LIKE而未跳脫萬用字元, 欄位層$not遇運算子物件被轉為!=
+//本模組改以白名單轉譯, 凡不能保證語意者一律拋錯, 規則見CLAUDE_rulebook.md之R1–R6;
+//主鍵值之正規化(normPk)亦屬本模組, 供主鍵函數與主鍵欄條件共用, 規則見R8
+
+
+//Op
+let Op = Sequelize.Op
+
+
+//sequelize之運算子Symbol全集, 非其成員之Symbol會被sequelize靜默丟棄, 故一律拒收
+let setOp = new Set(Object.values(Op))
+
+
+//比較運算子, 值須為純量(null僅$eq與$ne)
+let mCmp = {
+    $eq: Op.eq,
+    $ne: Op.ne,
+    $gt: Op.gt,
+    $gte: Op.gte,
+    $lt: Op.lt,
+    $lte: Op.lte,
+}
+
+
+//sequelize之Symbol運算子對應之$名稱, 令呼叫端以Symbol給條件時亦經同一檢核與轉譯
+let mSymCmp = new Map([
+    [Op.eq, '$eq'],
+    [Op.ne, '$ne'],
+    [Op.gt, '$gt'],
+    [Op.gte, '$gte'],
+    [Op.lt, '$lt'],
+    [Op.lte, '$lte'],
+    [Op.in, '$in'],
+    [Op.notIn, '$nin'],
+    [Op.not, '$not'],
+])
+
+
+//欄位層不接受之Symbol: 邏輯運算子於sequelize欄位層會提前返回而丟棄同層其他條件
+let setSymFieldNo = new Set([Op.and, Op.or])
+
+
+//LIKE之跳脫字元, 選用於各方言字串常值內皆無特殊意義者, 令ESCAPE子句不需依方言跳脫
+let cEsc = '!'
+
+
+//巢狀深度上限, 防循環參照與過深之條件
+let nDepthMax = 32
+
+
+//欄位型別分類, 以sequelize之型別類別判定(各方言之型別皆繼承之), 另以type.key補判
+//註: DataTypes.DOUBLE之key為'DOUBLE PRECISION', 只比對key會漏判而不檢型別
+let DT = Sequelize.DataTypes
+let tpsStr = ['STRING', 'TEXT', 'CHAR', 'UUID', 'CITEXT']
+let tpsInt = ['INTEGER', 'BIGINT', 'SMALLINT', 'MEDIUMINT', 'TINYINT']
+let tpsNum = ['FLOAT', 'REAL', 'DOUBLE', 'DOUBLE PRECISION', 'DECIMAL', 'NUMBER']
+let tpsDate = ['DATE']
+let tpsDateOnly = ['DATEONLY']
+let tpsBool = ['BOOLEAN']
+
+
+//嚴格十進位之數值字串, 不收前後空白與0x、0b、0o等寫法(sqlite不認而當成文字比較)
+//整數欄只收整數寫法: mssql轉'2.5'、'1e3'、'5.'為int時失敗, sqlite卻以'1e3'命中1000、'5.'命中5, 兩方言分歧
+//其他數值欄不收指數與尾端小數點: mssql轉'1e3'為DECIMAL時失敗
+let reInt = /^[+-]?\d+$/
+let reNum = /^[+-]?(\d+(\.\d+)?|\.\d+)$/
+
+
+//標準整數寫法, 即String(Number(s))===s之整數字串(無正號、前導零與-0), 供主鍵正規化
+let reIntStd = /^(0|-?[1-9]\d*)$/
+
+
+//帶時區之ISO 8601日期時間字串; 無時區者依主機時區解析而結果隨主機而變, 故不收
+let reIsoTz = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(:(\d{2})(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/
+
+
+//日期字串, 供DATEONLY欄
+let reDateOnly = /^(\d{4})-(\d{2})-(\d{2})$/
+
+
+/**
+ * 判定年月日是否為曆法上存在之日期, 如2026-02-30不存在
+ *
+ * @ignore
+ */
+function isCalendarDate(y, m, d) {
+    let t = new Date(Date.UTC(Number(y), Number(m) - 1, Number(d)))
+    return t.getUTCFullYear() === Number(y) && t.getUTCMonth() === Number(m) - 1 && t.getUTCDate() === Number(d)
+}
+
+
+/**
+ * 拋出條件錯誤
+ *
+ * @ignore
+ */
+function err(msg, path) {
+    throw new Error(`invalid find: ${msg}${path ? ` at [${path}]` : ''}`)
+}
+
+
+/**
+ * 是否為一般物件: 原型為Object.prototype或null者
+ * 註: 不以toString判定, 因帶Symbol.toStringTag之一般物件會被誤判為非物件, 而class實例、Object.create(proto)會被誤判為一般物件,
+ * 其條件可能放在原型上而取不到自有鍵, 被當成{}而刪全表
+ *
+ * @ignore
+ */
+function isPlainObj(v) {
+    if (v === null || typeof v !== 'object') {
+        return false
+    }
+    let p = Object.getPrototypeOf(v)
+    return p === Object.prototype || p === null
+}
+
+
+/**
+ * 恆真與恆假之謂詞, 以明確之SQL表示, 不以空條件表示
+ * 註: sequelize會把空條件(如{}、空$and)於OR、NOT內濾除, 致恆真被當成不存在而改變語意(如$nor:[{}]成全部)
+ *
+ * @ignore
+ */
+function sqlTrue() {
+    return Sequelize.literal('1 = 1')
+}
+function sqlFalse() {
+    return Sequelize.literal('1 = 0')
+}
+
+
+/**
+ * 取欄位之型別分類: str、int、num、date、bool, 未知或非上列者為any
+ *
+ * @param {Object} attrs 輸入model之rawAttributes
+ * @param {String} field 輸入欄位名
+ * @returns {String} 回傳型別分類字串
+ */
+function getColKind(attrs, field) {
+    if (!attrs || !Object.prototype.hasOwnProperty.call(attrs, field)) {
+        return 'any'
+    }
+    let t = attrs[field] && attrs[field].type
+    let k = t && t.key
+    if (t instanceof DT.INTEGER || tpsInt.indexOf(k) >= 0) {
+        return 'int'
+    }
+    if (t instanceof DT.NUMBER || tpsNum.indexOf(k) >= 0) {
+        return 'num'
+    }
+    if (t instanceof DT.DATEONLY || tpsDateOnly.indexOf(k) >= 0) {
+        return 'dateonly'
+    }
+    if (t instanceof DT.DATE || tpsDate.indexOf(k) >= 0) {
+        return 'date'
+    }
+    if (t instanceof DT.BOOLEAN || tpsBool.indexOf(k) >= 0) {
+        return 'bool'
+    }
+    if (t instanceof DT.STRING || t instanceof DT.TEXT || t instanceof DT.UUID || t instanceof DT.CITEXT || tpsStr.indexOf(k) >= 0) {
+        return 'str'
+    }
+    return 'any'
+}
+
+
+/**
+ * 取DECIMAL欄之scale, 未指定者為0(mssql之DECIMAL預設為(18,0)), 非DECIMAL者為null
+ *
+ * @param {Object} attrs 輸入model之rawAttributes
+ * @param {String} field 輸入欄位名
+ * @returns {Number|null} 回傳scale
+ */
+function getColScale(attrs, field) {
+    if (!attrs || !Object.prototype.hasOwnProperty.call(attrs, field)) {
+        return null
+    }
+    let t = attrs[field] && attrs[field].type
+    if (!(t instanceof DT.DECIMAL)) {
+        return null
+    }
+    return typeof t._scale === 'number' ? t._scale : 0
+}
+
+
+/**
+ * 判定純量是否符合欄位型別分類
+ * 註: sqlite比較不同型別時不報錯而依型別排序, 如INTEGER < 'abc'、DATE < 'garbage'恆為真,
+ * 若放行則delAll會刪除全部非NULL之列; mssql則轉型失敗而reject, 兩方言分歧, 故一律於送出前判定
+ * 註: 整數欄之數值須在安全整數範圍內, 超出者已失精度而會比對到相鄰之值; 精確之大整數以數值字串給予
+ *
+ * @param {*} v 輸入純量
+ * @param {String} kind 輸入欄位型別分類
+ * @returns {Boolean} 回傳是否相符
+ */
+function isKindOk(v, kind, scale = null) {
+    if (kind === 'str') {
+        return typeof v === 'string'
+    }
+    if (kind === 'int' || kind === 'num') {
+        if (typeof v === 'number') {
+            if (!Number.isFinite(v)) {
+                return false
+            }
+            if (kind === 'int' && Math.abs(v) > Number.MAX_SAFE_INTEGER) {
+                return false
+            }
+            return true
+        }
+        if (typeof v !== 'string' || !(kind === 'int' ? reInt : reNum).test(v)) {
+            return false
+        }
+        //DECIMAL欄之字串小數位不得多於欄位之scale(未指定為0): mssql把字串轉為欄位型別時四捨五入, '1.254'會命中1.25
+        if (scale !== null) {
+            let k = v.indexOf('.')
+            let nd = k >= 0 ? v.length - k - 1 : 0
+            return nd <= scale
+        }
+        return true
+    }
+    if (kind === 'date') {
+        if (v instanceof Date) {
+            return !isNaN(v.getTime())
+        }
+        if (typeof v === 'number') {
+            //須在Date可表示之範圍(±8.64e15毫秒)內, 超出者被stringify為'Invalid date'而以文字比較, sqlite會命中全部日期列
+            return Number.isFinite(v) && !isNaN(new Date(v).getTime())
+        }
+        if (typeof v !== 'string') {
+            return false
+        }
+        let m = v.match(reIsoTz)
+        return m !== null && isCalendarDate(m[1], m[2], m[3]) && !isNaN(Date.parse(v.replace(' ', 'T')))
+    }
+    if (kind === 'dateonly') {
+        //Date物件依主機時區取日期而結果隨主機而變, 故只收日期字串
+        if (typeof v !== 'string') {
+            return false
+        }
+        let m = v.match(reDateOnly)
+        return m !== null && isCalendarDate(m[1], m[2], m[3])
+    }
+    if (kind === 'bool') {
+        return typeof v === 'boolean' || v === 0 || v === 1
+    }
+    return true
+}
+
+
+/**
+ * 拆包裝物件: new String(x)與new Number(x)取原始值, 令其與原始值同處置(同w-orm-mdb)
+ *
+ * @ignore
+ */
+function unwrap(v) {
+    if (v !== null && typeof v === 'object') {
+        let c = Object.prototype.toString.call(v)
+        if (c === '[object String]' || c === '[object Number]') {
+            return v.valueOf()
+        }
+    }
+    return v
+}
+
+
+/**
+ * 依主鍵欄型別分類正規化主鍵值, 與w-orm-mdb之normPk同一規則(見CLAUDE_rulebook.md之R8)
+ *
+ * 註: kind為'ok'(v為正規化後之值)、'invalid'(未給或非有效值, 依規格T6處置)、'mismatch'(與主鍵欄型別不符)
+ * 註: 字串類主鍵欄之有限數字以String(v)處置, 與w-serv-orm、w-orm-mdb一致
+ * 註: 整數類主鍵欄收安全整數, 以及標準整數寫法之字串(String(Number(s))===s)而轉為數值;
+ * 超出安全整數之標準整數寫法字串保留為字串(精確值, 供BIGINT), 超出安全整數之數值已失精度而會命中相鄰主鍵, 視為型別不符;
+ * 非整數之數值與其他字串(如'012'、'1e1'、'0x1')寫入時會被資料庫轉型而改變鍵, 視為型別不符
+ * 註: 其他數值類主鍵欄收有限數值與標準數字字串(轉為數值), 其他字串視為型別不符;
+ * DECIMAL主鍵欄之值小數位多於scale者寫入時會被四捨五入而改變鍵(mssql之DECIMAL(10,2)存1.254為1.25, insert回報已存在而selectByPk(1.254)回null), 視為型別不符
+ * 註: 其他型別之主鍵欄不檢型別, 收非空字串與有限數值
+ * 註: NaN、±Infinity、空字串、布林、物件、陣列、Date、BigInt、null、undefined為無效
+ *
+ * @param {*} v 輸入主鍵值
+ * @param {String} kind 輸入主鍵欄之型別分類, 取自getColKind
+ * @param {Number|null} [scale=null] 輸入DECIMAL主鍵欄之scale, 取自getColScale, 非DECIMAL者為null
+ * @returns {Object} 回傳{kind,v}
+ */
+function normPk(v, kind, scale = null) {
+
+    //unwrap
+    v = unwrap(v)
+
+    //string
+    if (typeof v === 'string') {
+        if (v === '') {
+            return { kind: 'invalid' }
+        }
+        if (kind === 'int') {
+            if (!reIntStd.test(v)) {
+                return { kind: 'mismatch' }
+            }
+            let n = Number(v)
+            return { kind: 'ok', v: Number.isSafeInteger(n) ? n : v }
+        }
+        if (kind === 'num') {
+            let n = Number(v)
+            if (!Number.isFinite(n) || String(n) !== v) {
+                return { kind: 'mismatch' }
+            }
+            v = n //續由數值判定scale
+        }
+        else {
+            return { kind: 'ok', v }
+        }
+    }
+
+    //number
+    if (typeof v === 'number') {
+        if (!Number.isFinite(v)) {
+            return { kind: 'invalid' }
+        }
+        if (kind === 'str') {
+            return { kind: 'ok', v: String(v) }
+        }
+        if (kind === 'int' && !Number.isSafeInteger(v)) {
+            return { kind: 'mismatch' }
+        }
+        if (kind === 'num' && scale !== null && Number(v.toFixed(scale)) !== v) {
+            return { kind: 'mismatch' }
+        }
+        return { kind: 'ok', v }
+    }
+
+    return { kind: 'invalid' }
+}
+
+
+/**
+ * 檢核純量值: 字串、有限數值、布林、有效Date、Buffer, 以及允許時之null; 並須符合欄位型別分類
+ * 註: 物件、陣列等不得交sequelize之型別stringify, 否則FLOAT成'NaN'、INTEGER成'[object Object]'、DATE成本地今日00:00而誤刪
+ * 註: 主鍵欄(pk為true)之字串類、整數類與其他數值類以normPk正規化後回傳(如字串類主鍵欄之123即'123'), 無效或型別不符者拒收,
+ * 令select與delAll對主鍵之認定與selectByPk、del等主鍵函數一致; 非主鍵欄不轉型
+ *
+ * @ignore
+ */
+function chkScalar(v, path, allowNull, kind = 'any', scale = null, pk = false) {
+    if (v === null) {
+        if (allowNull) {
+            return v
+        }
+        err('null is not allowed here', path)
+    }
+    let ok = false
+    if (typeof v === 'string' || typeof v === 'boolean') {
+        ok = true
+    }
+    else if (typeof v === 'number') {
+        if (!Number.isFinite(v)) {
+            err(`number must be finite, got [${v}]`, path)
+        }
+        ok = true
+    }
+    else if (v instanceof Date) {
+        if (isNaN(v.getTime())) {
+            err('invalid Date', path)
+        }
+        ok = true
+    }
+    else if (Buffer.isBuffer(v)) {
+        ok = kind === 'any'
+    }
+    if (!ok) {
+        err(`value must be a string, finite number, boolean, Date or null, got [${Object.prototype.toString.call(v)}]`, path)
+    }
+    if (pk && (kind === 'str' || kind === 'int' || kind === 'num')) {
+        let r = normPk(v, kind, scale)
+        if (r.kind === 'ok') {
+            return r.v
+        }
+        err(`value [${String(v)}] does not match column type [${kind}]${scale !== null ? ` with scale [${scale}]` : ''}`, path)
+    }
+    if (!isKindOk(v, kind, scale)) {
+        err(`value [${String(v)}] does not match column type [${kind}]${scale !== null ? ` with scale [${scale}]` : ''}`, path)
+    }
+    return v
+}
+
+
+/**
+ * 取陣列之各元素, 稀疏陣列之洞與undefined一律拒收
+ * 註: forEach與map會略過洞, 洞若被略過則$and之子式消失而成恆真
+ *
+ * @ignore
+ */
+function getItems(arr, path) {
+    let rs = []
+    for (let i = 0; i < arr.length; i++) {
+        if (!(i in arr) || arr[i] === undefined) {
+            err('array must not contain holes or undefined', `${path}.${i}`)
+        }
+        rs.push(arr[i])
+    }
+    return rs
+}
+
+
+/**
+ * 檢核sequelize原生Symbol運算子之值: 純量、純量陣列或sequelize之literal/fn/col
+ * 註: 原生寫法由呼叫端自負語意, 但仍不得把物件交sequelize之型別stringify
+ *
+ * @ignore
+ */
+function chkRawSym(x, path, kind, scale, pk) {
+    if (x instanceof Sequelize.Utils.SequelizeMethod) {
+        return x
+    }
+    if (Array.isArray(x)) {
+        return getItems(x, path).map((y, i) => (y instanceof Sequelize.Utils.SequelizeMethod ? y : chkScalar(y, `${path}.${i}`, true, kind, scale, pk)))
+    }
+    return chkScalar(x, path, true, kind, scale, pk)
+}
+
+
+/**
+ * 將正規式來源轉為字面字串, 僅接受無未跳脫元字元者
+ *
+ * @ignore
+ */
+function regexToLiteral(src, path) {
+    let r = ''
+    let meta = '\\^$.|?*+()[]{}/'
+    for (let i = 0; i < src.length; i++) {
+        let c = src[i]
+        if (c === '\\') {
+            let n = src[i + 1]
+            if (n !== undefined && meta.indexOf(n) >= 0) {
+                r += n
+                i++
+                continue
+            }
+            err(`$regex supports literal substrings only, escape [\\${n === undefined ? '' : n}] is not supported`, path)
+        }
+        if (meta.indexOf(c) >= 0) {
+            err(`$regex supports literal substrings only, unescaped metacharacter [${c}] is not supported`, path)
+        }
+        r += c
+    }
+    if (r.indexOf('\u0000') >= 0) {
+        err('$regex must not contain NUL', path)
+    }
+    return r
+}
+
+
+/**
+ * 正規化正規式旗標, 僅接受i; '$i'為既有寫法, 過渡期視同i
+ *
+ * @ignore
+ */
+function normFlags(fs, path) {
+    if (fs === undefined || fs === null || fs === '') {
+        return false
+    }
+    if (typeof fs !== 'string') {
+        err('$options must be a string', path)
+    }
+    let s = fs === '$i' ? 'i' : fs
+    for (let c of s) {
+        if (c !== 'i') {
+            err(`$options/flags supports [i] only, got [${fs}]`, path)
+        }
+    }
+    return s.indexOf('i') >= 0
+}
+
+
+/**
+ * 產生LIKE子字串條件, 跳脫萬用字元並帶ESCAPE子句; 不分大小寫時兩側皆以LOWER處理
+ * 註: sqlite之LOWER只折疊ASCII, 故sqlite下給i而字面含非ASCII之大小寫字母者拒收, 不宣稱做不到之語意
+ *
+ * @ignore
+ */
+function cvRegex(field, re, options, path, ctx, kind) {
+    if (kind !== 'str' && kind !== 'any') {
+        err(`$regex requires a string column, column type is [${kind}]`, path)
+    }
+    let src
+    let ci
+    if (re instanceof RegExp) {
+        if (options !== undefined) {
+            err('$options can not be used with a RegExp $regex', path)
+        }
+        let flags = re.flags.replace(/[gu]/g, '') //g、u不影響是否命中
+        src = re.source === '(?:)' ? '' : re.source //new RegExp('')之source為(?:), 即空字串
+        ci = normFlags(flags, path)
+    }
+    else if (typeof re === 'string') {
+        src = re
+        ci = normFlags(options, path)
+    }
+    else {
+        err('$regex must be a string or RegExp', path)
+    }
+    let lit = regexToLiteral(src, path)
+    if (ci && ctx.dialect === 'sqlite') {
+        for (let c of lit) {
+            if (c.charCodeAt(0) > 127 && c.toLowerCase() !== c.toUpperCase()) {
+                err(`$regex with i supports ASCII letters only on sqlite, got [${c}]`, path)
+            }
+        }
+    }
+    let pat = `%${lit.replace(/[!%_[]/g, (c) => `${cEsc}${c}`)}%`
+    let q = ctx.escape(pat)
+    if (ci) {
+        //LOWER內須為資料庫之實際欄名, model之屬性名與欄名可不同
+        let col = ctx.attrs && ctx.attrs[field] && ctx.attrs[field].field ? ctx.attrs[field].field : field
+        return Sequelize.where(Sequelize.fn('LOWER', Sequelize.col(col)), Op.like, Sequelize.literal(`LOWER(${q}) ESCAPE '${cEsc}'`))
+    }
+    return { [field]: { [Op.like]: Sequelize.literal(`${q} ESCAPE '${cEsc}'`) } }
+}
+
+
+/**
+ * $in與$nin, 含null者另以IS [NOT] NULL補上, 與{欄位:null}一致; 空集合以恆假/恆真表示
+ *
+ * @ignore
+ */
+function cvIn(field, arr, path, neg, kind, scale, pk) {
+    if (!Array.isArray(arr)) {
+        err(`${neg ? '$nin' : '$in'} must be an array`, path)
+    }
+    let hasNull = false
+    let vs = []
+    getItems(arr, path).forEach((v, k) => {
+        if (v === null) {
+            hasNull = true
+            return
+        }
+        vs.push(chkScalar(v, `${path}.${k}`, false, kind, scale, pk))
+    })
+    if (!neg) {
+        if (vs.length === 0) {
+            return hasNull ? { [field]: null } : sqlFalse()
+        }
+        let c = { [field]: { [Op.in]: vs } }
+        return hasNull ? { [Op.or]: [c, { [field]: null }] } : c
+    }
+    if (vs.length === 0) {
+        return hasNull ? { [field]: { [Op.ne]: null } } : sqlTrue()
+    }
+    let c = { [field]: { [Op.notIn]: vs } }
+    return hasNull ? { [Op.and]: [c, { [field]: { [Op.ne]: null } }] } : c
+}
+
+
+/**
+ * 欄位層條件, 回傳以AND結合之子式陣列
+ *
+ * @ignore
+ */
+function cvField(field, v, path, depth, ctx) {
+    let kind = getColKind(ctx.attrs, field)
+    let scale = getColScale(ctx.attrs, field)
+    let pk = ctx.pk !== undefined && field === ctx.pk //主鍵欄之純量依normPk正規化(R8)
+    if (depth > nDepthMax) {
+        err('find is too deep', path)
+    }
+    if (field === '' || field === '__proto__') {
+        err(`invalid column name [${field}]`, path)
+    }
+    if (v === undefined) {
+        err('value is undefined', path)
+    }
+    if (Array.isArray(v)) {
+        //陣列值即$in(含null與空陣列之處置), 與MongoDB之陣列比對不同, 已文件化
+        return [cvIn(field, v, path, false, kind, scale, pk)]
+    }
+    if (v instanceof RegExp) {
+        return [cvRegex(field, v, undefined, path, ctx, kind)]
+    }
+    if (!isPlainObj(v)) {
+        return [{ [field]: chkScalar(v, path, true, kind, scale, pk) }]
+    }
+    let ks = Reflect.ownKeys(v)
+    if (ks.length === 0) {
+        err('empty operator object', path)
+    }
+    let simple = {}
+    let nSimple = 0
+    let cs = []
+    let hasRegex = false
+    for (let k of ks) {
+        let kp = `${path}.${String(k)}`
+        let x = v[k]
+        let name = k
+        if (typeof k === 'symbol') {
+            if (!setOp.has(k) || setSymFieldNo.has(k)) {
+                err(`unsupported symbol operator [${String(k)}]`, kp)
+            }
+            name = mSymCmp.get(k)
+            if (name === undefined) {
+                //其餘sequelize之Symbol運算子為呼叫端自負之原生寫法, 值經檢核後各自成一子式
+                cs.push({ [field]: { [k]: chkRawSym(x, kp, kind, scale, pk) } })
+                continue
+            }
+        }
+        if (typeof name !== 'string' || name[0] !== '$') {
+            err('nested object is not supported, operators must start with $', kp)
+        }
+        if (mCmp[name] !== undefined) {
+            let allowNull = name === '$eq' || name === '$ne'
+            let y = chkScalar(x, kp, allowNull, kind, scale, pk)
+            if (Object.prototype.hasOwnProperty.call(simple, mCmp[name])) {
+                //同義之鍵(如$gt與Op.gt)各自成一子式, 不得互相覆寫
+                cs.push({ [field]: { [mCmp[name]]: y } })
+            }
+            else {
+                simple[mCmp[name]] = y
+                nSimple++
+            }
+        }
+        else if (name === '$in' || name === '$nin') {
+            cs.push(cvIn(field, x, kp, name === '$nin', kind, scale, pk))
+        }
+        else if (name === '$exists') {
+            if (x !== true && x !== false && x !== 0 && x !== 1) {
+                err('$exists must be a boolean, 0 or 1', kp)
+            }
+            cs.push(x ? { [field]: { [Op.ne]: null } } : { [field]: null })
+        }
+        else if (name === '$regex') {
+            hasRegex = true
+            cs.push(cvRegex(field, x, v.$options, kp, ctx, kind))
+        }
+        else if (name === '$options') {
+            //由$regex一併處理
+        }
+        else if (name === '$not') {
+            if (Array.isArray(x)) {
+                err('$not does not accept an array', kp)
+            }
+            let ns = cvField(field, x, kp, depth + 1, ctx)
+            cs.push({ [Op.not]: { [Op.and]: ns } })
+        }
+        else {
+            err(`unsupported operator [${name}]`, kp)
+        }
+    }
+    if (v.$options !== undefined && !hasRegex) {
+        err('$options requires $regex', path)
+    }
+    if (nSimple > 0) {
+        cs.unshift({ [field]: simple })
+    }
+    return cs
+}
+
+
+/**
+ * 文件層條件(含頂層邏輯運算子)
+ *
+ * @ignore
+ */
+function cvDoc(o, path, depth, ctx) {
+    if (depth > nDepthMax) {
+        err('find is too deep', path)
+    }
+    if (!isPlainObj(o)) {
+        err('condition must be an object', path)
+    }
+    let cvList = (x, kp) => {
+        if (!Array.isArray(x)) {
+            err('logical operator requires an array', kp)
+        }
+        //空陣列拒收(同MongoDB), 以免呼叫端之條件清單恰為空時成為恆真而刪全表
+        if (x.length === 0) {
+            err('logical operator requires a nonempty array', kp)
+        }
+        return getItems(x, kp).map((y, i) => cvDoc(y, `${kp}.${i}`, depth + 1, ctx))
+    }
+    let cs = []
+    for (let k of Reflect.ownKeys(o)) {
+        let x = o[k]
+        let kp = path ? `${path}.${String(k)}` : String(k)
+        if (typeof k === 'symbol') {
+            if (k === Op.and) {
+                cs.push(cvAnd(cvList(x, kp)))
+            }
+            else if (k === Op.or) {
+                cs.push(cvOr(cvList(x, kp)))
+            }
+            else if (k === Op.not) {
+                cs.push({ [Op.not]: cvDoc(x, kp, depth + 1, ctx) })
+            }
+            else {
+                err(`unsupported symbol operator at document level [${String(k)}]`, kp)
+            }
+            continue
+        }
+        if (k[0] === '$') {
+            if (k === '$and') {
+                cs.push(cvAnd(cvList(x, kp)))
+            }
+            else if (k === '$or') {
+                cs.push(cvOr(cvList(x, kp)))
+            }
+            else if (k === '$nor') {
+                cs.push({ [Op.not]: cvOr(cvList(x, kp)) })
+            }
+            else {
+                err(`unsupported operator [${k}]`, kp)
+            }
+            continue
+        }
+        cs.push(...cvField(k, x, kp, depth + 1, ctx))
+    }
+    return cvAnd(cs)
+}
+
+
+/**
+ * 以AND結合子式, 無子式者為恆真
+ *
+ * @ignore
+ */
+function cvAnd(cs) {
+    if (cs.length === 0) {
+        return { [Op.and]: [sqlTrue()] }
+    }
+    return { [Op.and]: cs }
+}
+
+
+/**
+ * 以OR結合子式, 無子式者為恆假
+ *
+ * @ignore
+ */
+function cvOr(cs) {
+    if (cs.length === 0) {
+        return { [Op.and]: [sqlFalse()] }
+    }
+    return { [Op.or]: cs }
+}
+
+
+/**
+ * 將查詢條件轉為sequelize之where, 供select與delAll共用, 令同一find於兩函數由同一SQL謂詞決定命中
+ *
+ * 註: 支援欄位等值與$eq、$ne、$gt、$gte、$lt、$lte、$in、$nin、$not、$regex($options僅i)、$exists, 以及$and、$or、$nor
+ * 註: 不支援之運算子、非純量之值、與欄位型別不符之純量一律拋錯, 不得交sequelize之型別stringify(見本檔之chkScalar)
+ * 註: NULL依SQL三值邏輯; $regex僅支援字面子字串; 非物件之find回{}(即全部), 此為現況保留
+ *
+ * @param {*} find 輸入查詢條件
+ * @param {Object} ctx 輸入轉換所需之依賴物件
+ * @param {Function} ctx.escape 輸入依方言將字串轉為SQL字串常值之函數, 通常為sequelize實例之escape
+ * @param {Object} [ctx.attrs] 輸入model之rawAttributes, 供依欄位型別檢核純量與取得實際欄名, 未給時不檢型別
+ * @param {String} [ctx.dialect] 輸入資料庫種類字串, 供判定方言能力(如sqlite之LOWER僅折疊ASCII)
+ * @param {String} [ctx.pk] 輸入主鍵欄位名, 該欄之純量條件值依normPk正規化(如字串類主鍵欄之123即'123'), 未給時不正規化
+ * @returns {Object} 回傳sequelize之where物件, 條件不合法時拋出錯誤
+ */
+function cvFind(find, ctx) {
+
+    //check, 非物件(undefined、null、字串、數值等純量)與陣列視為未給條件, 此為現況保留, 系列規格另案處理
+    if (find === null || typeof find !== 'object' || Array.isArray(find)) {
+        return {}
+    }
+
+    //check, 非一般物件(class實例、Object.create(proto)、Date、Map等)之條件可能不在自有鍵上, 拒收而不當成{}
+    if (!isPlainObj(find)) {
+        err('find must be a plain object')
+    }
+
+    //check, 空物件為全部
+    if (Reflect.ownKeys(find).length === 0) {
+        return {}
+    }
+
+    return cvDoc(find, '', 0, ctx)
+}
+
+
+export { getColKind, getColScale, normPk }
+export default cvFind