vvvfs 0.1.6 → 0.1.8

package/README.md

@@ -2,6 +2,8 @@
 
 一个使用Dexie.js，基于IndexedDB的轻量、简单的浏览器中的Linux虚拟文件系统
 
+GitHub仓库: https://github.com/IFTC-XLKJ/vvvfs
+
 ## 快速开始
 
 1. 安装依赖
@@ -25,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. 初始化
@@ -32,6 +35,7 @@ const VVVFS = require("vvvfs"); // CommonJS
 ```javascript
 const vvvfs = new VVVFS("vvvfs", {
   throwError: true, // 设置为true后，操作文件失败时，不会返回false，而是会抛出错误
+  init: "IFTC", // 自动初始化，用户名为 IFTC
 }); // 创建一个名为vvvfs的虚拟文件系统
 ```
 
@@ -92,6 +96,14 @@ const vvvfs = new VVVFS("vvvfs", {
 
 ## 更新日志
 
+### 0.1.8
+
+- 新增 `writeJsonValue` 和 `readJsonValue` 方法，用于读取和写入JSON值（键支持字符串、数字数组下标以及嵌套路径，如 `["a", "b"]`）
+
+### 0.1.7
+
+- 新增 `init` 选项，用于是否自动初始化，传入字符串时，则为初始化的用户名，传入true时，则为默认用户名。
+
 ### 0.1.6
 
 - 新增 `VVVFS.path` ，用法与 NodeJS 的 `path` 模块类似。
@@ -168,6 +180,8 @@ const vvvfs = new VVVFS("vvvfs", {
 
 A lightweight and simple Linux virtual file system in the browser, based on IndexedDB, built with Dexie.js
 
+GitHub repository: https://github.com/IFTC-XLKJ/vvvfs
+
 ## Quick Start
 
 1. Install the dependency
@@ -198,6 +212,7 @@ const VVVFS = require("vvvfs"); // CommonJS
 ```javascript
 const vvvfs = new VVVFS("vvvfs", {
   throwError: true, // When set to true, failed file operations throw an error instead of returning false
+  init: "IFTC", // Automatically initialize with the username IFTC
 }); // Create a virtual file system named vvvfs
 ```
 
@@ -258,6 +273,14 @@ 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.
+
 ### 0.1.6
 
 - Added `VVVFS.path`, which works in a similar way to the `path` module in NodeJS.

package/index.d.ts

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

package/index.ts

@@ -37,9 +37,11 @@ export interface VVVFSDatabase extends Dexie {
 /**
  * 虚拟文件系统配置项
  * @param throwError 是否抛出错误
+ * @param init 是否自动初始化，传入字符串时，为用户名，传入true时，使用默认用户名
  */
 export interface VVVFSOptions {
     throwError: boolean;
+    init: boolean | string;
 }
 
 /**
@@ -168,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 文件对象
@@ -582,6 +599,7 @@ class VVVFS {
         name?: string,
         options = {
             throwError: false,
+            init: false,
         },
     ) {
         this.options = options;
@@ -599,6 +617,7 @@ class VVVFS {
                     }
                 });
             });
+            this.options.init ? this.init(this.options.init == true ? "root" : this.options.init) : void 0;
         } catch (error) {
             console.error("创建数据库失败", error);
             throw new VVVFSError("CreateDatabase", "创建数据库失败");
@@ -824,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.6",
+  "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,22 +48,24 @@ declare interface FileRecord {
  * 虚拟文件系统数据库
  * @param files 文件存储数据表
  */
-declare interface VVVFSDatabase extends Dexie {
+export interface VVVFSDatabase extends Dexie {
     files: Table<FileRecord, number>;
 }
 
 /**
  * 虚拟文件系统配置项
  * @param throwError 是否抛出错误
+ * @param init 是否自动初始化，传入字符串时，为用户名，传入true时，使用默认用户名
  */
-declare interface VVVFSOptions {
+export interface VVVFSOptions {
     throwError: boolean;
+    init: boolean | string;
 }
 
 /**
  * 虚拟文件系统错误类
  */
-declare class VVVFSError extends Error {
+export class VVVFSError extends Error {
     /**
      * @param type 错误类型
      * @param message 错误信息
@@ -64,7 +77,7 @@ declare class VVVFSError extends Error {
  * 虚拟文件系统文件类
  * @param path 文件路径
  */
-declare class VVVFSFile {
+export class VVVFSFile {
     /**
      * 获取文件路径
      */
@@ -131,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 文件对象
@@ -206,7 +230,7 @@ declare class VVVFSFile {
 /**
  * path类（类似于NodeJS中的path模块）
  */
-declare class Path {
+export class Path {
     /**
      * 路径分隔符
      */
@@ -312,7 +336,7 @@ declare class Path {
  * @author IFTC
  * @description 虚拟文件系统
  */
-declare class VVVFS {
+export class VVVFS {
     static defaultDBName: string;
     /**
      * 虚拟文件系统版本
@@ -398,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 文件路径
@@ -495,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;