w-orm-lowdb 1.0.32 → 1.0.34

package/docs/WOrmLowdb.html

@@ -91,13 +91,14 @@ err為錯誤訊息字串，內容與正規管道所送出者一致。
 註: 逐筆失敗時整批仍resolve，故收到本事件不表示該次呼叫失敗；正常結果(如查無數據、主鍵未命中、全數已存在)不發出本事件。</p>
 <p>註: 本套件之主鍵欄位固定為id，尚未支援指定其他欄位為主鍵。
 註: 本套件之寫入為[整檔讀出、記憶體修改、整檔寫回]，其原子性由行程內之序列化佇列提供，
-故僅單一行程內併發成立，跨行程併發不成立，詳見README之併發保證宣告。</p></li></ul></dd>
+故僅單一行程內併發成立，跨行程併發不成立，詳見README之併發保證宣告。
+註: 數據以JSON存檔，Date存入後為ISO字串；insert、insertBulk與save寫入之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject，詳見各函數與README。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line62">line 62</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line63">line 63</a>
     </li></ul></dd>
     
 
@@ -528,7 +529,7 @@ err為錯誤訊息字串，內容與正規管道所送出者一致。
 <li>傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)
 一律整批reject，不視為{}，不刪除任何數據。</li>
 <li>條件僅支援系列白名單: 欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與
-$in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date；
+$in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date(年份須介於0000-9999，範圍外整批reject，見第6點)；
 null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $where $expr $like $ilike等)、
 欄位層$and/$or、子查詢、函數值、Symbol鍵、undefined值、空的$nin/$and/$or等一律整批reject，
 訊息為invalid find: 原因 at [路徑]，且不刪除任何數據。</li>
@@ -538,7 +539,11 @@ null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $r
 空的$nin會reject，$in:[]則為恆假(刪除0筆)。</li>
 <li>語意差異(依後端，見README): MongoDB式: $ne(比較值非null時)與$nin會命中欄位為null或缺欄之數據，$ne:null則排除之；
 欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
-Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，範圍比較僅在年份0000-9999內正確，見README)。
+Date條件於本後端轉為ISO字串後以字典序比較(與字串型欄位亦會比較)：條件內任何位置之Date其年份須介於0000-9999，
+範圍外(年份小於0或大於9999，如new Date(8.64e15)、new Date(-8.64e15))整批reject，訊息為invalid find: Date year is out of range 0000-9999 at [路徑]，
+不回顯值，不讀檔、不刪除任何數據；數據側自1.0.34起insert、insertBulk與save寫入時已拒收範圍外Date，
+但資料庫檔內既有之範圍外Date字串(舊版以new Date(8.64e15)作永不過期哨兵存入者)仍無法以Date條件正確比較
+(例如{t:{$lt:現在}}會命中哨兵並將其刪除)，請自行清理或改寫，見README。
 需明確表達時可用可攜寫法: 排除NULL為{$and:[{f:{$ne:null}},{f:{$ne:x}}]}，含NULL為{$or:[{f:null},{f:{$ne:x}}]}。</li>
 </ol>
 <p>n與nDeleted皆為實際刪除筆數，不取全表筆數。條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。</p></li></ul></dd>
@@ -547,7 +552,7 @@ Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line1058">line 1058</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line1178">line 1178</a>
     </li></ul></dd>
     
 
@@ -725,7 +730,7 @@ Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line879">line 879</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line995">line 995</a>
     </li></ul></dd>
     
 
@@ -884,13 +889,14 @@ Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，
 註: 本函數非insert之加速版，兩者衝突政策不同。insert於主鍵已存在時跳過該筆而整批ok為1，
 本函數則整批reject且不寫入任何一筆；同批含重複主鍵者亦視為衝突。確無衝突時兩者結果相同
 註: 於本套件不會較insert快，因兩者皆為一次讀檔與一次寫檔，
-提供本函數係為與其他w-orm系列套件維持同一組函數，令呼叫端得於各套件間替換而不須改寫呼叫</p></li></ul></dd>
+提供本函數係為與其他w-orm系列套件維持同一組函數，令呼叫端得於各套件間替換而不須改寫呼叫
+註: 數據內任何深度之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject且不寫入任何一筆，規則同insert，詳見insert與README</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line582">line 582</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line689">line 689</a>
     </li></ul></dd>
     
 
