w-orm-lowdb 1.0.30 → 1.0.32

package/docs/WOrmLowdb.mjs.html

@@ -66,6 +66,7 @@ import isestr from 'wsemi/src/isestr.mjs'
 import iseobj from 'wsemi/src/iseobj.mjs'
 import isearr from 'wsemi/src/isearr.mjs'
 import haskey from 'wsemi/src/haskey.mjs'
+import cvOrmFind from 'wsemi/src/cvOrmFind.mjs'
 
 
 //kpGqueue, 以資料庫檔案路徑為鍵之全域序列化佇列, 詳見下方serialize說明
@@ -189,6 +190,64 @@ function WOrmLowdb(opt = {}) {
         return pm
     }
 
+    //isoFind, 把cvOrmFind所回傳複本內之Date就地轉為ISO字串(轉譯層): 數據以JSON存檔, Date於寫入時已成toISOString()之字串,
+    //條件內之Date不轉則恆不命中; 複本僅含null原型物件、密集陣列、純量與有效Date(無共享參照、無環), 就地轉換不影響呼叫端之find
+    let isoFind = (v) => {
+        if (v instanceof Date) {
+            return v.toISOString()
+        }
+        if (v !== null && typeof v === 'object') {
+
+            //物件與陣列皆以Object.keys走訪(陣列為密集, 鍵即索引)
+            for (let k of Object.keys(v)) {
+                v[k] = isoFind(v[k])
+            }
+        }
+        return v
+    }
+
+    //hasProtoName, 檢核後複本之欄名是否同於Object.prototype之成員(constructor、toString、valueOf、hasOwnProperty等):
+    //此類欄名屬白名單內之合法欄名, 但mingo以屬性存取取值, 數據無此自有欄位時會取到繼承之成員(函數)而非缺欄,
+    //使{constructor:null}無命中、{constructor:{$ne:null}}命中全部(delAll因而刪光); 欄名只會出現於複本之鍵(含$and/$or內之子條件)
+    let hasProtoName = (fc) => {
+        for (let k of Object.keys(fc)) {
+            if (k === '$and' || k === '$or') {
+                for (let sub of fc[k]) {
+                    if (hasProtoName(sub)) {
+                        return true
+                    }
+                }
+            }
+            else if (k in Object.prototype) {
+                return true
+            }
+        }
+        return false
+    }
+
+    //mkMatch, 依檢核後複本建立逐筆命中判定, select與delAll共用同一判定(系列最低要求①: select命中之數據即delAll刪除之數據);
+    //欄名同於Object.prototype成員者, 改以null原型之淺複本(只含自有可列舉欄位)判定, 令其與一般不存在之欄位同為缺欄語意, 命中者仍回傳原數據
+    let mkMatch = (fc) => {
+        let q = new Query(fc)
+        if (!hasProtoName(fc)) {
+            return (v) => q.test(v)
+        }
+        return (v) => q.test(v !== null && typeof v === 'object' ? Object.assign(Object.create(null), v) : v)
+    }
+
+    //procFind, 條件之入口檢核(帳本R-FIND-01), 供select與delAll於serialize佇列之外、讀取之前呼叫:
+    //不合白名單者發出error事件(於reject之前)並回{err}, 由呼叫端reject, 不占用佇列; 合法者回{fc}為全新複本(null原型, 與呼叫端之find脫勾),
+    //其後一律只用此複本; 複本無自有鍵(未給、undefined、{})為全部
+    let procFind = (mode, find) => {
+        try {
+            return { fc: isoFind(cvOrmFind(find)) }
+        }
+        catch (err) {
+            emitError(mode, null, err)
+            return { err }
+        }
+    }
+
     //emitChange, 資料實際異動成功後發出, 事件僅為附加通知不承擔回傳義務
     //一律包try/catch, 令訂閱函數自身拋錯不影響本次操作之結果
     let emitChange = (mode, data, res) => {
@@ -300,11 +359,15 @@ function WOrmLowdb(opt = {}) {
     /**
      * 查詢數據
      *
+     * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
+     *
      * @memberOf WOrmLowdb
-     * @param {Object} [find={}] 輸入查詢條件物件
+     * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
      * @returns {Promise} 回傳Promise，resolve回傳數據陣列，無符合數據回傳空陣列，reject回傳錯誤訊息
      */
-    async function selectCore(find = {}) {
+    async function selectCore(find) {
+
+        //find, 入口檢核後之複本(procFind), 不再讀取呼叫端之條件
         let isErr = false
 
         //res
@@ -314,15 +377,11 @@ function WOrmLowdb(opt = {}) {
             //ltdt
             let ltdt = await getData()
 
-            //filter
-            if (iseobj(find)) {
-
-                //q
-                let q = new Query(find)
-                // console.log('q', q)
+            //filter, 複本無自有鍵(未給、undefined、{})為全部
+            if (Reflect.ownKeys(find).length > 0) {
 
-                //find
-                res = q.find(ltdt).all()
+                //find, 與delAll共用同一逐筆判定
+                res = ltdt.filter(mkMatch(find))
                 // console.log('res', res)
 
             }
@@ -354,7 +413,14 @@ function WOrmLowdb(opt = {}) {
         return res
     }
     async function select(find = {}) {
-        return serialize(() => selectCore(find))
+
+        //check find, 置於serialize佇列之外, 錯誤不占佇列(R-FIND-01)
+        let pf = procFind('select', find)
+        if (pf.err) {
+            return Promise.reject(pf.err)
+        }
+
+        return serialize(() => selectCore(pf.fc))
     }
 
     /**
@@ -1009,13 +1075,36 @@ function WOrmLowdb(opt = {}) {
     }
 
     /**
-     * 刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表
+     * 依條件刪除多筆數據(破壞性操作，須審慎使用，非必要不用；刪除單筆請用del)
+     *
+     * 使用須知:
+     * 1. 不給條件即刪除全部數據: find未給、為undefined或為{}時，刪除資料表內全部數據，不另行確認。
+     *    給了條件才是部分刪除。
+     * 2. 傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)
+     *    一律整批reject，不視為{}，不刪除任何數據。
+     * 3. 條件僅支援系列白名單: 欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與
+     *    $in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date；
+     *    null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $where $expr $like $ilike等)、
+     *    欄位層$and/$or、子查詢、函數值、Symbol鍵、undefined值、空的$nin/$and/$or等一律整批reject，
+     *    訊息為invalid find: 原因 at [路徑]，且不刪除任何數據。
+     * 4. 與select共用同一檢核與同一條件，select(find)命中之數據即本函數刪除之數據；
+     *    建議先以select(find)確認命中範圍再刪除(useCache開啟且他行程已寫入時，select可能回傳快取，而本函數一律直讀資料庫)。
+     * 5. 條件值若來自可能為undefined、null或空陣列之變數，呼叫端須先自行判斷；undefined值會reject而非被忽略，
+     *    空的$nin會reject，$in:[]則為恆假(刪除0筆)。
+     * 6. 語意差異(依後端，見README): MongoDB式: $ne(比較值非null時)與$nin會命中欄位為null或缺欄之數據，$ne:null則排除之；
+     *    欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
+     *    Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，範圍比較僅在年份0000-9999內正確，見README)。
+     *    需明確表達時可用可攜寫法: 排除NULL為{$and:[{f:{$ne:null}},{f:{$ne:x}}]}，含NULL為{$or:[{f:null},{f:{$ne:x}}]}。
+     *
+     * n與nDeleted皆為實際刪除筆數，不取全表筆數。條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。
      *
      * @memberOf WOrmLowdb
-     * @param {Object} [find={}] 輸入刪除條件物件
-     * @returns {Promise} 回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，n與nDeleted同為實際刪除筆數，reject回傳錯誤訊息
+     * @param {Object} [find={}] 輸入刪除條件物件，不給予find則代表刪除全部數據
+     * @returns {Promise} 回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，reject回傳錯誤訊息
      */
-    async function delAllCore(find = {}) {
+    async function delAllCore(find) {
+
+        //find, 入口檢核後之複本(procFind), 不再讀取呼叫端之條件
         let isErr = false
 
         //res
@@ -1029,15 +1118,14 @@ function WOrmLowdb(opt = {}) {
             let nAll = size(arrOld)
             let nDel = 0
             let arrNew = null
-            if (iseobj(find)) {
+            if (Reflect.ownKeys(find).length > 0) {
 
-                //q
-                let q = new Query(find)
-                // console.log('q', q)
+                //match, 與select共用同一逐筆判定
+                let match = mkMatch(find)
 
                 //filter, 以與select同一條件逐筆判定, 保留未命中者
                 arrNew = filter(arrOld, (v) => {
-                    return !q.test(v)
+                    return !match(v)
                 })
 
                 //nDel
@@ -1094,7 +1182,14 @@ function WOrmLowdb(opt = {}) {
         return res
     }
     async function delAll(find = {}) {
-        return serialize(() => delAllCore(find))
+
+        //check find, 置於serialize佇列之外, 錯誤不占佇列(R-FIND-01)
+        let pf = procFind('delAll', find)
+        if (pf.err) {
+            return Promise.reject(pf.err)
+        }
+
+        return serialize(() => delAllCore(pf.fc))
     }
 
     //bind
@@ -1125,7 +1220,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 10 2026 22:41:39 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 Sat Oct 17 2026 14:56:45 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 10 2026 22:41:39 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 Sat Oct 17 2026 14:56:45 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-basic.mjs

@@ -156,7 +156,7 @@ async function test() {
     let spc = await wo.select({ '$or': [{ '$and': [{ value: { '$ne': 123 } }, { value: { '$in': [123, 321, 123.456, 456] } }, { value: { '$nin': [456, 654] } }] }, { '$or': [{ value: { '$lte': -1 } }, { value: { '$gte': 400 } }] }] })
     console.log('select by $or, $and, $ne, $in, $nin', spc)
 
-    // //select by regex //mingo不支援regex
+    // //select by regex //系列條件白名單不支援$regex(含$options), 會整批reject(invalid find: unsupported operator), 須改為select後自行過濾
     // let sr = await wo.select({ name: { $regex: 'PeT', $options: '$i' } })
     // console.log('selectReg', sr)
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "w-orm-lowdb",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "main": "dist/w-orm-lowdb.umd.js",
   "dependencies": {
     "lowdb": "^7.0.1",
     "mingo": "^7.2.4",
-    "wsemi": "^1.9.11"
+    "wsemi": "^1.9.19"
   },
   "devDependencies": {
     "w-package-tools": "^1.1.16"

package/src/WOrmLowdb.mjs

@@ -19,6 +19,7 @@ import isestr from 'wsemi/src/isestr.mjs'
 import iseobj from 'wsemi/src/iseobj.mjs'
 import isearr from 'wsemi/src/isearr.mjs'
 import haskey from 'wsemi/src/haskey.mjs'
+import cvOrmFind from 'wsemi/src/cvOrmFind.mjs'
 
 
 //kpGqueue, 以資料庫檔案路徑為鍵之全域序列化佇列, 詳見下方serialize說明
@@ -142,6 +143,64 @@ function WOrmLowdb(opt = {}) {
         return pm
     }
 
+    //isoFind, 把cvOrmFind所回傳複本內之Date就地轉為ISO字串(轉譯層): 數據以JSON存檔, Date於寫入時已成toISOString()之字串,
+    //條件內之Date不轉則恆不命中; 複本僅含null原型物件、密集陣列、純量與有效Date(無共享參照、無環), 就地轉換不影響呼叫端之find
+    let isoFind = (v) => {
+        if (v instanceof Date) {
+            return v.toISOString()
+        }
+        if (v !== null && typeof v === 'object') {
+
+            //物件與陣列皆以Object.keys走訪(陣列為密集, 鍵即索引)
+            for (let k of Object.keys(v)) {
+                v[k] = isoFind(v[k])
+            }
+        }
+        return v
+    }
+
+    //hasProtoName, 檢核後複本之欄名是否同於Object.prototype之成員(constructor、toString、valueOf、hasOwnProperty等):
+    //此類欄名屬白名單內之合法欄名, 但mingo以屬性存取取值, 數據無此自有欄位時會取到繼承之成員(函數)而非缺欄,
+    //使{constructor:null}無命中、{constructor:{$ne:null}}命中全部(delAll因而刪光); 欄名只會出現於複本之鍵(含$and/$or內之子條件)
+    let hasProtoName = (fc) => {
+        for (let k of Object.keys(fc)) {
+            if (k === '$and' || k === '$or') {
+                for (let sub of fc[k]) {
+                    if (hasProtoName(sub)) {
+                        return true
+                    }
+                }
+            }
+            else if (k in Object.prototype) {
+                return true
+            }
+        }
+        return false
+    }
+
+    //mkMatch, 依檢核後複本建立逐筆命中判定, select與delAll共用同一判定(系列最低要求①: select命中之數據即delAll刪除之數據);
+    //欄名同於Object.prototype成員者, 改以null原型之淺複本(只含自有可列舉欄位)判定, 令其與一般不存在之欄位同為缺欄語意, 命中者仍回傳原數據
+    let mkMatch = (fc) => {
+        let q = new Query(fc)
+        if (!hasProtoName(fc)) {
+            return (v) => q.test(v)
+        }
+        return (v) => q.test(v !== null && typeof v === 'object' ? Object.assign(Object.create(null), v) : v)
+    }
+
+    //procFind, 條件之入口檢核(帳本R-FIND-01), 供select與delAll於serialize佇列之外、讀取之前呼叫:
+    //不合白名單者發出error事件(於reject之前)並回{err}, 由呼叫端reject, 不占用佇列; 合法者回{fc}為全新複本(null原型, 與呼叫端之find脫勾),
+    //其後一律只用此複本; 複本無自有鍵(未給、undefined、{})為全部
+    let procFind = (mode, find) => {
+        try {
+            return { fc: isoFind(cvOrmFind(find)) }
+        }
+        catch (err) {
+            emitError(mode, null, err)
+            return { err }
+        }
+    }
+
     //emitChange, 資料實際異動成功後發出, 事件僅為附加通知不承擔回傳義務
     //一律包try/catch, 令訂閱函數自身拋錯不影響本次操作之結果
     let emitChange = (mode, data, res) => {
@@ -253,11 +312,15 @@ function WOrmLowdb(opt = {}) {
     /**
      * 查詢數據
      *
+     * 條件find僅支援系列白名單(規則同delAll之第1-3點，見delAll)，與delAll共用同一檢核，select(find)命中之數據即delAll(find)刪除之數據
+     *
      * @memberOf WOrmLowdb
-     * @param {Object} [find={}] 輸入查詢條件物件
+     * @param {Object} [find={}] 輸入查詢條件物件(系列白名單，規則同delAll之第1-3點); 未給、undefined或{}回傳全部數據; 非條件物件或白名單外運算子整批reject
      * @returns {Promise} 回傳Promise，resolve回傳數據陣列，無符合數據回傳空陣列，reject回傳錯誤訊息
      */
-    async function selectCore(find = {}) {
+    async function selectCore(find) {
+
+        //find, 入口檢核後之複本(procFind), 不再讀取呼叫端之條件
         let isErr = false
 
         //res
@@ -267,15 +330,11 @@ function WOrmLowdb(opt = {}) {
             //ltdt
             let ltdt = await getData()
 
-            //filter
-            if (iseobj(find)) {
-
-                //q
-                let q = new Query(find)
-                // console.log('q', q)
+            //filter, 複本無自有鍵(未給、undefined、{})為全部
+            if (Reflect.ownKeys(find).length > 0) {
 
-                //find
-                res = q.find(ltdt).all()
+                //find, 與delAll共用同一逐筆判定
+                res = ltdt.filter(mkMatch(find))
                 // console.log('res', res)
 
             }
@@ -307,7 +366,14 @@ function WOrmLowdb(opt = {}) {
         return res
     }
     async function select(find = {}) {
-        return serialize(() => selectCore(find))
+
+        //check find, 置於serialize佇列之外, 錯誤不占佇列(R-FIND-01)
+        let pf = procFind('select', find)
+        if (pf.err) {
+            return Promise.reject(pf.err)
+        }
+
+        return serialize(() => selectCore(pf.fc))
     }
 
     /**
@@ -962,13 +1028,36 @@ function WOrmLowdb(opt = {}) {
     }
 
     /**
-     * 刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表
+     * 依條件刪除多筆數據(破壞性操作，須審慎使用，非必要不用；刪除單筆請用del)
+     *
+     * 使用須知:
+     * 1. 不給條件即刪除全部數據: find未給、為undefined或為{}時，刪除資料表內全部數據，不另行確認。
+     *    給了條件才是部分刪除。
+     * 2. 傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)
+     *    一律整批reject，不視為{}，不刪除任何數據。
+     * 3. 條件僅支援系列白名單: 欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與
+     *    $in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)。純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date；
+     *    null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $where $expr $like $ilike等)、
+     *    欄位層$and/$or、子查詢、函數值、Symbol鍵、undefined值、空的$nin/$and/$or等一律整批reject，
+     *    訊息為invalid find: 原因 at [路徑]，且不刪除任何數據。
+     * 4. 與select共用同一檢核與同一條件，select(find)命中之數據即本函數刪除之數據；
+     *    建議先以select(find)確認命中範圍再刪除(useCache開啟且他行程已寫入時，select可能回傳快取，而本函數一律直讀資料庫)。
+     * 5. 條件值若來自可能為undefined、null或空陣列之變數，呼叫端須先自行判斷；undefined值會reject而非被忽略，
+     *    空的$nin會reject，$in:[]則為恆假(刪除0筆)。
+     * 6. 語意差異(依後端，見README): MongoDB式: $ne(比較值非null時)與$nin會命中欄位為null或缺欄之數據，$ne:null則排除之；
+     *    欄名同於Object.prototype成員(constructor、toString等)者，數據無此自有欄位時視為缺欄；
+     *    Date條件於本後端轉為ISO字串後比較(與字串型欄位亦會比較，範圍比較僅在年份0000-9999內正確，見README)。
+     *    需明確表達時可用可攜寫法: 排除NULL為{$and:[{f:{$ne:null}},{f:{$ne:x}}]}，含NULL為{$or:[{f:null},{f:{$ne:x}}]}。
+     *
+     * n與nDeleted皆為實際刪除筆數，不取全表筆數。條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。
      *
      * @memberOf WOrmLowdb
-     * @param {Object} [find={}] 輸入刪除條件物件
-     * @returns {Promise} 回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，n與nDeleted同為實際刪除筆數，reject回傳錯誤訊息
+     * @param {Object} [find={}] 輸入刪除條件物件，不給予find則代表刪除全部數據
+     * @returns {Promise} 回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，reject回傳錯誤訊息
      */
-    async function delAllCore(find = {}) {
+    async function delAllCore(find) {
+
+        //find, 入口檢核後之複本(procFind), 不再讀取呼叫端之條件
         let isErr = false
 
         //res
@@ -982,15 +1071,14 @@ function WOrmLowdb(opt = {}) {
             let nAll = size(arrOld)
             let nDel = 0
             let arrNew = null
-            if (iseobj(find)) {
+            if (Reflect.ownKeys(find).length > 0) {
 
-                //q
-                let q = new Query(find)
-                // console.log('q', q)
+                //match, 與select共用同一逐筆判定
+                let match = mkMatch(find)
 
                 //filter, 以與select同一條件逐筆判定, 保留未命中者
                 arrNew = filter(arrOld, (v) => {
-                    return !q.test(v)
+                    return !match(v)
                 })
 
                 //nDel
@@ -1047,7 +1135,14 @@ function WOrmLowdb(opt = {}) {
         return res
     }
     async function delAll(find = {}) {
-        return serialize(() => delAllCore(find))
+
+        //check find, 置於serialize佇列之外, 錯誤不占佇列(R-FIND-01)
+        let pf = procFind('delAll', find)
+        if (pf.err) {
+            return Promise.reject(pf.err)
+        }
+
+        return serialize(() => delAllCore(pf.fc))
     }
 
     //bind