w-orm-reladb 1.1.8 → 1.1.10

package/docs/cvFind.mjs.html

@@ -46,16 +46,19 @@
     <section>
         <article>
             <pre class="prettyprint source linenums"><code>import Sequelize from 'sequelize'
+import cvOrmFind from 'wsemi/src/cvOrmFind.mjs'
 
 
 //查詢條件(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;
+//分兩階段(規則見CLAUDE_rulebook.md之R11):
+//  1. 形狀檢核: 第一步經wsemi之cvOrmFind依系列白名單檢核並回傳全新之null原型深複本(檢查之值即使用之值), 之後只走訪複本;
+//     白名單外之運算子、非純量之值、非條件物件之find、異常結構(存取器、Symbol鍵、洞…)一律整批reject, 不靜默忽略、不改變語意、不擴大刪除範圍
+//  2. 翻譯: 本模組負責後端專屬之檢核與轉譯——欄名嚴格鍵、依欄位型別檢核純量、主鍵正規化(R8)、DATE範圍與ctx.dateNoTz、
+//     空集合之欄位引用($in:[]), 見R3–R5、R8
+//歷史: 原select內之cvObj以lodash之each迭代並以Op[k]直譯$鍵, 不支援之運算子成為鍵'undefined'、具數值length之物件被當成陣列樣迭代而丟棄全部條件,
+//不得供破壞性之delAll使用, 1.1.7起改自寫白名單; 第33項批1起形狀層改由cvOrmFind單一擁有, 本模組刪除Symbol/Op全集、$not $nor $regex $options $exists、
+//RegExp值、陣列值即$in、非物件視為{}等形狀層(破壞性變更見CLAUDE_rulebook.md與README)
 //主鍵值之正規化(normPk)亦屬本模組, 供主鍵函數與主鍵欄條件共用, 規則見R8
 
 
@@ -63,8 +66,17 @@
 let Op = Sequelize.Op
 
 
-//sequelize之運算子Symbol全集, 非其成員之Symbol會被sequelize靜默丟棄, 故一律拒收
-let setOp = new Set(Object.values(Op))
+//形狀檢核之上限(傳給cvOrmFind): $and/$or長度999——SQLite平鋪$or/$and恰1000項即Expression tree is too large(DB錯誤), 本套件使用SQLite故下調(預設1000);
+//其餘上限用預設: 邏輯巢狀深度32、$in/$nin長度10000、節點總數100000、欄名128
+let optShape = { maxList: 999 }
+
+
+//$and/$or清單(含同一條件物件內並列欄位之隱含AND)項數超過此值者, 遞迴二分為平衡樹再交sequelize:
+//SQLite之運算式樹深度上限1000(Expression tree is too large), 平鋪之a OR b OR …為左深樹(深度隨項數線性成長), select因欄位帶表別名(`t`.`c`)而較delAll少容1項
+//(實測平鋪$or: select最多998項、delAll最多999項, 999項時select報DB錯誤而delAll照常刪除, 違反select命中即delAll刪除之對象一致);
+//巢狀層數亦會累加(32層 × 每層33項平鋪即超限, 外審sol F1), 另有巢狀遞迴上限(實測右深巢狀OR約830層, SQLITE_ERROR: Recursion limit);
+//二分後每個清單之樹深僅約log2(項數)+3, 邏輯巢狀上限32層下全樹深度恆遠低於兩種上限, select與delAll皆可執行
+let nFlat = 4
 
 
 //比較運算子, 值須為純量(null僅$eq與$ne)
@@ -78,32 +90,6 @@ let mCmp = {
 }
 
 