@@ -1045,13 +1051,17 @@ Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫</p>
+<p>數據內任何深度(頂層欄位、巢狀物件、陣列內)之Date年份須介於0000-9999(序列化為固定24字元之ISO字串，字典序即時間序)，
+範圍外(年份小於0或大於9999，如以new Date(8.64e15)作永不過期哨兵)整批reject且不寫入任何一筆，訊息為invalid data: Date year is out of range 0000-9999 at [路徑]，
+不回顯值，於reject之前發出一次error事件、不發出change事件；無效Date維持序列化為null存入；永不過期請改用null或new Date('9999-12-31T23:59:59.999Z')；
+資料庫檔內既有之範圍外Date字串不遷移，仍無法以Date條件正確比較，詳見README</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line448">line 448</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line551">line 551</a>
     </li></ul></dd>
     
 
@@ -1332,13 +1342,15 @@ Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>儲存數據，以主鍵為準更新既有數據，未給之欄位保留；主鍵不存在且autoInsert為true時改為插入</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>儲存數據，以主鍵為準更新既有數據，未給之欄位保留；主鍵不存在且autoInsert為true時改為插入</p>
+<p>數據內任何深度之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject且不寫入任何一筆(逐筆失敗之ok為0機制不適用)，規則同insert，詳見insert與README；
+autoInsert為false而主鍵不存在(不會寫入)者亦先經同一檢核；合併與覆寫路徑寫入之Date皆來自已檢核之數據，已存在於資料庫之字串不檢核</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line683">line 683</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line796">line 796</a>
     </li></ul></dd>
     
 
@@ -1628,7 +1640,7 @@ Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line389">line 389</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line487">line 487</a>
     </li></ul></dd>
     
 
@@ -1781,13 +1793,14 @@ Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，
     
     <dt class="tag-description">Description:</dt>
     <dd class="tag-description"><ul class="dummy"><li><p>查詢數據</p>
-<p>條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據</p></li></ul></dd>
+<p>條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
+條件內之Date年份須介於0000-9999，範圍外整批reject；資料庫檔內既有之範圍外Date字串(1.0.34起寫入已拒收範圍外Date)無法以Date條件正確比較(規則同delAll之第6點，見README)</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line321">line 321</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line419">line 419</a>
     </li></ul></dd>
     
 
@@ -1972,7 +1985,7 @@ select亦納入序列化，令其不致與寫入之整檔替換交錯。</p>
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line130">line 130</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line131">line 131</a>
     </li></ul></dd>
     
 
@@ -2056,7 +2069,7 @@ select亦納入序列化，令其不致與寫入之整檔替換交錯。</p>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sat Oct 17 2026 14:56:45 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 21:48:29 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WOrmLowdb.mjs.html

@@ -96,6 +96,7 @@ let kpGqueue = {}
  * 註: 本套件之主鍵欄位固定為id，尚未支援指定其他欄位為主鍵。
  * 註: 本套件之寫入為[整檔讀出、記憶體修改、整檔寫回]，其原子性由行程內之序列化佇列提供，
  * 故僅單一行程內併發成立，跨行程併發不成立，詳見README之併發保證宣告。
+ * 註: 數據以JSON存檔，Date存入後為ISO字串；insert、insertBulk與save寫入之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject，詳見各函數與README。
  *
  * @class
  * @param {Object} [opt={}] 輸入設定物件，預設{}
@@ -190,17 +191,113 @@ function WOrmLowdb(opt = {}) {
         return pm
     }
 
