@k3000/store 1.9.1 → 1.9.2

package/README.md

@@ -367,3 +367,36 @@ const recent = storage.user.indexByCreatedAt({ after: new Date('2024-01-01') })
 **备份与迁移补充**
 
 - 每次 `upgrade` 会将旧版本目录完整复制为备份；迁移仅需复制整个存储目录到目标项目，并确保使用兼容版本的库与正确密码即可。
+
+# 缺点与不足
+
+这个项目实现了一个轻量级的、无依赖的、基于文件的结构化存储系统（类似简易数据库），虽然设计精巧且自给自足，但在生产环境中使用存在显著的风险，**“不建议用作主数据库”**。
+
+以下是存在的主要缺点与不足：
+
+**1. 严重的安全与稳定性隐患 (Critical)**
+
+   非异步 I/O 阻塞事件循环: architect.mjs 中大量使用了 readSync, writeSync, openSync 等同步文件操作。Node.js 是单线程的，这意味着每次读写数据库都会完全卡死整个应用程序的事件循环，直到文件操作完成。在高并发或大文件读写时，会导致服务器无响应。
+   缺乏 Crash Safety (崩溃安全): 没有发现 Write-Ahead Log (WAL) 或事务日志机制。依赖内存缓存 (needSave 标志) 和每 3 秒的定时器 (Storage) 落盘。
+   数据丢失风险: 如果进程在 3 秒间隔内崩溃或断电，这期间的所有数据修改将永久丢失。
+   文件损坏风险: 如果在写入数据的瞬间崩溃，文件可能只写了一半，导致数据库彻底损坏且无法恢复。
+   并发控制脆弱: 仅依赖文件头部的“打开计数器”来防止并发，并建议“防止同目录并发写入”。这无法有效处理多进程环境，容易导致竞态条件（Race Condition）和数据错乱。
+
+**2. 性能与扩展性瓶颈**
+
+   内存占用高: 索引（Indexes）似乎是全量加载到内存中的 (#index Set)。对于大数据集，这会消耗大量 RAM。
+   写入性能随数据量下降: 索引维护使用了 splice 插入 (set2 方法中)，这是一个 O(N) 操作。随着数据量增加，插入新数据并维护排序索引的速度会越来越慢。
+   缓存限制: 硬编码了 MaxSize = 99999 的缓存上限，超过后直接落盘。这种策略比较生硬。
+
+**3. 功能局限性**
+
+   查询能力有限: 虽然支持 filter, find, indexBy...，但本质上很多操作是在遍历内存或文件。不支持复杂的 SQL 语义（如复杂的 JOIN, GROUP BY, 子查询等）。flat 系列方法仅提供了非常基础的关联能力。
+   缺乏生态工具: 作为一个自定义的二进制格式，没有现成的 GUI 客户端、备份工具、数据迁移工具（除了自带的 upgrade）、可视化监控等。调试数据非常困难，只能写代码查。
+
+**4. 安全性细节**
+
+   密码学实践不标准:
+   使用 md5(key) 作为后续密钥派生的基础。MD5 如今被认为是不够安全的（抗碰撞性弱），虽然后续用了 scrypt，但起手式用 MD5 会降低整体熵值。
+   IV 来源于 MD5 的中间字节，这种非随机生成的 IV 在某些加密场景下可能是不安全的。
+   测试代码中暗示用户密码可能只存了 MD5 (String('存MD5指'))，这是过时的做法，现代应用应使用 bcrypt/argon2。
+   总结建议

package/architect.mjs

@@ -1,7 +1,7 @@
-import {openSync, closeSync, readFileSync, writeFileSync, readSync, writeSync, unlinkSync, mkdirSync, existsSync} from "node:fs"
-import {createCipheriv, createDecipheriv, createHash, scryptSync} from "node:crypto"
-import {fileURLToPath} from 'node:url'
-import {dirname} from 'node:path'
+import { promises as fs, existsSync } from "node:fs"
+import { createCipheriv, createDecipheriv, createHash, scryptSync } from "node:crypto"
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
 /**
  * 结构化存储运行时核心模块
  * - 定义数据读写协议（定长 Buffer 字段、外置文件字段）
@@ -36,7 +36,7 @@ Array.prototype.eachFlat = function (array, predicate, map) {
 
             if (result.length === 0) return item
 
-            return result.map(entry => map({...entry, ...item}, entry))
+            return result.map(entry => map({ ...entry, ...item }, entry))
 
         }).flat()
 
@@ -48,7 +48,7 @@ Array.prototype.eachFlat = function (array, predicate, map) {
 
             if (result.length === 0) return item
 
-            return result.map(entry => ({...entry, ...item}))
+            return result.map(entry => ({ ...entry, ...item }))
 
         }).flat()
     }
@@ -82,8 +82,8 @@ Array.prototype.filterFlat = function (array, predicate, map) {
     } else {
 
         return this.map(item => array
-            .filter(entry => predicate({...entry, ...item}, entry))
-            .map(entry => ({...entry, ...item}))
+            .filter(entry => predicate({ ...entry, ...item }, entry))
+            .map(entry => ({ ...entry, ...item }))
         ).flat()
     }
 }
@@ -223,42 +223,43 @@ export class Entity {
         return this.#position
     }
 
-    get(name) {
+    async get(name) {
 
-        return this.#storage.getValue(this.#position + this.#positionSet[name], this.#lengthSet[name])
+        return await this.#storage.getValue(this.#position + this.#positionSet[name], this.#lengthSet[name])
     }
 
-    set(name, buffer) {
+    async set(name, buffer) {
 
-        this.#storage.setValue(this.#position + this.#positionSet[name], this.#lengthSet[name], buffer)
+        await this.#storage.setValue(this.#position + this.#positionSet[name], this.#lengthSet[name], buffer)
     }
 
-    #indexPosition(index, buffer, length, s, e) {
+    async #indexPosition(index, buffer, length, s, e) {
 
         if (s + 1 === e) return e
 
         const m = Math.round((s + e) / 2)
 
-        const result = buffer.compare(this.#storage.getValue(index[m], length))
+        const val = await this.#storage.getValue(index[m], length)
+        const result = buffer.compare(val)
 
-        if (result < 0) return this.#indexPosition(index, buffer, length, s, m)
-        if (result > 0) return this.#indexPosition(index, buffer, length, m, e)
+        if (result < 0) return await this.#indexPosition(index, buffer, length, s, m)
+        if (result > 0) return await this.#indexPosition(index, buffer, length, m, e)
 
         return m
     }
 
-    set2(name, buffer) {
+    async set2(name, buffer) {
 
         // 维护索引列：写入值并按二分/边界插入保持 index[name] 有序
         const position = this.#position + this.#positionSet[name]
         const index = this.#indexSet[name]
         const length = this.#lengthSet[name]
-        const buf = this.#storage.getValue(position, length)
+        const buf = await this.#storage.getValue(position, length)
         const changed = !buf.equals(buffer)
 
         if (changed) {
 
-            this.#storage.setValue(position, length, buffer)
+            await this.#storage.setValue(position, length, buffer)
         }
 
         let i = index.indexOf(position)
@@ -272,7 +273,8 @@ export class Entity {
                 index.splice(i, 1)
             }
 
-            let resutl = buffer.compare(this.#storage.getValue(index[0], length))
+            const firstVal = await this.#storage.getValue(index[0], length)
+            let resutl = buffer.compare(firstVal)
 
             if (index.length === 0) {
 
@@ -288,7 +290,8 @@ export class Entity {
 
             } else {
 
-                resutl = buffer.compare(this.#storage.getValue(index[e], length))
+                const lastVal = await this.#storage.getValue(index[e], length)
+                resutl = buffer.compare(lastVal)
 
                 if (resutl >= 0) {
 
@@ -296,7 +299,7 @@ export class Entity {
 
                 } else {
 
-                    i = this.#indexPosition(index, buffer, length, s, e)
+                    i = await this.#indexPosition(index, buffer, length, s, e)
                 }
             }
 
@@ -304,22 +307,22 @@ export class Entity {
         }
     }
 
-    readFileSync(name) {
+    async read(name) {
 
-        // 读取外置 buffer/text 文件内容（字段本体只存标志位与位置）
-        return readFileSync(this.#storage.bufferDir + (this.#position + this.#positionSet[name]))
+        // 读取外置 buffer/text 文件内容
+        return await fs.readFile(this.#storage.bufferDir + (this.#position + this.#positionSet[name]))
     }
 
-    buffer(value, name) {
+    async buffer(value, name) {
 
         const buffer = Buffer.alloc(TypeLen.buffer)
 
         if (value instanceof Buffer) {
 
             if (!existsSync(this.#storage.bufferDir)) {
-                mkdirSync(this.#storage.bufferDir)
+                await fs.mkdir(this.#storage.bufferDir, { recursive: true })
             }
-            writeFileSync(this.#storage.bufferDir + (this.#position + this.#positionSet[name]), value)
+            await fs.writeFile(this.#storage.bufferDir + (this.#position + this.#positionSet[name]), value)
 
             buffer[0] = 1
         }
@@ -377,16 +380,16 @@ export class Entity {
         return buffer
     }
 
-    textToBuffer(value, name) {
+    async textToBuffer(value, name) {
 
         const buffer = Buffer.alloc(TypeLen.text)
 
         if (value) {
 
             if (!existsSync(this.#storage.bufferDir)) {
-                mkdirSync(this.#storage.bufferDir)
+                await fs.mkdir(this.#storage.bufferDir, { recursive: true })
             }
-            writeFileSync(this.#storage.bufferDir + (this.#position + this.#positionSet[name]),
+            await fs.writeFile(this.#storage.bufferDir + (this.#position + this.#positionSet[name]),
                 typeof value === "string" ? value : String(value))
 
             buffer[0] = 1
@@ -874,7 +877,7 @@ export class Entities extends Array {
         return result
     }
 
-    findByTime(name, {after = 0, before = MaxTime}) {
+    findByTime(name, { after = 0, before = MaxTime }) {
 
         const index = this.#index[name]
         const position = this.#positionSet[name]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k3000/store",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "storage",
   "main": "generator.mjs",
   "scripts": {