vvvfs 0.1.7 → 0.1.9

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,16 @@ const vvvfs = new VVVFS("vvvfs", {
 
 ## 更新日志
 
+### 0.1.9
+
+- 新增 `saveFile` 方法，用于保存文件
+- 新增 `downloadFile` 方法，用于下载文件并保存到IndexedDB（支持`fetch`和`xhr`两种模式，以及下载进度、错误和成功事件）
+- `VVVFS.File` 类新增 `save` 和 `download` 方法
+
+### 0.1.8
+
+- 新增 `writeJsonValue` 和 `readJsonValue` 方法，用于读取和写入JSON值（键支持字符串、数字数组下标以及嵌套路径，如 `["a", "b"]`）
+
 ### 0.1.7
 
 - 新增 `init` 选项，用于是否自动初始化，传入字符串时，则为初始化的用户名，传入true时，则为默认用户名。
@@ -268,6 +279,16 @@ Using the `VVVFS.File` class:
 
 ## Changelog
 
+### 0.1.9
+
+- Added the `saveFile` method for saving files
+- Added the `downloadFile` method for downloading files to IndexedDB (supports both `fetch` and `xhr` modes, as well as progress, error, and success callbacks)
+- Added the `save` and `download` methods to the `VVVFS.File` class
+
+### 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

@@ -44,6 +44,22 @@ export interface VVVFSOptions {
     init: boolean | string;
 }
 
+/**
+ * 虚拟文件系统下载配置项
+ * @param headers 请求头
+ * @param mode 下载模式（fetch或xhr）
+ * @param onProgress 下载进度事件
+ * @param onError 下载出错事件
+ * @param onSuccess 下载成功事件
+ */
+export interface VVVFSDownloadOptions {
+    headers?: Record<string, string>;
+    mode?: "fetch" | "xhr";
+    onProgress?: (progress: number) => void;
+    onError?: (error: any) => void;
+    onSuccess?: (success: boolean) => void;
+}
+
 /**
  * 虚拟文件系统错误类
  */
@@ -170,6 +186,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 文件对象
@@ -274,6 +305,21 @@ class VVVFSFile {
     async isLocked() {
         return await this._vvvfs.isLocked(this._path);
     }
+    /**
+     * 保存文件
+     * @param name 文件名
+     */
+    async save(name: string) {
+        return await this._vvvfs.saveFile(this._path, name);
+    }
+    /**
+     * 下载文件
+     * @param url 文件链接
+     * @param options 下载配置项
+     */
+    async download(url: string | URL | Request, options: VVVFSDownloadOptions = {}) {
+        return await this._vvvfs.downloadFile(url, this._path, options);
+    }
 }
 
 /**
@@ -828,6 +874,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);
+    }
     /**
      * 内部读取（跳过访问检查，供内部方法调用）
      */
@@ -1227,6 +1328,166 @@ class VVVFS {
             return await this.#isLocked(targetPath);
         }, false);
     }