+    //reIsoDate, 西元0000-9999年之toISOString()恆為24字元YYYY-MM-DDTHH:mm:ss.sssZ, 字典序即時間序;
+    //年份<0或>9999者帶-yyyyyy-/+yyyyyy-前綴(27字元), 且'+'<'-'<數字, 字典序與時間序顛倒, 故不符此形者視為範圍外
+    let reIsoDate = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+
+    //pathKey, 路徑段(欄名或運算子名,皆已通過cvOrmFind之文法): 過長者截短, 規則同cvOrmFind之訊息(單鍵>30字元取前30加...,
+    //截斷處切開代理對而成孤立之高代理碼元者, cvOrmFind以?取代)
+    let pathKey = (k) => {
+        if (k.length <= 30) {
+            return k
+        }
+        let t = k.slice(0, 30)
+        let c = t.charCodeAt(29)
+        if (c >= 0xD800 && c <= 0xDBFF) {
+            t = `${t.slice(0, 29)}?`
+        }
+        return `${t}...`
+    }
+
+    //pathStr, 路徑字串化: 全路徑>120字元取...加末100字元, 規則同cvOrmFind之訊息
+    let pathStr = (s) => {
+        return s.length > 120 ? `...${s.slice(-100)}` : s
+    }
+
+    //reIdent, 數據之鍵為一般識別字者於路徑以.鍵表示, 其餘以括號法表示
+    let reIdent = /^[\p{L}_$][\p{L}\p{M}\p{N}_$]*$/u
+
+    //pathSeg, 數據之鍵於路徑之表示: 數據之鍵不受條件白名單之欄名文法約束(可含空白,點,括號,引號,換行,孤立代理碼元),
+    //故非一般識別字者以JSON字串括號法表示, 過長者依pathKey截短
+    let pathSeg = (k) => {
+        let t = pathKey(k)
+        return reIdent.test(k) ? `.${t}` : `[${JSON.stringify(t)}]`
+    }
+
+    //isDateNode, 是否為JSON序列化時會經toJSON轉為日期字串之Date: 須有可呼叫之toJSON(此判斷同時避免對每個物件節點都以拋錯探測內部槽),
+    //且以Date.prototype.getTime證明內部槽為Date(不受Symbol.toStringTag、instanceof、被覆寫之getTime影響, 跨realm之Date亦可)
+    let isDateNode = (v) => {
+        if (typeof v.toJSON !== 'function') {
+            return false
+        }
+        try {
+            Date.prototype.getTime.call(v)
+            return true
+        }
+        catch (err) {
+            return false
+        }
+    }
+
+    //chkDataDate, 寫入前之Date範圍檢核(帳本R-DATE-01), 供insert、insertBulk與save於cloneDeep之後(即檢核實際寫入之複本)、readData之前呼叫:
+    //走訪數據複本任何深度之Date, 以JSON.stringify(即寫檔時之序列化, 檢查之值即使用之值)判定, 序列化為字串者須為reIsoDate之形(年份0000-9999),
+    //範圍外(年份<0或>9999)者fail-closed: 拋出invalid data(由呼叫端既有catch走emitError後reject, 整批不寫檔), 不回顯值;
+    //無效Date序列化為null故不檢(既有處置不變); 已是字串者、非Date之toJSON物件(含Buffer)與Map/Set內之Date不檢, 其餘ArrayBuffer視圖(無toJSON者, 序列化時其自有屬性照常輸出)依一般物件走訪;
+    //ks為由根起之鍵序列(陣列索引記number, 物件之鍵記string, 僅於拋出時才組成路徑), seen為已走訪物件集合(進入時加入、不移除):
+    //循環參照遇回邊即略過(仍由寫檔時之JSON序列化報錯), 共用參照(菱形圖)亦只走訪一次, 時間為O(節點+邊)
+    let chkDataDate = (v, ks = [], seen = new WeakSet()) => {
+        if (v === null || typeof v !== 'object' || seen.has(v)) {
+            return
+        }
+        if (ArrayBuffer.isView(v) && typeof v.toJSON === 'function') {
+
+            //Buffer: JSON序列化取其toJSON之輸出({type,data}), 不含自有屬性, 不走訪(避免逐位元組走訪)
+            return
+        }
+        if (isDateNode(v)) {
+            let s = JSON.stringify(v)
+            if (typeof s === 'string' && s.charAt(0) === '"' && !reIsoDate.test(s.slice(1, -1))) {
+                let p = `data${ks.map((k) => (typeof k === 'number' ? `[${k}]` : pathSeg(k))).join('')}`
+                throw new Error(`invalid data: Date year is out of range 0000-9999 at [${pathStr(p)}]`)
+            }
+            return
+        }
+        seen.add(v)
+        if (Array.isArray(v)) {
+
+            //陣列以索引走訪(JSON序列化亦逐索引, 空洞為null)
+            for (let i = 0; i < v.length; i++) {
+                ks.push(i)
+                chkDataDate(v[i], ks, seen)
+                ks.pop()
+            }
+        }
+        else {
+            for (let k of Object.keys(v)) {
+                ks.push(k)
+                chkDataDate(v[k], ks, seen)
+                ks.pop()
+            }
+        }
+    }
+
     //isoFind, 把cvOrmFind所回傳複本內之Date就地轉為ISO字串(轉譯層): 數據以JSON存檔, Date於寫入時已成toISOString()之字串,
     //條件內之Date不轉則恆不命中; 複本僅含null原型物件、密集陣列、純量與有效Date(無共享參照、無環), 就地轉換不影響呼叫端之find
