vvvfs 0.1.7 → 0.1.8

package/README.md

@@ -27,6 +27,7 @@ const VVVFS = require("vvvfs"); // CommonJS
 <script src="https://cdn.jsdelivr.net/npm/vvvfs@latest/dist/vvvfs.min.js"></script>
 <script src="https://unpkg.com/vvvfs@latest/dist/vvvfs.min.js"></script>
 <!-- 浏览器 -->
+<!-- GitHub Release: https://github.com/IFTC-XLKJ/vvvfs/releases -->
 ```
 
 3. 初始化
@@ -95,6 +96,10 @@ const vvvfs = new VVVFS("vvvfs", {
 
 ## 更新日志
 
+### 0.1.8
+
+- 新增 `writeJsonValue` 和 `readJsonValue` 方法，用于读取和写入JSON值（键支持字符串、数字数组下标以及嵌套路径，如 `["a", "b"]`）
+
 ### 0.1.7
 
 - 新增 `init` 选项，用于是否自动初始化，传入字符串时，则为初始化的用户名，传入true时，则为默认用户名。
@@ -268,6 +273,10 @@ Using the `VVVFS.File` class:
 
 ## Changelog
 
+### 0.1.8
+
+- Added the `writeJsonValue` and `readJsonValue` methods for reading and writing JSON values (keys support strings, numeric array indexes, and nested paths such as `["a", "b"]`)
+
 ### 0.1.7
 
 - Added the `init` option to control automatic initialization: when passed a string, it is used as the username for initialization; when passed `true`, the default username is used.

package/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 虚拟文件系统
+ * @author IFTC
+ * @description 虚拟文件系统
+ */
+export * from "./types/index";

package/index.ts

@@ -170,6 +170,21 @@ class VVVFSFile {
     async writeJSON(json: Record<string, unknown>, format: boolean = true) {
         return await this._vvvfs.writeJson(this._path, json, format);
     }
+    /**
+     * 写入文件JSON值
+     * @param key 键名
+     * @param value 键值
+     */
+    async writeJsonValue(key: string | number | Array<string | number>, value: any) {
+        return await this._vvvfs.writeJsonValue(this._path, key, value);
+    }
+    /**
+     * 读取文件JSON值
+     * @param key 键名
+     */
+    async readJsonValue(key: string | number | Array<string | number>): Promise<any> {
+        return await this._vvvfs.readJsonValue(this._path, key);
+    }
     /**
      * 追加文件内容
      * @param file 文件对象
@@ -828,6 +843,61 @@ class VVVFS {
             return await this.append(path, blob);
         }, false);
     }
+    /**
+     * 写入 JSON 值
+     * @param path 文件路径
+     * @param key 键名
+     * @param value 键值
+     * @example await vvvfs.writeJsonValue("/example.json", "a", { b: "example"});
+     * @example await vvvfs.writeJsonValue("/example.json", ["a", "b"], "example2");
+     * @example await vvvfs.writeJsonValue("/example.json", 0, "example");
+     */
+    async writeJsonValue(path: string, key: string | number | Array<string | number>, value: any) {
+        return this.#withErrorHandling("writeJsonValue", async () => {
+            let root: any = (await this.readJson(path)) ?? {};
+            const keys = Array.isArray(key) ? key : [key];
+            if (keys.length > 0) {
+                let json: any = root;
+                for (let i = 0; i < keys.length - 1; i++) {
+                    const currentKey = keys[i];
+                    const nextKey = keys[i + 1];
+                    if (
+                        json[currentKey] === undefined ||
+                        json[currentKey] === null ||
+                        typeof json[currentKey] !== "object"
+                    ) {
+                        json[currentKey] = typeof nextKey === "number" ? [] : {};
+                    }
+                    json = json[currentKey];
+                }
+                json[keys[keys.length - 1]] = value;
+            } else {
+                root = value;
+            }
+            return await this.writeJson(path, root);
+        }, false);
+    }
+    /**
+     * 读取 JSON 值
+     * @param path 文件路径
+     * @param key 键名
+     * @example await vvvfs.readJsonValue("/example.json", "a");
+     * @example await vvvfs.readJsonValue("/example.json", ["a", "b"]);
+     * @example await vvvfs.readJsonValue("/example.json", 0);
+     */
+    async readJsonValue(path: string, key: string | number | Array<string | number>): Promise<any> {
+        return this.#withErrorHandling("readJsonValue", async () => {
+            const json = await this.readJson(path);
+            if (json === null || json === undefined) return null;
+            const keys = Array.isArray(key) ? key : [key];
+            let current: any = json;
+            for (const keyPart of keys) {
+                if (current === null || current === undefined) return null;
+                current = current[keyPart];
+            }
+            return current === undefined ? null : current;
+        }, null as any);
+    }
     /**
      * 内部读取（跳过访问检查，供内部方法调用）
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vvvfs",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "一个使用IndexDB实现的虚拟文件系统",
   "keywords": [
     "Virtual",
@@ -17,6 +17,7 @@
   "author": "IFTC",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "build": "node esbuild.config.js"

package/types/index.d.ts

@@ -1,17 +1,28 @@
 import { Dexie, Table } from "dexie";
 
+/**
+ * VVVFS 类构造签名（避免在内 declare global 中自引用）
+ */
+type VVVFSConstructor = typeof VVVFS;
+
+/**
+ * VVVFS 类实例类型
+ */
+type VVVFSInstance = VVVFS;
+
 /**
  * 虚拟文件系统
  */
 declare global {
     // 扩展 Window 接口
-    interface window {
-        VVVFS: typeof VVVFS; // 如果 VVFS 是个类，这里可能需要调整，或者直接定义 vvfs 实例
+    interface Window {
+        VVVFS: VVVFSConstructor;
+        vvvfs: VVVFSInstance;
     }
 
     // 扩展 GlobalThis (针对你在 index.js 里的 globalThis.vvfs 写法)
-    // 注意：GlobalThis 和 Window 往往指向同一个对象，但在 TS 类型中有时需要分别处理
-    // var VVVFS: typeof VVVFS; 
+    var VVVFS: VVVFSConstructor;
+    var vvvfs: VVVFSInstance;
 }
 
 
@@ -24,7 +35,7 @@ declare global {
  * @param file 文件对象
  * @param locked 是否锁定
  */
-declare interface FileRecord {
+export interface FileRecord {
     id?: number;
     name: string;
     path: string;
@@ -37,7 +48,7 @@ declare interface FileRecord {
  * 虚拟文件系统数据库
  * @param files 文件存储数据表
  */
-declare interface VVVFSDatabase extends Dexie {
+export interface VVVFSDatabase extends Dexie {
     files: Table<FileRecord, number>;
 }
 
@@ -54,7 +65,7 @@ export interface VVVFSOptions {
 /**
  * 虚拟文件系统错误类
  */
-declare class VVVFSError extends Error {
+export class VVVFSError extends Error {
     /**
      * @param type 错误类型
      * @param message 错误信息
@@ -66,7 +77,7 @@ declare class VVVFSError extends Error {
  * 虚拟文件系统文件类
  * @param path 文件路径
  */
-declare class VVVFSFile {
+export class VVVFSFile {
     /**
      * 获取文件路径
      */
@@ -133,6 +144,17 @@ declare class VVVFSFile {
      * @param json 文件JSON内容
      */
     writeJSON(json: Record<string, unknown>, format?: boolean): Promise<boolean>;
+    /**
+     * 写入文件JSON值
+     * @param key 键名
+     * @param value 键值
+     */
+    writeJsonValue(key: string | number | Array<string | number>, value: any): Promise<boolean>;
+    /**
+     * 读取文件JSON值
+     * @param key 键名
+     */
+    readJsonValue(key: string | number | Array<string | number>): Promise<any>;
     /**
      * 追加文件内容
      * @param file 文件对象
@@ -208,7 +230,7 @@ declare class VVVFSFile {
 /**
  * path类（类似于NodeJS中的path模块）
  */
-declare class Path {
+export class Path {
     /**
      * 路径分隔符
      */
@@ -314,7 +336,7 @@ declare class Path {
  * @author IFTC
  * @description 虚拟文件系统
  */
-declare class VVVFS {
+export class VVVFS {
     static defaultDBName: string;
     /**
      * 虚拟文件系统版本
@@ -400,6 +422,25 @@ declare class VVVFS {
      * @param format 是否格式化
      */
     writeJson(path: string, content: Record<string, unknown>, format?: boolean): Promise<boolean>;
+    /**
+     * 写入 JSON 值
+     * @param path 文件路径
+     * @param key 键名
+     * @param value 键值
+     * @example await vvvfs.writeJsonValue("/example.json", "a", { b: "example"});
+     * @example await vvvfs.writeJsonValue("/example.json", ["a", "b"], "example2");
+     * @example await vvvfs.writeJsonValue("/example.json", 0, "example");
+     */
+    writeJsonValue(path: string, key: string | number | Array<string | number>, value: any): Promise<boolean>;
+    /**
+     * 读取 JSON 值
+     * @param path 文件路径
+     * @param key 键名
+     * @example await vvvfs.readJsonValue("/example.json", "a");
+     * @example await vvvfs.readJsonValue("/example.json", ["a", "b"]);
+     * @example await vvvfs.readJsonValue("/example.json", 0);
+     */
+    readJsonValue(path: string, key: string | number | Array<string | number>): Promise<any>;
     /**
      * 追加内容
      * @param path 文件路径
@@ -497,10 +538,10 @@ declare class VVVFS {
  * 解析路径
  * @param path 路径
  */
-declare function parsePath(path: string): { name: string; parent: string };
+export function parsePath(path: string): { name: string; parent: string };
 
 /**
  * 合并路径
  * @param paths 路径
  */
-declare function joinPath(...paths: string[]): string;
+export function joinPath(...paths: string[]): string;