w-orm-lowdb 1.0.33 → 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>
     
 
@@ -540,8 +541,9 @@ null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $r
 欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
 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 [路徑]，
-不回顯值，不讀檔、不刪除任何數據；數據側已存入之範圍外Date(如以new Date(8.64e15)作永不過期哨兵)寫入行為不變，
-但此類資料無法以Date條件正確比較(例如{t:{$lt:現在}}會命中哨兵並將其刪除)，見README。
+不回顯值，不讀檔、不刪除任何數據；數據側自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>
@@ -550,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#line1091">line 1091</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line1178">line 1178</a>
     </li></ul></dd>
     
 
@@ -728,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#line909">line 909</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line995">line 995</a>
     </li></ul></dd>
     
 
@@ -887,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#line612">line 612</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line689">line 689</a>
     </li></ul></dd>
     
 
@@ -1048,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#line478">line 478</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line551">line 551</a>
     </li></ul></dd>
     
 
@@ -1335,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#line713">line 713</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line796">line 796</a>
     </li></ul></dd>
     
 
@@ -1631,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#line419">line 419</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line487">line 487</a>
     </li></ul></dd>
     
 
@@ -1785,13 +1794,13 @@ 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)刪除之數據
-條件內之Date年份須介於0000-9999，範圍外整批reject；數據側已存入之範圍外Date無法以Date條件正確比較(規則同delAll之第6點，見README)</p></li></ul></dd>
+條件內之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#line351">line 351</a>
+        <a href="WOrmLowdb.mjs.html">WOrmLowdb.mjs</a>, <a href="WOrmLowdb.mjs.html#line419">line 419</a>
     </li></ul></dd>
     
 
@@ -1976,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>
     
 
@@ -2060,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 Mon Oct 19 2026 20:07:22 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={}] 輸入設定物件，預設{}
@@ -213,6 +214,73 @@ function WOrmLowdb(opt = {}) {
         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
     //轉換所得之字串須為reIsoDate之形(檢查之值即使用之值), 範圍外(年份<0或>9999)者fail-closed: 拋出invalid find(帳本R-FIND-02), 不回顯值, p為路徑
@@ -389,7 +457,7 @@ function WOrmLowdb(opt = {}) {
      * 查詢數據
      *
      * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
-     * 條件內之Date年份須介於0000-9999，範圍外整批reject；數據側已存入之範圍外Date無法以Date條件正確比較(規則同delAll之第6點，見README)
+     * 條件內之Date年份須介於0000-9999，範圍外整批reject；資料庫檔內既有之範圍外Date字串(1.0.34起寫入已拒收範圍外Date)無法以Date條件正確比較(規則同delAll之第6點，見README)
      *
      * @memberOf WOrmLowdb
      * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
@@ -516,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={}] 輸入設定物件，預設為{}
@@ -559,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()
 
@@ -651,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 輸入數據物件或陣列
@@ -683,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()
 
@@ -751,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={}] 輸入設定物件，預設為{}
@@ -783,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()
 