-//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
@@ -134,52 +120,73 @@ let reIsoTz = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(:(\d{2})(\.\d+)?)?(Z|
 let reDateOnly = /^(\d{4})-(\d{2})-(\d{2})$/
 
 
+//無時區之ISO 8601日期時間字串(秒與小數秒可省), 僅呼叫端以ctx.dateNoTz明示'local'時收
+let reIsoNoTz = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?$/
+
+
 /**
- * 判定年月日是否為曆法上存在之日期, 如2026-02-30不存在
+ * 依主機時區解析無時區之ISO 8601日期時間字串為Date, 不合法(格式不符、曆法上不存在、主機時區下不存在)者回傳null
+ * 註: 不用Date.parse, 因帶空白分隔等寫法屬實作定義; 以本地時間建構後逐欄回驗, 如2026-02-30、24:00:00、60秒、夏令跳過之時刻皆為null
+ * 註: 小數秒取前三位(截斷至毫秒); 夏令重疊之時刻取較早者(Date之行為)
  *
  * @ignore
  */
-function isCalendarDate(y, m, d) {
-    let t = new Date(Date.UTC(Number(y), Number(m) - 1, Number(d)))
-    return t.getUTCFullYear() === Number(y) &amp;&amp; t.getUTCMonth() === Number(m) - 1 &amp;&amp; t.getUTCDate() === Number(d)
+function parseNoTzLocal(s) {
+    let m = s.match(reIsoNoTz)
+    if (m === null) {
+        return null
+    }
+    let y = Number(m[1])
+    let mo = Number(m[2])
+    let d = Number(m[3])
+    let h = Number(m[4])
+    let mi = Number(m[5])
+    let sec = m[6] === undefined ? 0 : Number(m[6])
+    let ms = m[7] === undefined ? 0 : Number(`${m[7]}00`.slice(0, 3))
+    let t = new Date(y, mo - 1, d, h, mi, sec, ms)
+    if (t.getFullYear() !== y || t.getMonth() !== mo - 1 || t.getDate() !== d || t.getHours() !== h || t.getMinutes() !== mi || t.getSeconds() !== sec || t.getMilliseconds() !== ms) {
+        return null
+    }
+    if (!inDateRange(t.getTime())) {
+        return null //本地時間通過回驗, 但換算UTC後年份超出1–9999(如負偏移時區之9999-12-31晚間)
+    }
+    return t
 }
 
 
 /**
- * 拋出條件錯誤
+ * 判定年月日是否為曆法上存在之日期, 如2026-02-30不存在; 年須在1以上(年0000不收)
+ * 註: 不用Date.UTC(y,..)建構, 因其把0–99年映射為1900–1999而使年0001–0099之字串被誤拒; 以setUTCFullYear設定完整年份
  *
  * @ignore
  */
-function err(msg, path) {
-    throw new Error(`invalid find: ${msg}${path ? ` at [${path}]` : ''}`)
+function isCalendarDate(y, m, d) {
+    let yn = Number(y)
+    if (yn &lt; 1) {
+        return false
+    }
+    let t = new Date(0)
+    t.setUTCFullYear(yn, Number(m) - 1, Number(d))
+    return t.getUTCFullYear() === yn &amp;&amp; t.getUTCMonth() === Number(m) - 1 &amp;&amp; t.getUTCDate() === Number(d)
 }
 
 
 /**
- * 是否為一般物件: 原型為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
+function err(msg, path) {
+    throw new Error(`invalid find: ${msg}${path ? ` at [${path}]` : ''}`)
 }
 
 
 /**
- * 恆真與恆假之謂詞, 以明確之SQL表示, 不以空條件表示
- * 註: sequelize會把空條件(如{}、空$and)於OR、NOT內濾除, 致恆真被當成不存在而改變語意(如$nor:[{}]成全部)
+ * 恆假之謂詞, 以明確之SQL表示, 不以空條件表示
+ * 註: sequelize會把空條件於OR、NOT內濾除而改變語意; 本模組僅用於$in:[]之f IS NULL AND 1 = 0(仍引用欄位, 見R5)
  *
  * @ignore
  */
-function sqlTrue() {
-    return Sequelize.literal('1 = 1')
-}
 function sqlFalse() {
     return Sequelize.literal('1 = 0')
 }
@@ -220,6 +227,149 @@ function getColKind(attrs, field) {
 }
 
 
+/**
+ * 取model屬性之資料庫欄名: attr.field(字串)優先, 否則為屬性名(sequelize define後恆有field, 手造attrs可能缺)
+ *
+ * @ignore
+ */
+function colOf(attrs, k) {
+    return attrs[k] &amp;&amp; typeof attrs[k].field === 'string' ? attrs[k].field : k
+}
+
+
+/**
+ * 建立attrs之索引: 資料庫欄名 → 屬性名陣列(依定義順序), 供欄名解析與sequelize反查之核對
+ *
+ * @ignore
+ */
+function buildAttrIdx(attrs) {
+    let byCol = new Map()
+    for (let k of Object.keys(attrs)) {
+        let c = colOf(attrs, k)
+        let a = byCol.get(c)
+        if (a === undefined) {
+            a = []
+            byCol.set(c, a)
+        }
+        a.push(k)
+    }
+    return { byCol }
+}
+
+
+/**
+ * 核對attrs為sequelize之rawAttributes形狀: 一般物件(原型為Object.prototype或null)、無Symbol鍵、自有字串鍵皆可列舉
+ * 註: sequelize以rawAttributes[鍵]讀取(含原型鏈、Symbol鍵、不可列舉者), 而cvFind以Object.keys建索引、以自有屬性核對; 三者所見之屬性集合不同時,
+ * 反查核對與sequelize實際取用之定義分歧(如與Op.and相撞之Symbol屬性使sequelize把邏輯鍵映射為欄而條件消失); 真正之rawAttributes恆符合
+ *
+ * @ignore
+ */
+function chkAttrs(attrs) {
+    let p = typeof attrs === 'object' ? Object.getPrototypeOf(attrs) : undefined
+    if (!(p === Object.prototype || p === null) || Object.getOwnPropertySymbols(attrs).length > 0 || Object.getOwnPropertyNames(attrs).length !== Object.keys(attrs).length) {
+        throw new Error('invalid ctx: attrs must be a plain object (prototype Object.prototype or null) without symbol keys and with enumerable string keys only')
+    }
+}
+
+
+/**
+ * 核對欄名可安全交sequelize: 下列名稱會被sequelize於轉成SQL前改寫或重新解讀, 使資料庫實際比對之欄不是此名, 一律拒收
+ * 註: 空字串者(sequelize之_joinKeyValue遇空鍵只回值, 條件成常數而delAll刪全表)、含反引號/雙引號/單引號/方括號者(quoteIdentifier依方言刪除之, 如sqlite之`val`ue`成value)、含點者(JSON路徑、表.欄)、
+ * 前後皆$者($x$被當成欄引用; sequelize之isColString只比首尾字元, 故含換行者與單一$亦是, 不以正規式判定以免.不匹配換行)、
+ * Object.prototype之成員名與__proto__(sequelize以一般物件查表與賦值: 查到函數而不依欄型序列化、賦值__proto__使條件遺失而刪全表)
+ *
+ * @ignore
+ */
+function chkColName(n, path) {
+    if (n === '' || n in Object.prototype || n.indexOf('.') >= 0 || /[`"'[\]]/.test(n) || (n[0] === '$' &amp;&amp; n[n.length - 1] === '$')) {
+        err(`unsupported column name [${n}]`, path)
+    }
+}
+
+
+/**
+ * 屬性是否為VIRTUAL(非資料庫欄)
+ *
+ * @ignore
+ */
+function isVirtualAttr(at) {
+    let t = at &amp;&amp; at.type
+    return !!t &amp;&amp; (t instanceof DT.VIRTUAL || t.key === 'VIRTUAL')
+}
+
+
+/**
+ * 將條件之欄名解析為model之屬性名(嚴格鍵): 僅收屬性名完全相符、或資料庫欄名(attr.field)完全相符且唯一者, 其餘一律拒收, 不模擬資料庫之識別字解析
+ * 註: 欄名經三方各自解析: cvFind(判型別、主鍵、DATE值)、sequelize(屬性名映射欄名、以映射後之名稱反查屬性型別、引用層改寫字元)、資料庫(依定序折疊);
+ * 完全相符之名稱無論資料庫如何折疊皆解析為自己, 故只收完全相符者(另核對sequelize之反查與改寫, 見chkColName與下文), 使三方之解析必然一致, 見CLAUDE_rulebook.md之R4欄名解析
+ * 註: 以model之attrs為準, attrs缺少之欄與VIRTUAL屬性皆拒收; attrs未給者回傳null(不解析, 欄位型別為any, 交資料庫處置)
+ *
+ * @ignore
+ */
+function resolveAttr(attrs, idx, field, path) {
+    if (!attrs) {
+        return null
+    }
+    chkColName(field, path)
+
+    //①屬性名完全相符; ②資料庫欄名完全相符(多於一個者無從判定)
+    let name = null
+    if (Object.prototype.hasOwnProperty.call(attrs, field)) {
+        name = field
+    }
+    else {
+        let hits = idx.byCol.get(field) || []
+        if (hits.length > 1) {
+            err(`ambiguous column name [${field}]`, path)
+        }
+        if (hits.length === 1) {
+            name = hits[0]
+        }
+    }
+
+    //其餘拒收; 提示僅供診斷(不分大小寫相同者), 不影響解析
+    if (name === null || isVirtualAttr(attrs[name])) {
+        let lf = field.toLowerCase()
+        let near = Object.keys(attrs).find((k) => !isVirtualAttr(attrs[k]) &amp;&amp; (k.toLowerCase() === lf || colOf(attrs, k).toLowerCase() === lf))
+        err(`unknown column name [${field}]${near === undefined ? '' : `, did you mean [${near}]?`}`, path)
+    }
+
+    //field已設者須為字串(sequelize保留原值並以String(field)映射, 退回屬性名則二者指向不同欄); 空字串由chkColName拒收
+    let at = attrs[name]
+    if (at &amp;&amp; at.field !== undefined &amp;&amp; typeof at.field !== 'string') {
+        err(`unsupported column name [${name}], its field must be a string`, path)
+    }
+
+    //sequelize把屬性名之鍵映射為其欄名後, 以rawAttributes[欄名](名稱為該欄名之屬性)、其次fieldRawAttributesMap[欄名](欄名為該欄名之屬性, 多個取最後定義者)取得型別序列化值;
+    //反查所得須即本屬性, 否則值依他屬性之型別序列化(如DATE之值被INTEGER序列化為Date.toString文字, sqlite以文字比較而命中全部非NULL列), 拒收
+    //共用一欄者另須本屬性即最後定義者: 實體欄之型別由最後定義者決定(sync以欄名為鍵而後者覆寫), 先定義者即使反查為自己, sequelize之序列化亦與實體欄不符
+    let col = colOf(attrs, name)
+    chkColName(col, path)
+    let cs = idx.byCol.get(col)
+    let last = cs[cs.length - 1]
+    let s = Object.prototype.hasOwnProperty.call(attrs, col) ? col : last
+    if (s !== name) {
+        err(`ambiguous column name [${field}], its column [${col}] resolves to attribute [${s}]`, path)
+    }
+    if (last !== name) {
+        err(`ambiguous column name [${field}], its column [${col}] is shared with attribute [${last}], the last attribute defines the column type`, path)
+    }
+    return name
+}
+
+
+/**
+ * 判定時間(毫秒)換算UTC後年份是否在1–9999
+ * 註: sequelize以YYYY格式化DATE, 年10000起為5位數, sqlite以文字比較致{d:{$gt:年10000}}命中全部日期列; mssql之datetimeoffset範圍亦為0001–9999
+ *
+ * @ignore
+ */
+function inDateRange(ms) {
+    let y = new Date(ms).getUTCFullYear()
+    return y >= 1 &amp;&amp; y &lt;= 9999
+}
+
+
 /**
  * 取DECIMAL欄之scale, 未指定者為0(mssql之DECIMAL預設為(18,0)), 非DECIMAL者為null
  *
@@ -275,18 +425,23 @@ function isKindOk(v, kind, scale = null) {
         return true
     }
     if (kind === 'date') {
+        //所有形式換算UTC後年份須在1–9999(inDateRange)
         if (v instanceof Date) {
-            return !isNaN(v.getTime())
+            return !isNaN(v.getTime()) &amp;&amp; inDateRange(v.getTime())
         }
         if (typeof v === 'number') {
             //須在Date可表示之範圍(±8.64e15毫秒)內, 超出者被stringify為'Invalid date'而以文字比較, sqlite會命中全部日期列
-            return Number.isFinite(v) &amp;&amp; !isNaN(new Date(v).getTime())
+            return Number.isFinite(v) &amp;&amp; !isNaN(new Date(v).getTime()) &amp;&amp; inDateRange(v)
         }
         if (typeof v !== 'string') {
             return false
         }
         let m = v.match(reIsoTz)
-        return m !== null &amp;&amp; isCalendarDate(m[1], m[2], m[3]) &amp;&amp; !isNaN(Date.parse(v.replace(' ', 'T')))
+        if (m === null || !isCalendarDate(m[1], m[2], m[3])) {
+            return false
+        }
+        let ms = Date.parse(v.replace(' ', 'T'))
+        return !isNaN(ms) &amp;&amp; inDateRange(ms)
     }
     if (kind === 'dateonly') {
         //Date物件依主機時區取日期而結果隨主機而變, 故只收日期字串
@@ -386,42 +541,31 @@ function normPk(v, kind, scale = null) {
     return { kind: 'invalid' }
 }
 
-
 /**
- * 檢核純量值: 字串、有限數值、布林、有效Date、Buffer, 以及允許時之null; 並須符合欄位型別分類
- * 註: 物件、陣列等不得交sequelize之型別stringify, 否則FLOAT成'NaN'、INTEGER成'[object Object]'、DATE成本地今日00:00而誤刪
+ * 檢核純量值: 字串、有限數值、布林、有效Date, 以及null(是否允許null已由cvOrmFind依運算子判定); 並須符合欄位型別分類
+ * 註: 物件、陣列等不得交sequelize之型別stringify, 否則FLOAT成'NaN'、INTEGER成'[object Object]'、DATE成本地今日00:00而誤刪;
+ * 形狀層(cvOrmFind)已保證僅此類值到達, 此處保留型別檢核作為fail-closed之防線(日後上游放寬時不得靜默放行)
  * 註: 主鍵欄(pk為true)之字串類、整數類與其他數值類以normPk正規化後回傳(如字串類主鍵欄之123即'123'), 無效或型別不符者拒收,
  * 令select與delAll對主鍵之認定與selectByPk、del等主鍵函數一致; 非主鍵欄不轉型
+ * 註: kind為date且呼叫端以ctx.dateNoTz明示'local'(dateNoTz為'local')時, 無時區日期時間字串依主機時區轉為Date回傳(見parseNoTzLocal), 其餘值照舊判定
  *
  * @ignore
  */
-function chkScalar(v, path, allowNull, kind = 'any', scale = null, pk = false) {
+function chkScalar(v, path, kind = 'any', scale = null, pk = false, dateNoTz = undefined) {
     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
+        return v
     }
-    else if (typeof v === 'number') {
+    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) {
+    else if (typeof v !== 'string' &amp;&amp; typeof v !== 'boolean') {
         err(`value must be a string, finite number, boolean, Date or null, got [${Object.prototype.toString.call(v)}]`, path)
     }
     if (pk &amp;&amp; (kind === 'str' || kind === 'int' || kind === 'num')) {
@@ -431,408 +575,231 @@ function chkScalar(v, path, allowNull, kind = 'any', scale = null, pk = false) {
         }
         err(`value [${String(v)}] does not match column type [${kind}]${scale !== null ? ` with scale [${scale}]` : ''}`, path)
     }
+    if (kind === 'date' &amp;&amp; dateNoTz === 'local' &amp;&amp; typeof v === 'string') {
+        //呼叫端明示之無時區日期時間字串: 依主機時區解析並以Date送出, 與直接給Date同義; 不符者續由isKindOk判定(帶時區者照舊)
+        let t = parseNoTzLocal(v)
+        if (t !== null) {
+            return t
+        }
+    }
     if (!isKindOk(v, kind, scale)) {
         err(`value [${String(v)}] does not match column type [${kind}]${scale !== null ? ` with scale [${scale}]` : ''}`, path)
     }
+    if (kind === 'date' &amp;&amp; !(v instanceof Date)) {
+        //通過檢核之字串與epoch一律轉為Date送出: sequelize只在鍵為屬性名或欄名完全相符時依欄型序列化值, 大小寫變體鍵會原樣送出字串與epoch,
+        //sqlite以文字或型別序比較而命中錯列(如{D:{$gt:epoch}}刪光全部日期列); 轉為Date後與鍵之拼寫無關
+        return new Date(typeof v === 'string' ? Date.parse(v.replace(' ', 'T')) : v)
+    }
     return v
 }
 
 
 /**
- * 取陣列之各元素, 稀疏陣列之洞與undefined一律拒收
- * 註: forEach與map會略過洞, 洞若被略過則$and之子式消失而成恆真
+ * $in與$nin, 元素為純量(不含null, 已由cvOrmFind保證); 空$in以引用欄位之恆假表示
+ * 註: $nin:[]已由cvOrmFind拒收(恆真, 易因清單恰為空而刪全表); 此處再擋以免上游放寬時靜默放行
  *
  * @ignore
  */
-function getItems(arr, path) {
-    let rs = []
+function cvIn(field, arr, path, neg, kind, scale, pk, dateNoTz) {
+    let vs = []
     for (let i = 0; i &lt; arr.length; i++) {
-        if (!(i in arr) || arr[i] === undefined) {
-            err('array must not contain holes or undefined', `${path}.${i}`)
+        if (arr[i] === null) {
+            err('null is not allowed here', `${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
+        vs.push(chkScalar(arr[i], `${path}[${i}]`, kind, scale, pk, dateNoTz))
     }
-    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 &lt; src.length; i++) {
-        let c = src[i]
-        if (c === '\\') {
-            let n = src[i + 1]
-            if (n !== undefined &amp;&amp; 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' &amp;&amp; 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 &amp;&amp; ctx.dialect === 'sqlite') {
-        for (let c of lit) {
-            if (c.charCodeAt(0) > 127 &amp;&amp; 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 &amp;&amp; ctx.attrs[field] &amp;&amp; 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()
+            //f IS NULL恆為二值(永不為UNKNOWN), 整式二值, 且欄名會出現在SQL中, 不存在之欄由資料庫回報(R5)
+            return { [Op.and]: [{ [field]: null }, sqlFalse()] }
         }
-        let c = { [field]: { [Op.in]: vs } }
-        return hasNull ? { [Op.or]: [c, { [field]: null }] } : c
+        return { [field]: { [Op.in]: vs } }
     }
     if (vs.length === 0) {
-        return hasNull ? { [field]: { [Op.ne]: null } } : sqlTrue()
+        err('$nin with empty array is always true', path)
     }
-    let c = { [field]: { [Op.notIn]: vs } }
-    return hasNull ? { [Op.and]: [c, { [field]: { [Op.ne]: null } }] } : c
+    return { [field]: { [Op.notIn]: vs } }
 }
 
 
 /**
- * 欄位層條件, 回傳以AND結合之子式陣列
+ * 欄位層條件, 回傳以AND結合之子式陣列; v為純量、null、Date(等值)或運算子物件(null原型, 鍵為$eq $ne $gt $gte $lt $lte $in $nin)
  *
  * @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 &amp;&amp; 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)
+function cvField(field, v, path, ctx) {
+
+    //欄名先解析為model之屬性名再判型別與主鍵(R4欄名解析); attrs已給而解析不到者拒收, attrs未給者為any, 交資料庫處置
+    let an = resolveAttr(ctx.attrs, ctx.attrIdx, field, path)
+    let kind = an === null ? 'any' : getColKind(ctx.attrs, an)
+    let scale = an === null ? null : getColScale(ctx.attrs, an)
+    let pk = ctx.pk !== undefined &amp;&amp; an === ctx.pk //主鍵欄之純量依normPk正規化(R8)
+    let dateNoTz = ctx.dateNoTz
+
+    //欄位直給(等值)
+    if (v === null || typeof v !== 'object' || v instanceof Date) {
+        return [{ [field]: chkScalar(v, path, kind, scale, pk, dateNoTz) }]
     }
+
+    //運算子物件
     let simple = {}
     let nSimple = 0
     let cs = []
-    let hasRegex = false
-    for (let k of ks) {
-        let kp = `${path}.${String(k)}`
+    for (let k of Object.keys(v)) {
+        let kp = `${path}.${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)
+        if (k === '$in' || k === '$nin') {
+            if (!Array.isArray(x)) {
+                err(`${k} must be an array`, 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)
+            cs.push(cvIn(field, x, kp, k === '$nin', kind, scale, pk, dateNoTz))
         }
-        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 &amp;&amp; x !== false &amp;&amp; x !== 0 &amp;&amp; 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 if (Object.prototype.hasOwnProperty.call(mCmp, k)) {
+            //同欄之比較運算子併入同一欄位物件, 以AND結合
+            simple[mCmp[k]] = chkScalar(x, kp, kind, scale, pk, dateNoTz)
+            nSimple++
         }
         else {
-            err(`unsupported operator [${name}]`, kp)
+            err(`unsupported operator [${k}]`, kp)
         }
     }
-    if (v.$options !== undefined &amp;&amp; !hasRegex) {
-        err('$options requires $regex', path)
-    }
     if (nSimple > 0) {
         cs.unshift({ [field]: simple })
     }
+    if (cs.length === 0) {
+        //不產生任何子式者條件即消失而成恆真, delAll會刪全表; cvOrmFind已拒收空運算子物件, 此處再擋(含非Date之物件值)
+        err('operator object has no operator', path)
+    }
     return cs
 }
 
 
 /**
- * 文件層條件(含頂層邏輯運算子)
+ * 文件層條件(含$and、$or), o為cvOrmFind之複本(null原型, 鍵僅字串)
  *
  * @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))
-    }
+function cvDoc(o, path, ctx) {
     let cs = []
-    for (let k of Reflect.ownKeys(o)) {
+    for (let k of Object.keys(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)))
+        let kp = `${path}.${k}`
+        if (k === '$and' || k === '$or') {
+            if (!Array.isArray(x) || x.length === 0) {
+                err(`${k} requires a nonempty array`, kp)
             }
-            else if (k === Op.not) {
-                cs.push({ [Op.not]: cvDoc(x, kp, depth + 1, ctx) })
+            let sub = []
+            for (let i = 0; i &lt; x.length; i++) {
+                sub.push(cvDoc(x[i], `${kp}[${i}]`, ctx))
             }
-            else {
-                err(`unsupported symbol operator at document level [${String(k)}]`, kp)
-            }
-            continue
+            cs.push(cvGroup(k === '$and' ? cvAnd : cvOr, sub))
         }
-        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
+        else if (k[0] === '$') {
+            err(`unsupported operator [${k}]`, kp)
         }
-        cs.push(...cvField(k, x, kp, depth + 1, ctx))
+        else {
+            cs.push(...cvField(k, x, kp, ctx))
+        }
+    }
+    if (cs.length === 0) {
+        err('empty condition', path)
     }
-    return cvAnd(cs)
+    return cvGroup(cvAnd, cs)
 }
 
 
 /**
- * 以AND結合子式, 無子式者為恆真
+ * 以AND結合子式
  *
  * @ignore
  */
 function cvAnd(cs) {
-    if (cs.length === 0) {
-        return { [Op.and]: [sqlTrue()] }
-    }
     return { [Op.and]: cs }
 }
 
 
 /**
- * 以OR結合子式, 無子式者為恆假
+ * 以OR結合子式
  *
  * @ignore
  */
 function cvOr(cs) {
-    if (cs.length === 0) {
-        return { [Op.and]: [sqlFalse()] }
-    }
     return { [Op.or]: cs }
 }
 
 
+/**
+ * 子式過多者遞迴二分為平衡樹, 避免SQLite之運算式樹深度與遞迴上限(見nFlat); 語意不變(AND與OR皆滿足結合律, 含NULL之三值邏輯), 子式順序不變
+ *
+ * @ignore
+ */
+function cvGroup(fn, cs) {
+    if (cs.length &lt;= nFlat) {
+        return fn(cs)
+    }
+    let k = Math.ceil(cs.length / 2)
+    return fn([cvGroup(fn, cs.slice(0, k)), cvGroup(fn, cs.slice(k))])
+}
+
+
+/**
+ * 檢核find之形狀(系列白名單, 由wsemi之cvOrmFind單一擁有, 規則見R11)並回傳全新之null原型深複本, 後續一律只使用複本(檢查之值即使用之值)
+ * 註: 未給/undefined/{}回傳空物件(全部); 其餘非條件物件、白名單外之運算子與值、異常結構一律throw Error('invalid find: 原因 at [路徑]')
+ * 註: maxList傳999(SQLite之運算式樹深度上限); select與delAll於載入model與建立sequelize實例之前先呼叫本函數, 使形狀不合法者不連線、不送出任何SQL
+ * 註: 對複本再呼叫為冪等(複本本身符合白名單)
+ *
+ * @ignore
+ * @param {*} find 輸入查詢條件
+ * @returns {Object} 回傳null原型之條件複本, 無自有鍵代表全部
+ */
+function chkFindShape(find) {
+    return cvOrmFind(find, optShape)
+}
+
+
 /**
  * 將查詢條件轉為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回{}(即全部), 此為現況保留
+ * 註: 第一步經chkFindShape(wsemi之cvOrmFind)依系列白名單檢核並取複本, 其後只走訪複本; 白名單: 欄位等值{欄:純量|null}、
+ * $eq $ne $gt $gte $lt $lte(純量)、$in $nin(純量陣列)、$and $or(條件物件之非空陣列); 其餘(含$not $nor $regex $options $exists、RegExp、Symbol鍵、陣列值)一律拋錯
+ * 註: 未給、undefined或{}回傳{}(全部); 其餘非條件物件(null、陣列、字串、數值等)拋錯, 不再視為{}
+ * 註: 與欄位型別不符之純量、不存在之欄一律拋錯, 不得交sequelize之型別stringify(見本檔之chkScalar); NULL依SQL三值邏輯
  *
  * @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 {Function} [ctx.escape] 已不使用(原供$regex之LIKE字面常值; 第33項批1移除$regex), 保留接受以相容既有呼叫端
+ * @param {Object} [ctx.attrs] 輸入執行where之model之rawAttributes, 供欄名解析(嚴格鍵: 鍵須與屬性名或資料庫欄名完全相符, 其餘拒收)、依欄位型別檢核純量與取得實際欄名; 未給時不解析鍵、不檢型別而交資料庫(見CLAUDE_rulebook.md之R4)
+ * @param {String} [ctx.dialect] 已不使用(原供判定sqlite之LOWER僅折疊ASCII), 保留接受以相容既有呼叫端
  * @param {String} [ctx.pk] 輸入主鍵欄位名, 該欄之純量條件值依normPk正規化(如字串類主鍵欄之123即'123'), 未給時不正規化
+ * @param {String} [ctx.dateNoTz] 輸入無時區日期時間字串之處置, 僅接受undefined(預設, 無時區者拒收)或'local'(依主機時區解析, 與以本地時間分量建構之Date同義), 其餘值拋錯; 僅作用於DATE欄, 供Jet等無時區後端之呼叫端明示啟用
  * @returns {Object} 回傳sequelize之where物件, 條件不合法時拋出錯誤
  */
 function cvFind(find, ctx) {
 
-    //check, 非物件(undefined、null、字串、數值等純量)與陣列視為未給條件, 此為現況保留, 系列規格另案處理
-    if (find === null || typeof find !== 'object' || Array.isArray(find)) {
-        return {}
+    //check, ctx.dateNoTz須為undefined或'local', 其餘值(含拼錯、大小寫不同)拋錯, 不靜默忽略
+    if (ctx &amp;&amp; ctx.dateNoTz !== undefined &amp;&amp; ctx.dateNoTz !== 'local') {
+        throw new Error(`invalid ctx: dateNoTz must be 'local' or undefined, got [${String(ctx.dateNoTz)}]`)
     }
 
-    //check, 非一般物件(class實例、Object.create(proto)、Date、Map等)之條件可能不在自有鍵上, 拒收而不當成{}
-    if (!isPlainObj(find)) {
-        err('find must be a plain object')
-    }
+    //step1, 形狀檢核(R11), 其後一律只使用複本
+    let fd = chkFindShape(find)
 
     //check, 空物件為全部
-    if (Reflect.ownKeys(find).length === 0) {
+    if (Reflect.ownKeys(fd).length === 0) {
         return {}
     }
 
-    return cvDoc(find, '', 0, ctx)
+    //check, attrs須為rawAttributes形狀(見chkAttrs)
+    if (ctx &amp;&amp; ctx.attrs) {
+        chkAttrs(ctx.attrs)
+    }
+
+    //attrs之索引每次轉譯只建一次(內部欄位attrIdx, 不屬ctx之介面)
+    return cvDoc(fd, 'find', ctx &amp;&amp; ctx.attrs ? { ...ctx, attrIdx: buildAttrIdx(ctx.attrs) } : ctx)
 }
 
 
-export { getColKind, getColScale, normPk }
+export { getColKind, getColScale, normPk, chkFindShape }
 export default cvFind
 </code></pre>
         </article>
@@ -848,7 +815,7 @@ export default cvFind
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 16 2026 14:32:44 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 Mon Oct 19 2026 18:54:43 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>