w-orm-lowdb 1.0.32 → 1.0.33

package/docs/WOrmLowdb.mjs.html

@@ -190,17 +190,46 @@ 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
+    }
+
     //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 +389,7 @@ function WOrmLowdb(opt = {}) {
      * 查詢數據
      *
      * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
+     * 條件內之Date年份須介於0000-9999，範圍外整批reject；數據側已存入之範圍外Date無法以Date條件正確比較(規則同delAll之第6點，見README)
      *
      * @memberOf WOrmLowdb
      * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
@@ -1083,7 +1113,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 +1123,10 @@ 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 [路徑]，
+     *    不回顯值，不讀檔、不刪除任何數據；數據側已存入之範圍外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 +1253,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 20:07:22 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 20:07:22 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.33",
   "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

@@ -143,17 +143,46 @@ 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
+    }
+
     //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 +342,7 @@ function WOrmLowdb(opt = {}) {
      * 查詢數據
      *
      * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
+     * 條件內之Date年份須介於0000-9999，範圍外整批reject；數據側已存入之範圍外Date無法以Date條件正確比較(規則同delAll之第6點，見README)
      *
      * @memberOf WOrmLowdb
      * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
@@ -1036,7 +1066,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 +1076,10 @@ 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 [路徑]，
+     *    不回顯值，不讀檔、不刪除任何數據；數據側已存入之範圍外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}，不視為錯誤。