@@ -1125,8 +1211,9 @@ function WOrmLowdb(opt = {}) {
      *    欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
      *    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 [路徑]，
-     *    不回顯值，不讀檔、不刪除任何數據；數據側已存入之範圍外Date(如以new Date(8.64e15)作永不過期哨兵)寫入行為不變，
-     *    但此類資料無法以Date條件正確比較(例如{t:{$lt:現在}}會命中哨兵並將其刪除)，見README。
+     *    不回顯值，不讀檔、不刪除任何數據；數據側自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}，不視為錯誤。
@@ -1253,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 Mon Oct 19 2026 20:07:22 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 Mon Oct 19 2026 20:07:22 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,6 +1,6 @@
 {
   "name": "w-orm-lowdb",
-  "version": "1.0.33",
+  "version": "1.0.34",
   "main": "dist/w-orm-lowdb.umd.js",
   "dependencies": {
     "lowdb": "^7.0.1",

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={}] 輸入設定物件，預設{}
@@ -166,6 +167,73 @@ function WOrmLowdb(opt = {}) {
         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
     //轉換所得之字串須為reIsoDate之形(檢查之值即使用之值), 範圍外(年份<0或>9999)者fail-closed: 拋出invalid find(帳本R-FIND-02), 不回顯值, p為路徑
@@ -342,7 +410,7 @@ function WOrmLowdb(opt = {}) {
      * 查詢數據
      *
      * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
-     * 條件內之Date年份須介於0000-9999，範圍外整批reject；數據側已存入之範圍外Date無法以Date條件正確比較(規則同delAll之第6點，見README)
+     * 條件內之Date年份須介於0000-9999，範圍外整批reject；資料庫檔內既有之範圍外Date字串(1.0.34起寫入已拒收範圍外Date)無法以Date條件正確比較(規則同delAll之第6點，見README)
      *
      * @memberOf WOrmLowdb
      * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
@@ -469,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={}] 輸入設定物件，預設為{}
@@ -512,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()
 
@@ -604,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 輸入數據物件或陣列
@@ -636,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()
 
@@ -704,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={}] 輸入設定物件，預設為{}
@@ -736,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()
 
@@ -1078,8 +1164,9 @@ function WOrmLowdb(opt = {}) {
      *    欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
      *    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 [路徑]，
-     *    不回顯值，不讀檔、不刪除任何數據；數據側已存入之範圍外Date(如以new Date(8.64e15)作永不過期哨兵)寫入行為不變，
-     *    但此類資料無法以Date條件正確比較(例如{t:{$lt:現在}}會命中哨兵並將其刪除)，見README。
+     *    不回顯值，不讀檔、不刪除任何數據；數據側自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}，不視為錯誤。

package/test/lib/leaves.mjs

@@ -0,0 +1,46 @@
+import assert from 'assert'
+
+
+//呼叫端傳入物件之逐節點快照(unit-find-whitelist與unit-date-write共用, 只定義一處)
+
+//timeOf, 以內部槽取Date之時間值, 非Date回傳undefined(跨realm、子類別、被改Symbol.toStringTag之Date皆可辨)
+let timeOf = (v) => {
+    try {
+        return Date.prototype.getTime.call(v)
+    }
+    catch (err) {
+        return undefined
+    }
+}
+
+//leaves: 取物件之全部節點(物件節點記鍵序,Date節點記毫秒,皆記參照), 供reject後確認呼叫端實際傳入之同一物件逐節點未被改動; 物件須為無環
+let leaves = (v, p = 'root', out = []) => {
+    let ms = timeOf(v)
+    if (ms !== undefined) {
+        out.push({ p, ref: v, ms })
+    }
+    else if (v !== null && typeof v === 'object') {
+        out.push({ p, ref: v, keys: Object.keys(v).join(',') })
+        for (let k of Object.keys(v)) {
+            leaves(v[k], `${p}.${k}`, out)
+        }
+    }
+    else {
+        out.push({ p, ref: v })
+    }
+    return out
+}
+
+//chkSame: 兩次leaves之結果須逐節點相同(參照、毫秒、鍵序)
+let chkSame = (a, b) => {
+    assert.strict.equal(a.length, b.length, 'object should keep the same number of nodes')
+    for (let i = 0; i < a.length; i++) {
+        assert.strict.equal(a[i].p, b[i].p)
+        assert.strict.equal(a[i].ref, b[i].ref, `${a[i].p} should keep the same reference or value`)
+        assert.strict.equal(a[i].ms, b[i].ms, `${a[i].p} should keep the same time value`)
+        assert.strict.equal(a[i].keys, b[i].keys, `${a[i].p} should keep the same keys`)
+    }
+}
+
+
+export { timeOf, leaves, chkSame }

package/test/lib/mkObserver.mjs

@@ -0,0 +1,52 @@
+//呼叫觀測器(unit-find-whitelist與unit-date-write共用, 只定義一處)
+
+//tick, 讓出一個macrotask, 令延遲發出之事件有機會發出
+let tick = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+//mkObserver, 建立呼叫觀測器: 事件記錄於evs, 每筆error事件附帶發出當下呼叫端之await是否已恢復(settledAtEmit, 即呼叫端可觀察之先後)
+let mkObserver = (wo) => {
+    let evs = []
+    let cur = { settled: false }
+    wo.on('error', function(mode, data, err) {
+        evs.push({ t: 'error', mode, data, err, settledAtEmit: cur.settled })
+    })
+    wo.on('change', function(mode) {
+        evs.push({ t: 'change', mode })
+    })
+
+    //run, 執行call()(回傳Promise之函數)並回傳{ ok, val, err, nAtSettle, probe, evs }, nAtSettle為結果定案當下之事件數,
+    //probe為結果定案當下(同一microtask鏈內, 尚未讓出macrotask)呼叫probeFn()之回傳, evs為再讓出一個macrotask後之事件
+    let run = async(call, probeFn = null) => {
+        evs.length = 0
+        cur = { settled: false }
+        let out = { ok: false, val: null, err: null, nAtSettle: 0, probe: null, evs: [] }
+        try {
+            out.val = await call()
+            out.ok = true
+        }
+        catch (err) {
+            out.err = err
+        }
+        cur.settled = true
+        out.nAtSettle = evs.length
+        out.probe = probeFn ? probeFn() : null
+        await tick()
+        out.evs = evs.slice()
+        return out
+    }
+
+    //invoke, 呼叫wo[fn](arg)
+    let invoke = (fn, arg, probeFn = null) => {
+        return run(() => wo[fn](arg), probeFn)
+    }
+
+    //clear
+    let clear = () => {
+        evs.length = 0
+    }
+
+    return { run, invoke, clear }
+}
+
+
+export { tick, mkObserver }