@k3000/store 1.7.0 → 1.9.0

package/README.md

@@ -5,6 +5,10 @@
 *2、1.5.0版本请注意page的用法。
 *3、1.6.1修改String中文存储的BUG建议更新，更新请注意第1、2条和page的用法。
 *4、1.7.0修复中文路径问题。
+*5、1.8.0添加存储目录的备份与迁移的描述（无功能调整）。
+*6、1.9.0让Trae builder优化代码添加了注释。
+*7、反馈与讨论：19815488@qq.com
+
 ```
 
 **初始化和更新升级**
@@ -227,9 +231,127 @@ storage.admin.remove(...storage.admin.filter(admin => admin.usn.startsWith('test
 ```
 更多使用方法参考 `test.mjs`
 
-**保存：**
+**保存**
 
+没3秒会自动保存，也可以手工操作
 ```
 import {close} from './test/index.mjs'
 close() // 关闭并保存
 ```
+**备份与迁移**
+
+当使用`upgrade`升级的时候会按照版本号备份历史版本。
+
+也能直接将整个存储目录保存，复制妥存。
+
+同样道理，迁移就是将存储目录拷贝到相应项目目录，使用相应版本的库运行即可。
+
+---
+
+**概述**
+
+- 本工具提供一种轻量的、可版本化的本地结构化存储方案，面向 Node.js 项目；以“集合/列”定义模式，生成访问层代码，数据落盘到二进制文件并配合加密索引文件。
+- 适合嵌入式、桌面端或需要无需外部数据库的应用，支持索引查询、范围查询、分页与联合查询，且提供平滑的结构升级与密码迁移能力。
+
+**核心概念**
+
+- `Storage`：底层存储运行时，负责数据读写、缓存、加解密、结构与记录的持久化以及并发打开检查。
+- `Entity`：单条记录对象，字段访问器封装了二进制读写与索引维护；支持 Buffer/Text 外置文件字段。
+- `Entities`：集合的代理，提供 `push/pop/unshift/splice/remove/page` 等数组语义与 `indexBy<Field>` 查询。
+- 集合/列定义：通过类型 DSL（`Id/Uint/Int/BigUint/Bigint/Time/Float/String/Buffer/Text`）声明列类型、索引、默认值、长度、步进。
+
+**目录结构详解**
+
+- `index`：二进制索引文件，包含两段加密 JSON：结构（struct）与记录（record）。头部额外包含一个 4 字节整数作为“打开计数”，用于并发打开检测。
+- `data`：二进制数据文件，按集合总长度定长布局存储；每条记录按列 `position/length` 定位读取。
+- `buffer/`：外置文件目录，存放 `Buffer/Text` 字段实际内容；字段本体存储一个字节作为标志位，值为 1 表示存在外置内容。
+- `<version>/index.mjs`：访问层代码，按结构自动生成集合实体类与集合代理；顶层 `index.mjs` 始终重导出最新版本。
+
+**加密与密码**
+
+- 结构与记录的加解密使用 `AES-192-CBC`，密钥由 `md5(password)+salt` 派生，IV 来自 MD5 的中间字节；密码来源于 `Storage(import.meta.url)` 的查询参数或 `upgrade` 传参。
+- 密码迁移：通过 `upgrade('name', { newPwd, password })` 在提交时重新加密结构与记录；若密码不匹配或存储文件损坏会抛出错误。
+
+**版本与升级流程**
+
+- `upgrade(name, options)` 会：
+  - 计算最新版本 `v` 并将其目录完整复制到新版本目录 `version`；
+  - 打开旧/新 `Storage`（支持密码切换），准备生成路径（`index.mjs/type.ts`）；
+  - 返回结构变更 API；`submit()` 会写入加密结构与记录、关闭句柄、生成访问代码，并在集合结构有更新时把旧版数据迁移到新版集合。
+
+**索引与查询**
+
+- 为列开启索引可使用 `updateIndex('set', { col: true })` 或在 DSL 中 `String().index(true)` 等；索引是按字段二进制值排序的记录位置列表。
+- 字段写入使用两种模式：索引列通过 `set2` 维护有序索引（二分定位插入），普通列使用 `set` 直接写入。
+- 查询方法：
+  - 值查询：`indexBy<Field>(value)` 返回与二进制值相等的所有记录；
+  - 范围查询：`indexBy<Field>(value1, value2)` 或针对 `Time` 用 `indexByTime({ after, before })`；
+  - 普通数组查询：`filter/find/some/findIndex` 等对集合进行内存遍历。
+
+**分页与缓存**
+
+- `page(predicate, index, size, params)` 支持两种模式：
+  - 简单分页：`page(fn, 1, 10)` 返回第 1 页、大小 10 的结果（按记录顺序）；
+  - 缓存分页：`page(fn, 'index', 'size', params)` 将 `params` 作为缓存键，命中时不重复计算；内部每轮（3 秒）标记过期，下一轮未访问的缓存将被移除。
+
+**大字段（Buffer/Text）**
+
+- `Buffer`/`Text` 字段内容存储在 `buffer/` 目录，以记录起始位置+列偏移作为文件名；字段本体只存放 1 字节标记位。
+- 删除或替换记录时，会自动清理关联的外置文件；读取时通过 `readFileSync` 返回二进制或文本内容。
+
+**性能与注意事项**
+
+- 自动保存与清理：每 3 秒写回需要保存的值、刷新记录并清理过期缓存；
+- 缓存上限：Value/Entity/Cache 的 Map 最多各 99999 条；超过上限的写入会直接落盘而不进入缓存；
+- 并发打开：打开计数变化会抛错提示“已在其他地方打开”，防止同目录并发写入；
+- 路径解析：`Storage(import.meta.url)` 在 file URL 情况下使用 `process.cwd()` 作为目录基础，请在正确工作目录下运行或传显式路径；
+- 时间编码：`Time` 字段以定长十六进制 Buffer 表示，使用 `d2b/b2d` 辅助范围比较；最大时间常量为 `MaxTime`。
+
+**API 参考（结构变更）**
+
+```
+const gen = upgrade(name, { version, password, newPwd, store })
+gen.appendSet(name, set, remark)       // 新增集合
+gen.updateCol(name, set)               // 更新集合列
+gen.renameSet(name, newName)           // 集合更名
+gen.renameCol(name, { old: new })      // 列更名
+gen.deleteSet(name)                    // 删除集合
+gen.deleteCol(name, colName)           // 删除列
+gen.updateSetRemark(name, remark)      // 更新集合备注
+gen.updateIndex(name, { col: true })   // 索引开关
+gen.submit()                           // 提交生成与数据迁移
+```
+
+**最小示例**
+
+```
+import upgrade, { Id, String, Time, Uint } from '@k3000/store/generator.mjs'
+
+const { appendSet, submit } = upgrade('myStore')
+
+appendSet('user', {
+  id: Id,
+  uid: String('账号').index(true),
+  pwd: String('密码').length(64),
+  createdAt: Time('创建时间').index(true).value(Time.now),
+  status: Uint(1).remark('状态位')
+}, '用户表')
+
+await submit()
+
+// 使用
+import storage from './myStore/index.mjs'
+storage.user.push({ uid: 'alice', pwd: '***', status: 1 })
+const recent = storage.user.indexByCreatedAt({ after: new Date('2024-01-01') })
+```
+
+**常见问题（FAQ）**
+
+- `Error: ENOENT: no such file or directory, open '.../data'`：当前工作目录与版本目录不匹配或目录未初始化。请先执行 `upgrade` 生成版本，并在该目录下运行。
+- `密码不匹配或者存储文件不正确`：传入密码与存储目录加密信息不一致，或索引文件损坏。请确认密码或重新初始化。
+- `索引查询无结果`：检查是否为该列开启索引（定义或 `updateIndex`），以及值/范围是否与列类型与长度匹配。
+- `page 返回空`：检查 `size` 是否为正数，`predicate` 是否正确，或缓存参数键名是否与 `'index'/'size'` 一致。
+
+**备份与迁移补充**
+
+- 每次 `upgrade` 会将旧版本目录完整复制为备份；迁移仅需复制整个存储目录到目标项目，并确保使用兼容版本的库与正确密码即可。