-    let isoFind = (v) => {
+    //轉換所得之字串須為reIsoDate之形(檢查之值即使用之值), 範圍外(年份<0或>9999)者fail-closed: 拋出invalid find(帳本R-FIND-02), 不回顯值, p為路徑
+    let isoFind = (v, p = 'find') => {
         if (v instanceof Date) {
-            return v.toISOString()
+            let s = v.toISOString()
+            if (!reIsoDate.test(s)) {
+                throw new Error(`invalid find: Date year is out of range 0000-9999 at [${pathStr(p)}]`)
+            }
+            return s
         }
         if (v !== null && typeof v === 'object') {
 
             //物件與陣列皆以Object.keys走訪(陣列為密集, 鍵即索引)
+            let isArr = Array.isArray(v)
             for (let k of Object.keys(v)) {
-                v[k] = isoFind(v[k])
+                v[k] = isoFind(v[k], isArr ? `${p}[${k}]` : `${p}.${pathKey(k)}`)
             }
         }
         return v
@@ -360,6 +457,7 @@ function WOrmLowdb(opt = {}) {
      * 查詢數據
      *
      * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
+     * 條件內之Date年份須介於0000-9999，範圍外整批reject；資料庫檔內既有之範圍外Date字串(1.0.34起寫入已拒收範圍外Date)無法以Date條件正確比較(規則同delAll之第6點，見README)
      *
      * @memberOf WOrmLowdb
      * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
@@ -486,6 +584,11 @@ function WOrmLowdb(opt = {}) {
     /**
      * 插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫
      *
+     * 數據內任何深度(頂層欄位、巢狀物件、陣列內)之Date年份須介於0000-9999(序列化為固定24字元之ISO字串，字典序即時間序)，
+     * 範圍外(年份小於0或大於9999，如以new Date(8.64e15)作永不過期哨兵)整批reject且不寫入任何一筆，訊息為invalid data: Date year is out of range 0000-9999 at [路徑]，
+     * 不回顯值，於reject之前發出一次error事件、不發出change事件；無效Date維持序列化為null存入；永不過期請改用null或new Date('9999-12-31T23:59:59.999Z')；
+     * 資料庫檔內既有之範圍外Date字串不遷移，仍無法以Date條件正確比較，詳見README
+     *
      * @memberOf WOrmLowdb
      * @param {Object|Array} data 輸入數據物件或陣列
      * @param {Object} [option={}] 輸入設定物件，預設為{}
@@ -529,6 +632,9 @@ function WOrmLowdb(opt = {}) {
             //check id
             data = procPk(data, 'insert')
 
+            //check Date, 複本內任何深度之Date年份須介於0000-9999, 範圍外整批reject(帳本R-DATE-01)
+            chkDataDate(data)
+
             //read
             let arrOld = await readData()
 
@@ -621,6 +727,7 @@ function WOrmLowdb(opt = {}) {
      * 本函數則整批reject且不寫入任何一筆；同批含重複主鍵者亦視為衝突。確無衝突時兩者結果相同
      * 註: 於本套件不會較insert快，因兩者皆為一次讀檔與一次寫檔，
      * 提供本函數係為與其他w-orm系列套件維持同一組函數，令呼叫端得於各套件間替換而不須改寫呼叫
+     * 註: 數據內任何深度之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject且不寫入任何一筆，規則同insert，詳見insert與README
      *
      * @memberOf WOrmLowdb
      * @param {Object|Array} data 輸入數據物件或陣列
@@ -653,6 +760,9 @@ function WOrmLowdb(opt = {}) {
             //check id
             data = procPk(data, 'insertBulk')
 
+            //check Date, 複本內任何深度之Date年份須介於0000-9999, 範圍外整批reject(帳本R-DATE-01)
+            chkDataDate(data)
+
             //read
             let arrOld = await readData()
 
@@ -721,6 +831,9 @@ function WOrmLowdb(opt = {}) {
     /**
      * 儲存數據，以主鍵為準更新既有數據，未給之欄位保留；主鍵不存在且autoInsert為true時改為插入
      *
+     * 數據內任何深度之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject且不寫入任何一筆(逐筆失敗之ok為0機制不適用)，規則同insert，詳見insert與README；
+     * autoInsert為false而主鍵不存在(不會寫入)者亦先經同一檢核；合併與覆寫路徑寫入之Date皆來自已檢核之數據，已存在於資料庫之字串不檢核
+     *
      * @memberOf WOrmLowdb
      * @param {Object|Array} data 輸入數據物件或陣列
      * @param {Object} [option={}] 輸入設定物件，預設為{}
@@ -753,6 +866,9 @@ function WOrmLowdb(opt = {}) {
             //check id
             data = procPk(data, 'save')
 
+            //check Date, 複本內任何深度之Date年份須介於0000-9999, 範圍外整批reject(帳本R-DATE-01); 合併與覆寫路徑之Date皆來自此複本
+            chkDataDate(data)
+
             //read
             let arrOld = await readData()
 
@@ -1083,7 +1199,7 @@ function WOrmLowdb(opt = {}) {
      * 2. 傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)
      *    一律整批reject，不視為{}，不刪除任何數據。
      * 3. 條件僅支援系列白名單: 欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與
-     *    $in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date；
+     *    $in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date(年份須介於0000-9999，範圍外整批reject，見第6點)；
      *    null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $where $expr $like $ilike等)、
      *    欄位層$and/$or、子查詢、函數值、Symbol鍵、undefined值、空的$nin/$and/$or等一律整批reject，
      *    訊息為invalid find: 原因 at [路徑]，且不刪除任何數據。
@@ -1093,7 +1209,11 @@ function WOrmLowdb(opt = {}) {
      *    空的$nin會reject，$in:[]則為恆假(刪除0筆)。
      * 6. 語意差異(依後端，見README): MongoDB式: $ne(比較值非null時)與$nin會命中欄位為null或缺欄之數據，$ne:null則排除之；
      *    欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
-     *    Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，範圍比較僅在年份0000-9999內正確，見README)。
+     *    Date條件於本後端轉為ISO字串後以字典序比較(與字串型欄位亦會比較)：條件內任何位置之Date其年份須介於0000-9999，
+     *    範圍外(年份小於0或大於9999，如new Date(8.64e15)、new Date(-8.64e15))整批reject，訊息為invalid find: Date year is out of range 0000-9999 at [路徑]，
+     *    不回顯值，不讀檔、不刪除任何數據；數據側自1.0.34起insert、insertBulk與save寫入時已拒收範圍外Date，
+     *    但資料庫檔內既有之範圍外Date字串(舊版以new Date(8.64e15)作永不過期哨兵存入者)仍無法以Date條件正確比較
+     *    (例如{t:{$lt:現在}}會命中哨兵並將其刪除)，請自行清理或改寫，見README。
      *    需明確表達時可用可攜寫法: 排除NULL為{$and:[{f:{$ne:null}},{f:{$ne:x}}]}，含NULL為{$or:[{f:null},{f:{$ne:x}}]}。
      *
      * n與nDeleted皆為實際刪除筆數，不取全表筆數。條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。
@@ -1220,7 +1340,7 @@ export default WOrmLowdb
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sat Oct 17 2026 14:56:45 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 21:48:29 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sat Oct 17 2026 14:56:45 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 21:48:29 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "w-orm-lowdb",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "main": "dist/w-orm-lowdb.umd.js",
   "dependencies": {
     "lowdb": "^7.0.1",
     "mingo": "^7.2.4",
-    "wsemi": "^1.9.19"
+    "wsemi": "^1.9.20"
   },
   "devDependencies": {
-    "w-package-tools": "^1.1.16"
+    "w-package-tools": "^1.1.21"
   },
   "scripts": {
     "test": "mocha --parallel \"test/*.test.mjs\" --timeout 180000",

package/src/WOrmLowdb.mjs

@@ -49,6 +49,7 @@ let kpGqueue = {}
  * 註: 本套件之主鍵欄位固定為id，尚未支援指定其他欄位為主鍵。
  * 註: 本套件之寫入為[整檔讀出、記憶體修改、整檔寫回]，其原子性由行程內之序列化佇列提供，
  * 故僅單一行程內併發成立，跨行程併發不成立，詳見README之併發保證宣告。
+ * 註: 數據以JSON存檔，Date存入後為ISO字串；insert、insertBulk與save寫入之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject，詳見各函數與README。
  *
  * @class
  * @param {Object} [opt={}] 輸入設定物件，預設{}
@@ -143,17 +144,113 @@ function WOrmLowdb(opt = {}) {
         return pm
     }
 
+    //reIsoDate, 西元0000-9999年之toISOString()恆為24字元YYYY-MM-DDTHH:mm:ss.sssZ, 字典序即時間序;
+    //年份<0或>9999者帶-yyyyyy-/+yyyyyy-前綴(27字元), 且'+'<'-'<數字, 字典序與時間序顛倒, 故不符此形者視為範圍外
+    let reIsoDate = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+
+    //pathKey, 路徑段(欄名或運算子名,皆已通過cvOrmFind之文法): 過長者截短, 規則同cvOrmFind之訊息(單鍵>30字元取前30加...,
+    //截斷處切開代理對而成孤立之高代理碼元者, cvOrmFind以?取代)
+    let pathKey = (k) => {
+        if (k.length <= 30) {
+            return k
+        }
+        let t = k.slice(0, 30)
+        let c = t.charCodeAt(29)
+        if (c >= 0xD800 && c <= 0xDBFF) {
+            t = `${t.slice(0, 29)}?`
+        }
+        return `${t}...`
+    }
+
+    //pathStr, 路徑字串化: 全路徑>120字元取...加末100字元, 規則同cvOrmFind之訊息
+    let pathStr = (s) => {
+        return s.length > 120 ? `...${s.slice(-100)}` : s
+    }
+
+    //reIdent, 數據之鍵為一般識別字者於路徑以.鍵表示, 其餘以括號法表示
+    let reIdent = /^[\p{L}_$][\p{L}\p{M}\p{N}_$]*$/u
+
+    //pathSeg, 數據之鍵於路徑之表示: 數據之鍵不受條件白名單之欄名文法約束(可含空白,點,括號,引號,換行,孤立代理碼元),
+    //故非一般識別字者以JSON字串括號法表示, 過長者依pathKey截短
+    let pathSeg = (k) => {
+        let t = pathKey(k)
+        return reIdent.test(k) ? `.${t}` : `[${JSON.stringify(t)}]`
+    }
+
+    //isDateNode, 是否為JSON序列化時會經toJSON轉為日期字串之Date: 須有可呼叫之toJSON(此判斷同時避免對每個物件節點都以拋錯探測內部槽),
+    //且以Date.prototype.getTime證明內部槽為Date(不受Symbol.toStringTag、instanceof、被覆寫之getTime影響, 跨realm之Date亦可)
+    let isDateNode = (v) => {
+        if (typeof v.toJSON !== 'function') {
+            return false
+        }
+        try {
+            Date.prototype.getTime.call(v)
+            return true
+        }
+        catch (err) {
+            return false
+        }
+    }
+
+    //chkDataDate, 寫入前之Date範圍檢核(帳本R-DATE-01), 供insert、insertBulk與save於cloneDeep之後(即檢核實際寫入之複本)、readData之前呼叫:
+    //走訪數據複本任何深度之Date, 以JSON.stringify(即寫檔時之序列化, 檢查之值即使用之值)判定, 序列化為字串者須為reIsoDate之形(年份0000-9999),
+    //範圍外(年份<0或>9999)者fail-closed: 拋出invalid data(由呼叫端既有catch走emitError後reject, 整批不寫檔), 不回顯值;
+    //無效Date序列化為null故不檢(既有處置不變); 已是字串者、非Date之toJSON物件(含Buffer)與Map/Set內之Date不檢, 其餘ArrayBuffer視圖(無toJSON者, 序列化時其自有屬性照常輸出)依一般物件走訪;
+    //ks為由根起之鍵序列(陣列索引記number, 物件之鍵記string, 僅於拋出時才組成路徑), seen為已走訪物件集合(進入時加入、不移除):
+    //循環參照遇回邊即略過(仍由寫檔時之JSON序列化報錯), 共用參照(菱形圖)亦只走訪一次, 時間為O(節點+邊)
+    let chkDataDate = (v, ks = [], seen = new WeakSet()) => {
+        if (v === null || typeof v !== 'object' || seen.has(v)) {
+            return
+        }
+        if (ArrayBuffer.isView(v) && typeof v.toJSON === 'function') {
+
+            //Buffer: JSON序列化取其toJSON之輸出({type,data}), 不含自有屬性, 不走訪(避免逐位元組走訪)
+            return
+        }
+        if (isDateNode(v)) {
+            let s = JSON.stringify(v)
+            if (typeof s === 'string' && s.charAt(0) === '"' && !reIsoDate.test(s.slice(1, -1))) {
+                let p = `data${ks.map((k) => (typeof k === 'number' ? `[${k}]` : pathSeg(k))).join('')}`
+                throw new Error(`invalid data: Date year is out of range 0000-9999 at [${pathStr(p)}]`)
+            }
+            return
+        }
+        seen.add(v)
+        if (Array.isArray(v)) {
+
+            //陣列以索引走訪(JSON序列化亦逐索引, 空洞為null)
+            for (let i = 0; i < v.length; i++) {
+                ks.push(i)
+                chkDataDate(v[i], ks, seen)
+                ks.pop()
+            }
+        }
+        else {
+            for (let k of Object.keys(v)) {
+                ks.push(k)
+                chkDataDate(v[k], ks, seen)
+                ks.pop()
+            }
+        }
+    }
+
     //isoFind, 把cvOrmFind所回傳複本內之Date就地轉為ISO字串(轉譯層): 數據以JSON存檔, Date於寫入時已成toISOString()之字串,
     //條件內之Date不轉則恆不命中; 複本僅含null原型物件、密集陣列、純量與有效Date(無共享參照、無環), 就地轉換不影響呼叫端之find
-    let isoFind = (v) => {
+    //轉換所得之字串須為reIsoDate之形(檢查之值即使用之值), 範圍外(年份<0或>9999)者fail-closed: 拋出invalid find(帳本R-FIND-02), 不回顯值, p為路徑
+    let isoFind = (v, p = 'find') => {
         if (v instanceof Date) {
-            return v.toISOString()
+            let s = v.toISOString()
+            if (!reIsoDate.test(s)) {
+                throw new Error(`invalid find: Date year is out of range 0000-9999 at [${pathStr(p)}]`)
+            }
+            return s
         }
         if (v !== null && typeof v === 'object') {
 
             //物件與陣列皆以Object.keys走訪(陣列為密集, 鍵即索引)
+            let isArr = Array.isArray(v)
             for (let k of Object.keys(v)) {
-                v[k] = isoFind(v[k])
+                v[k] = isoFind(v[k], isArr ? `${p}[${k}]` : `${p}.${pathKey(k)}`)
             }
         }
         return v
@@ -313,6 +410,7 @@ function WOrmLowdb(opt = {}) {
      * 查詢數據
      *
      * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
+     * 條件內之Date年份須介於0000-9999，範圍外整批reject；資料庫檔內既有之範圍外Date字串(1.0.34起寫入已拒收範圍外Date)無法以Date條件正確比較(規則同delAll之第6點，見README)
      *
      * @memberOf WOrmLowdb
      * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
@@ -439,6 +537,11 @@ function WOrmLowdb(opt = {}) {
     /**
      * 插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫
      *
+     * 數據內任何深度(頂層欄位、巢狀物件、陣列內)之Date年份須介於0000-9999(序列化為固定24字元之ISO字串，字典序即時間序)，
+     * 範圍外(年份小於0或大於9999，如以new Date(8.64e15)作永不過期哨兵)整批reject且不寫入任何一筆，訊息為invalid data: Date year is out of range 0000-9999 at [路徑]，
+     * 不回顯值，於reject之前發出一次error事件、不發出change事件；無效Date維持序列化為null存入；永不過期請改用null或new Date('9999-12-31T23:59:59.999Z')；
+     * 資料庫檔內既有之範圍外Date字串不遷移，仍無法以Date條件正確比較，詳見README
+     *
      * @memberOf WOrmLowdb
      * @param {Object|Array} data 輸入數據物件或陣列
      * @param {Object} [option={}] 輸入設定物件，預設為{}
@@ -482,6 +585,9 @@ function WOrmLowdb(opt = {}) {
             //check id
             data = procPk(data, 'insert')
 
+            //check Date, 複本內任何深度之Date年份須介於0000-9999, 範圍外整批reject(帳本R-DATE-01)
+            chkDataDate(data)
+
             //read
             let arrOld = await readData()
 
@@ -574,6 +680,7 @@ function WOrmLowdb(opt = {}) {
      * 本函數則整批reject且不寫入任何一筆；同批含重複主鍵者亦視為衝突。確無衝突時兩者結果相同
      * 註: 於本套件不會較insert快，因兩者皆為一次讀檔與一次寫檔，
      * 提供本函數係為與其他w-orm系列套件維持同一組函數，令呼叫端得於各套件間替換而不須改寫呼叫
+     * 註: 數據內任何深度之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject且不寫入任何一筆，規則同insert，詳見insert與README
      *
      * @memberOf WOrmLowdb
      * @param {Object|Array} data 輸入數據物件或陣列
@@ -606,6 +713,9 @@ function WOrmLowdb(opt = {}) {
             //check id
             data = procPk(data, 'insertBulk')
 
+            //check Date, 複本內任何深度之Date年份須介於0000-9999, 範圍外整批reject(帳本R-DATE-01)
+            chkDataDate(data)
+
             //read
             let arrOld = await readData()
 
@@ -674,6 +784,9 @@ function WOrmLowdb(opt = {}) {
     /**
      * 儲存數據，以主鍵為準更新既有數據，未給之欄位保留；主鍵不存在且autoInsert為true時改為插入
      *
+     * 數據內任何深度之Date年份須介於0000-9999，範圍外(如new Date(8.64e15))整批reject且不寫入任何一筆(逐筆失敗之ok為0機制不適用)，規則同insert，詳見insert與README；
+     * autoInsert為false而主鍵不存在(不會寫入)者亦先經同一檢核；合併與覆寫路徑寫入之Date皆來自已檢核之數據，已存在於資料庫之字串不檢核
+     *
      * @memberOf WOrmLowdb
      * @param {Object|Array} data 輸入數據物件或陣列
      * @param {Object} [option={}] 輸入設定物件，預設為{}
@@ -706,6 +819,9 @@ function WOrmLowdb(opt = {}) {
             //check id
             data = procPk(data, 'save')
 
+            //check Date, 複本內任何深度之Date年份須介於0000-9999, 範圍外整批reject(帳本R-DATE-01); 合併與覆寫路徑之Date皆來自此複本
+            chkDataDate(data)
+
             //read
             let arrOld = await readData()
 
@@ -1036,7 +1152,7 @@ function WOrmLowdb(opt = {}) {
      * 2. 傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)
      *    一律整批reject，不視為{}，不刪除任何數據。
      * 3. 條件僅支援系列白名單: 欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與
-     *    $in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date；
+     *    $in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date(年份須介於0000-9999，範圍外整批reject，見第6點)；
      *    null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $where $expr $like $ilike等)、
      *    欄位層$and/$or、子查詢、函數值、Symbol鍵、undefined值、空的$nin/$and/$or等一律整批reject，
      *    訊息為invalid find: 原因 at [路徑]，且不刪除任何數據。
@@ -1046,7 +1162,11 @@ function WOrmLowdb(opt = {}) {
      *    空的$nin會reject，$in:[]則為恆假(刪除0筆)。
      * 6. 語意差異(依後端，見README): MongoDB式: $ne(比較值非null時)與$nin會命中欄位為null或缺欄之數據，$ne:null則排除之；
      *    欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
-     *    Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，範圍比較僅在年份0000-9999內正確，見README)。
+     *    Date條件於本後端轉為ISO字串後以字典序比較(與字串型欄位亦會比較)：條件內任何位置之Date其年份須介於0000-9999，
+     *    範圍外(年份小於0或大於9999，如new Date(8.64e15)、new Date(-8.64e15))整批reject，訊息為invalid find: Date year is out of range 0000-9999 at [路徑]，
+     *    不回顯值，不讀檔、不刪除任何數據；數據側自1.0.34起insert、insertBulk與save寫入時已拒收範圍外Date，
+     *    但資料庫檔內既有之範圍外Date字串(舊版以new Date(8.64e15)作永不過期哨兵存入者)仍無法以Date條件正確比較
+     *    (例如{t:{$lt:現在}}會命中哨兵並將其刪除)，請自行清理或改寫，見README。
      *    需明確表達時可用可攜寫法: 排除NULL為{$and:[{f:{$ne:null}},{f:{$ne:x}}]}，含NULL為{$or:[{f:null},{f:{$ne:x}}]}。
      *
      * n與nDeleted皆為實際刪除筆數，不取全表筆數。條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。