+    /**
+     * 保存文件
+     * @param path 文件路径
+     * @param name 文件名
+     */
+    async saveFile(path: string, name?: string) {
+        return this.#withErrorHandling("saveFile", async () => {
+            const targetPath = joinPath(path);
+            if (!(await this.#checkAccess(targetPath, "read"))) return false;
+            const file = await this.#internalRead(targetPath);
+            if (!file) {
+                console.warn("文件不存在");
+                return false;
+            }
+            const a = document.createElement("a");
+            a.href = URL.createObjectURL(file);
+            a.download = name || Path.basename(targetPath);
+            a.click();
+            URL.revokeObjectURL(a.href);
+            return true;
+        }, false);
+    }
+    /**
+     * 下载文件
+     * @param url 文件链接
+     * @param path 保存路径
+     * @param options 下载配置项
+     */
+    async downloadFile(
+        url: string | URL | Request,
+        path: string,
+        options: VVVFSDownloadOptions = {},
+    ) {
+        return this.#withErrorHandling("downloadFile", async () => {
+            const targetPath = joinPath(path);
+            if (!(await this.#checkAccess(targetPath, "write"))) return false;
+            const content =
+                (options.mode || "fetch") === "xhr"
+                    ? await this.#downloadWithXHR(url, options)
+                    : await this.#downloadWithFetch(url, options);
+            if (!content) return false;
+            const blob = new Blob([content], {
+                type: mime.getType(targetPath) || "application/octet-stream",
+            });
+            const success = await this.#internalWrite(targetPath, blob);
+            if (success && options.onSuccess) {
+                options.onSuccess(success);
+            }
+            return success;
+        }, false);
+    }
+    /**
+     * 使用fetch下载文件
+     * @param url 文件链接
+     * @param options 下载配置项
+     */
+    async #downloadWithFetch(
+        url: string | URL | Request,
+        options: VVVFSDownloadOptions,
+    ): Promise<Blob | null> {
+        const request =
+            url instanceof Request
+                ? url
+                : new Request(url, { headers: options.headers });
+        const response = await fetch(request);
+        if (!response.ok) {
+            const error = new Error(`下载失败，HTTP ${response.status}`);
+            if (options.onError) {
+                options.onError(error);
+                return null;
+            }
+            throw error;
+        }
+        const total = Number(response.headers.get("Content-Length") || 0);
+        if (options.onProgress && response.body && total > 0) {
+            const reader = response.body.getReader();
+            const chunks: Uint8Array<ArrayBuffer>[] = [];
+            let loaded = 0;
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                const chunk = value as Uint8Array<ArrayBuffer>;
+                chunks.push(chunk);
+                loaded += chunk.length;
+                options.onProgress(Math.round((loaded / total) * 100));
+            }
+            return new Blob(chunks);
+        }
+        return await response.blob();
+    }
+    /**
+     * 使用XHR下载文件
+     * @param url 文件链接
+     * @param options 下载配置项
+     */
+    #downloadWithXHR(
+        url: string | URL | Request,
+        options: VVVFSDownloadOptions,
+    ): Promise<Blob | null> {
+        return new Promise((resolve, reject) => {
+            const requestUrl =
+                url instanceof URL
+                    ? url.href
+                    : url instanceof Request
+                        ? url.url
+                        : url;
+            const headers = url instanceof Request ? url.headers : options.headers;
+            const xhr = new XMLHttpRequest();
+            xhr.open("GET", requestUrl);
+            if (headers instanceof Headers) {
+                headers.forEach((value, key) => {
+                    xhr.setRequestHeader(key, value);
+                });
+            } else if (headers) {
+                for (const [key, value] of Object.entries(headers)) {
+                    xhr.setRequestHeader(key, value);
+                }
+            }
+            xhr.responseType = "blob";
+            xhr.onprogress = (event) => {
+                if (options.onProgress && event.total > 0) {
+                    options.onProgress(
+                        Math.round((event.loaded / event.total) * 100),
+                    );
+                }
+            };
+            xhr.onload = () => {
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    resolve(xhr.response as Blob);
+                } else {
+                    const error = new Error(`下载失败，HTTP ${xhr.status}`);
+                    if (options.onError) {
+                        options.onError(error);
+                        resolve(null);
+                    } else {
+                        reject(error);
+                    }
+                }
+            };
+            xhr.onerror = () => {
+                const error = new Error("下载失败");
+                if (options.onError) {
+                    options.onError(error);
+                    resolve(null);
+                } else {
+                    reject(error);
+                }
+            };
+            try {
+                xhr.send();
+            } catch (error) {
+                if (options.onError) {
+                    options.onError(error);
+                    resolve(null);
+                } else {
+                    reject(error);
+                }
+            }
+        });
+    }
 }
 /**
  * 解析路径

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vvvfs",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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>;
 }
 
@@ -51,10 +62,26 @@ export interface VVVFSOptions {
     init: boolean | string;
 }
 
+/**
+ * 虚拟文件系统下载配置项
+ * @param headers 请求头
+ * @param mode 下载模式（fetch或xhr）
+ * @param onProgress 下载进度事件
+ * @param onError 下载出错事件
+ * @param onSuccess 下载成功事件
+ */
+export interface VVVFSDownloadOptions {
+    headers?: Record<string, string>;
+    mode?: "fetch" | "xhr";
+    onProgress?: (progress: number) => void;
+    onError?: (error: any) => void;
+    onSuccess?: (success: boolean) => void;
+}
+
 /**
  * 虚拟文件系统错误类
  */
-declare class VVVFSError extends Error {
+export class VVVFSError extends Error {
     /**
      * @param type 错误类型
      * @param message 错误信息
@@ -66,7 +93,7 @@ declare class VVVFSError extends Error {
  * 虚拟文件系统文件类
  * @param path 文件路径
  */
-declare class VVVFSFile {
+export class VVVFSFile {
     /**
      * 获取文件路径
      */
@@ -133,6 +160,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 文件对象
@@ -203,12 +241,23 @@ declare class VVVFSFile {
      * 判断文件是否已锁定
      */
     isLocked(): Promise<boolean>;
+    /**
+     * 保存文件
+     * @param name 文件名
+     */
+    save(name: string): Promise<boolean>;
+    /**
+     * 下载文件
+     * @param url 文件链接
+     * @param options 下载配置项
+     */
+    download(url: string | URL | Request, options?: VVVFSDownloadOptions): Promise<boolean>;
 }
 
 /**
  * path类（类似于NodeJS中的path模块）
  */
-declare class Path {
+export class Path {
     /**
      * 路径分隔符
      */
@@ -314,7 +363,7 @@ declare class Path {
  * @author IFTC
  * @description 虚拟文件系统
  */
-declare class VVVFS {
+export class VVVFS {
     static defaultDBName: string;
     /**
      * 虚拟文件系统版本
@@ -400,6 +449,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 文件路径
@@ -491,16 +559,33 @@ declare class VVVFS {
      * @param path 文件路径
      */
     isLocked(path: string): Promise<boolean>;
+    /**
+     * 保存文件
+     * @param path 文件路径
+     * @param name 文件名
+     */
+    saveFile(path: string, name?: string): Promise<boolean>;
+    /**
+     * 下载文件
+     * @param url 文件链接
+     * @param path 保存路径
+     * @param options 下载配置项
+     */
+    downloadFile(
+        url: string | URL | Request,
+        path: string,
+        options?: VVVFSDownloadOptions,
+    ): Promise<boolean>;
 }
 
 /**
  * 解析路径
  * @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;