package/architect.mjs

@@ -1,5 +1,14 @@
-import {openSync, closeSync, readFileSync, writeFileSync, readSync, writeSync, unlinkSync} from "node:fs"
+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'
+/**
+ * 结构化存储运行时核心模块
+ * - 定义数据读写协议（定长 Buffer 字段、外置文件字段）
+ * - 提供实体（Entity）与集合（Entities）抽象，支持索引查询、范围查询与分页
+ * - 管理结构/记录的持久化与加解密、变更缓存与周期性保存
+ * - 为生成器输出的访问层（index.mjs）提供底层能力
+ */
 
 /**
  *
@@ -10,6 +19,8 @@ import {createCipheriv, createDecipheriv, createHash, scryptSync} from "node:cry
  */
 Array.prototype.eachFlat = function (array, predicate, map) {
 
+    // eachFlat：类似 LEFT JOIN，将本数组与目标数组按谓词进行展开合并
+
     if (typeof predicate === "string") {
 
         const key = predicate
@@ -52,6 +63,8 @@ Array.prototype.eachFlat = function (array, predicate, map) {
  */
 Array.prototype.filterFlat = function (array, predicate, map) {
 
+    // filterFlat：类似 INNER JOIN，仅保留满足谓词的组合项
+
     if (typeof predicate === "string") {
 
         const key = predicate
@@ -75,16 +88,19 @@ Array.prototype.filterFlat = function (array, predicate, map) {
     }
 }
 
+// 缓存容量上限（value/entity/cache 三类 Map 的最大条目数）
 const MaxSize = 99999
 /**
  * 时间筛选的最大值
  * @type {number}
  */
+// 时间筛选允许的最大毫秒值（用于范围查询边界）
 export const MaxTime = 99999999999999
 /**
  * 用于获取存储的位置
  * @type {symbol}
  */
+// 实体在数据文件中的起始位置标识，用于删除/回收与定位
 export const position = Symbol('position')
 
 export const TypeLen = {
@@ -233,6 +249,7 @@ export class Entity {
 
     set2(name, buffer) {
 
+        // 维护索引列：写入值并按二分/边界插入保持 index[name] 有序
         const position = this.#position + this.#positionSet[name]
         const index = this.#indexSet[name]
         const length = this.#lengthSet[name]
@@ -289,6 +306,7 @@ export class Entity {
 
     readFileSync(name) {
 
+        // 读取外置 buffer/text 文件内容（字段本体只存标志位与位置）
         return readFileSync(this.#storage.bufferDir + (this.#position + this.#positionSet[name]))
     }
 
@@ -298,6 +316,9 @@ export class Entity {
 
         if (value instanceof Buffer) {
 
+            if (!existsSync(this.#storage.bufferDir)) {
+                mkdirSync(this.#storage.bufferDir)
+            }
             writeFileSync(this.#storage.bufferDir + (this.#position + this.#positionSet[name]), value)
 
             buffer[0] = 1
@@ -362,6 +383,9 @@ export class Entity {
 
         if (value) {
 
+            if (!existsSync(this.#storage.bufferDir)) {
+                mkdirSync(this.#storage.bufferDir)
+            }
             writeFileSync(this.#storage.bufferDir + (this.#position + this.#positionSet[name]),
                 typeof value === "string" ? value : String(value))
 
@@ -444,6 +468,7 @@ export class Entities extends Array {
 
                 if (index >= record.length || index < 0) return null
 
+                // 索引访问返回实体代理（含字段 getter/setter）
                 return storage.getEntity(record[p], classify, this.#index, this.#lengthSet, this.#positionSet)
             }
 
@@ -453,6 +478,7 @@ export class Entities extends Array {
 
             if (typeof result !== "function") return result
 
+            // 将原生数组方法委托到实体对象数组
             return (...arg) => result.call(record.map(position => storage.getEntity(position, classify,
                 this.#index, this.#lengthSet, this.#positionSet)), ...arg)
         }
@@ -496,6 +522,7 @@ export class Entities extends Array {
 
     push(...items) {
 
+        // 追加：复用空闲位或推进指针，返回实体对象（已应用默认值创建）
         if (this.#storage.needSave === false) {
 
             this.#storage.needSave = true
@@ -524,6 +551,7 @@ export class Entities extends Array {
 
     pop() {
 
+        // 弹出最后一条：回收索引与外置文件，位置进入空闲池
         if (this.#storage.needSave === false) {
 
             this.#storage.needSave = true
@@ -540,6 +568,7 @@ export class Entities extends Array {
 
     unshift(...items) {
 
+        // 头部插入：同 push 但写入到记录头部
         if (this.#storage.needSave === false) {
 
             this.#storage.needSave = true
@@ -568,6 +597,7 @@ export class Entities extends Array {
 
     shift() {
 
+        // 移除首条：与 pop 相似
         if (this.#storage.needSave === false) {
 
             this.#storage.needSave = true
@@ -583,6 +613,7 @@ export class Entities extends Array {
 
     splice(start, deleteCount, ...items) {
 
+        // 区间替换：批量分配位置并回收被删除位置
         if (this.#storage.needSave === false) {
 
             this.#storage.needSave = true
@@ -642,6 +673,7 @@ export class Entities extends Array {
      */
     page(predicate, page, size, params) {
 
+        // 分页：支持带缓存键的分页与简单分页两种模式
         if (typeof page === "string" && typeof size === "string" && typeof params === "object") {
 
             return this.#page(predicate, params[page], params[size], this.#name + ' ' +
@@ -681,6 +713,7 @@ export class Entities extends Array {
 
     remove(...items) {
 
+        // 从集合中移除实体（按位置比对），触发回收与空闲入池
         let index
 
         if (Array.isArray(items[0])) {
@@ -964,7 +997,17 @@ export class Storage {
 
     constructor(url, password, newPwd) {
 
-        let dir = url.startsWith('file:///') ? process.cwd() : url
+        let dir
+
+        if (url.startsWith('file:///')) {
+
+            const filePath = fileURLToPath(url)
+            dir = dirname(filePath)
+
+        } else {
+
+            dir = url
+        }
 
         dir = dir.replace(/\\/g, '/')
 
@@ -1022,6 +1065,7 @@ export class Storage {
 
     #save() {
 
+        // 将需要保存的缓存值写回数据文件；如记录有结构改动，刷新记录块
         for (const [position, item] of this.#values.entries()) {
 
             if (item.needsSave) {
@@ -1047,6 +1091,7 @@ export class Storage {
 
     #check(...arg) {
 
+        // 简单的每轮过期机制：第二次巡检仍为 expired=true 的条目会被移除
         for (const map of arg) {
 
             for (const [key, value] of map) {
@@ -1065,6 +1110,7 @@ export class Storage {
 
     #writeNumber(number, position) {
 
+        // 向索引文件写入 4 字节无符号整数（版本/长度/指针等）
         const buffer = Buffer.alloc(4)
 
         buffer.writeUint32BE(number, 0)
@@ -1089,6 +1135,7 @@ export class Storage {
         extra: {},
     }) {
 
+        // 更新结构并写入索引文件（加密 JSON）
         this.#struct = struct
 
         this.#update(struct)
@@ -1102,6 +1149,7 @@ export class Storage {
         pointer: 0,
     }, length = 4 + this.#getLength()) {
 
+        // 更新记录并写入索引文件（结构长度之后的区域）
         this.#record = record
 
         this.#update(record, length)
@@ -1228,6 +1276,7 @@ export class Storage {
      */
     getValue(position, length) {
 
+        // 读取数据文件指定位置的定长 Buffer，配合 LRU 式过期标记缓存
         if (this.#values.has(position)) {
 
             const item = this.#values.get(position)
@@ -1267,6 +1316,7 @@ export class Storage {
 
     setValue(position, length, value) {
 
+        // 设置缓存并标记是否需要保存（或直接写盘，当缓存已满）
         if (this.#values.has(position)) {
 
             const item = this.#values.get(position)
@@ -1326,6 +1376,7 @@ export class Storage {
 
     getEntity(position, classify, ...arg) {
 
+        // 获取实体代理对象，带过期标记以配合周期性清理
         if (this.#entities.has(position)) {
 
             const item = this.#entities.get(position)
@@ -1387,6 +1438,7 @@ export class Storage {
 
     updateValue(value, name, key) {
 
+        // 维护有步进的列（如自增 Id）：当未提供值时按步进递增并返回
         if (value === undefined) return this.#record.value[name][key] += this.#struct.base[name][key].step
 
         if (Number.isNaN(Number.parseFloat(value))) {

package/generator.mjs

@@ -1,6 +1,12 @@
 import {copyFileSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync} from "node:fs";
-import {buffer, string, Storage, TypeLen, readInt24BE, readUint24BE} from './architect.mjs'
+import {buffer, string, Storage, TypeLen, readInt24BE, readUint24BE, b2d} from './architect.mjs'
 import {resolve} from 'node:path'
+/**
+ * 代码生成与结构升级模块
+ * - 提供类型 DSL（Id/Uint/Int/...）定义集合结构、索引、默认值、长度与步进
+ * - 生成运行时访问代码（index.mjs）与类型声明（type.ts）
+ * - 管理版本目录复制、密码迁移与数据迁移
+ */
 
 const modulePath = import.meta.url.endsWith('?test=true') ? '../../architect.mjs' : '@k3000/store/architect.mjs'
 const modulePath2 = import.meta.url.endsWith('?test=true') ? '../../generator.mjs' : '@k3000/store'
@@ -49,6 +55,7 @@ const TimeAttr = {
 }
 
 const SCOPE = {}
+// SCOPE：内部哨兵对象，限制链式配置仅由类型构造器内部调用生效
 
 export const bigintSerialize = (_, value) => typeof value === "bigint" ? value.toString() : value
 
@@ -495,6 +502,7 @@ export const Text = remark => new class Text extends Type {
 
 export const struct = (storage, remark, name) => {
 
+    // 将底层结构反射为可读的元信息（类型、备注、索引、默认值、长度等）
     const struct = {}, base = storage.struct.base
 
     for (const [key, value] of Object.entries(storage.struct.extra)) {
@@ -545,6 +553,7 @@ export const struct = (storage, remark, name) => {
 
 const updateColPos = (base, extra) => {
 
+    // 重新计算列起始位置与集合总长度（按顺序累加定长字段）
     let position = 0
 
     for (const value of Object.values(base)) {
@@ -559,6 +568,7 @@ const updateColPos = (base, extra) => {
 
 function appendSet(name, set, remark = '') {
 
+    // 新增集合：初始化结构/记录占位，并根据列定义填充索引/步进默认值
     if (!Reflect.has(this.curr.struct.base, name)) {
 
         console.log('append set:', name)
@@ -619,6 +629,7 @@ function appendSet(name, set, remark = '') {
 
 function updateCol(name, set) {
 
+    // 更新集合列：覆盖或新增列定义，维护索引与步进默认值
     if (Reflect.has(this.curr.struct.base, name)) {
 
         console.log('current set:', name)
@@ -674,6 +685,7 @@ function updateCol(name, set) {
 
 function renameSet(name, newName) {
 
+    // 集合更名：同步结构/备注/记录各处键名
     if (typeof newName === "string"
         && Reflect.has(this.curr.struct.base, name)
         && !Reflect.has(this.curr.struct.base, newName)) {
@@ -708,6 +720,7 @@ function renameSet(name, newName) {
 
 function renameCol(name, set) {
 
+    // 列更名：同步结构/备注/记录各处键名与对应索引容器
     if (Reflect.has(this.curr.struct.base, name)) {
 
         for (let [key, newKey] of Object.entries(set)) {
@@ -748,6 +761,7 @@ function renameCol(name, set) {
 
 function deleteSet(name) {
 
+    // 删除集合：移除结构与记录的全部条目
     if (Reflect.has(this.curr.struct.base, name)) {
 
         console.log(`delete set: ${name}`)
@@ -763,6 +777,7 @@ function deleteSet(name) {
 
 function deleteCol(name, col) {
 
+    // 删除列：移除结构与记录条目并重算位置
     if (Reflect.has(this.curr.struct.base, name)
         && Reflect.has(this.curr.struct.base[name], col)) {
 
@@ -783,6 +798,7 @@ function deleteCol(name, col) {
 
 function updateSetRemark(name, remark) {
 
+    // 更新集合备注
     if (Reflect.has(this.curr.struct.base, name)) {
 
         console.log(`update ${name} remark:`, remark)
@@ -793,93 +809,74 @@ function updateSetRemark(name, remark) {
 
 const updateIndex2 = function (store, record, struct) {
 
-    record = record.map(position => position + struct.position)
+    const positions = record.map(position => position + struct.position)
+    const length = struct.length
 
     switch (struct.type) {
 
         case typeMap.id:
-
-            return record.sort((a, b) => store.getValue(a, struct.length).readUInt32BE()
-                - store.getValue(b, struct.length).readUInt32BE())
+            return positions.map(p => [p, store.getValue(p, length).readUInt32BE(0)])
+                .sort((a, b) => a[1] - b[1]).map(([p]) => p)
 
         case typeMap.uint:
-
-            switch (struct.length) {
-
+            switch (length) {
                 case 1:
-
-                    return record.sort((a, b) => store.getValue(a, struct.length).readUInt8()
-                        - store.getValue(b, struct.length).readUInt8())
-
+                    return positions.map(p => [p, store.getValue(p, length).readUInt8(0)])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
                 case 2:
-
-                    return record.sort((a, b) => store.getValue(a, struct.length).readUInt16BE()
-                        - store.getValue(b, struct.length).readUInt16BE())
-
+                    return positions.map(p => [p, store.getValue(p, length).readUInt16BE(0)])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
                 case 3:
-
-                    return record.sort((a, b) => readUint24BE(store.getValue(a, struct.length))
-                        - readUint24BE(store.getValue(b, struct.length)))
-
+                    return positions.map(p => [p, readUint24BE(store.getValue(p, length))])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
                 case 4:
-
-                    return record.sort((a, b) => store.getValue(a, struct.length).readUInt32BE()
-                        - store.getValue(b, struct.length).readUInt32BE())
+                    return positions.map(p => [p, store.getValue(p, length).readUInt32BE(0)])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
             }
+            break
 
         case typeMap.int:
-
-            switch (struct.length) {
-
+            switch (length) {
                 case 1:
-
-                    return record.sort((a, b) => store.getValue(a, struct.length).readInt8()
-                        - store.getValue(b, struct.length).readInt8())
-
+                    return positions.map(p => [p, store.getValue(p, length).readInt8(0)])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
                 case 2:
-
-                    return record.sort((a, b) => store.getValue(a, struct.length).readInt16BE()
-                        - store.getValue(b, struct.length).readInt16BE())
-
+                    return positions.map(p => [p, store.getValue(p, length).readInt16BE(0)])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
                 case 3:
-
-                    return record.sort((a, b) => readInt24BE(store.getValue(a, struct.length))
-                        - readInt24BE(store.getValue(b, struct.length)))
-
+                    return positions.map(p => [p, readInt24BE(store.getValue(p, length))])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
                 case 4:
-
-                    return record.sort((a, b) => store.getValue(a, struct.length).readInt32BE()
-                        - store.getValue(b, struct.length).readInt32BE())
+                    return positions.map(p => [p, store.getValue(p, length).readInt32BE(0)])
+                        .sort((a, b) => a[1] - b[1]).map(([p]) => p)
             }
+            break
 
         case typeMap.bigUint:
-
-            return record.sort((a, b) => store.getValue(a, struct.length).readBigUInt64BE()
-                - store.getValue(b, struct.length).readBigUInt64BE())
+            return positions.map(p => [p, store.getValue(p, length).readBigUInt64BE(0)])
+                .sort((a, b) => (a[1] - b[1])).map(([p]) => p)
 
         case typeMap.bigint:
-
-            return record.sort((a, b) => store.getValue(a, struct.length).readBigInt64BE()
-                - store.getValue(b, struct.length).readBigInt64BE())
+            return positions.map(p => [p, store.getValue(p, length).readBigInt64BE(0)])
+                .sort((a, b) => (a[1] - b[1])).map(([p]) => p)
 
         case typeMap.time:
-
-            return record.sort((a, b) => b2d(store.getValue(a, struct.length))
-                - b2d(store.getValue(b, struct.length)))
+            return positions.map(p => [p, b2d(store.getValue(p, length))])
+                .sort((a, b) => a[1] - b[1]).map(([p]) => p)
 
         case typeMap.float:
-
-            return record.sort((a, b) => store.getValue(a, struct.length).readDoubleBE()
-                - store.getValue(b, struct.length).readDoubleBE())
+            return positions.map(p => [p, store.getValue(p, length).readDoubleBE(0)])
+                .sort((a, b) => a[1] - b[1]).map(([p]) => p)
 
         case typeMap.string:
-
-            return record.sort((a, b) => store.getValue(a, struct.length).compare(store.getValue(b, struct.length)))
+            return positions.map(p => [p, store.getValue(p, length)])
+                .sort((a, b) => a[1].compare(b[1])).map(([p]) => p)
     }
 }
 
 const updateIndex = function (name, set) {
 
+    // 开启/关闭指定列索引：重建或清理索引映射
     const struct = this.curr.struct.base[name]
     const index = this.curr.record.index[name]
 
@@ -918,6 +915,11 @@ const commentRemark = (remark = '') => remark.replace(/\n/g, '\n\t * ')
 
 function submit() {
 
+    // 提交：
+    // 1) 清理更新集合的运行时记录
+    // 2) 写入结构/记录（加密）并关闭旧/新存储句柄
+    // 3) 生成类型声明与访问层代码
+    // 4) 将旧版本数据迁移到新版本（当集合结构有更新）
     for (const name of this.updateSet.values()) {
 
         this.curr.record.idle[name] = []
@@ -986,6 +988,7 @@ export default storage
 
 const initDir = (name, dir) => {
 
+    // 初始化版本目录：创建 index.mjs/index/data/buffer 与 Storage 实例
     const existsDir = existsSync(name) && statSync(name).isDirectory()
 
     if (!existsDir) {
@@ -1042,6 +1045,7 @@ export default new class extends Store {
 
 const copyDir = (src, dest) => {
 
+    // 复制目录（用于版本演进的目录克隆）
     mkdirSync(dest)
 
     for (const name of readdirSync(src)) {
@@ -1125,6 +1129,7 @@ const gen = {
 
 const clipStatic = (name, [key, value]) => {
 
+    // 生成实体创建阶段的默认值赋值代码（含步进值与特殊时间默认）
     if (!Reflect.has(value, 'value')) return ''
 
     let valueStr = ''
@@ -1166,6 +1171,7 @@ const clipStatic = (name, [key, value]) => {
 
 const clipIndex = (name, key, k, v) => {
 
+    // 生成字段 setter 写入语句：区分索引列与普通列的写入方式
     let main = '0'
 
     if (v.type === typeMap.int) {
@@ -1215,6 +1221,7 @@ const sort2 = ([a], [b]) => a.localeCompare(b)
 
 const clipEntity = ([key, value]) => {
 
+    // 生成实体类：包含静态 create 默认值、字段属性访问器与自动更新时间
     const update = Object.entries(value).find(([_, v]) => v.type === typeMap.time && v.value === TimeAttr.update)
 
     const name = key[0].toUpperCase() + key.substring(1)
@@ -1253,6 +1260,7 @@ ${update ? `
 
 const clipEntities = ([key, value]) => {
 
+    // 生成集合代理类：屏蔽内部方法、提供索引查询方法
     const name = key[0].toUpperCase() + key.substring(1)
 
     return `
@@ -1438,6 +1446,10 @@ export default function upgrade(name, {
     store,
 } = {}) {
 
+    // 升级流程：
+    // - 计算最新版本 v，克隆 v 到新版本目录
+    // - 打开旧/新 Storage（支持密码切换），准备代码生成路径
+    // - 返回结构变更操作器，最终由 submit() 完成落盘与代码生成
     const dir = name[name.length - 1] === '/' ? name : name + '/'
 
     if (!existsSync(dir)) {

package/package.json

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

package/test/1/buffer/683

@@ -0,0 +1 @@
+abc