vvvfs 0.1.5 → 0.1.7

package/README.md

@@ -2,6 +2,8 @@
 
 一个使用Dexie.js，基于IndexedDB的轻量、简单的浏览器中的Linux虚拟文件系统
 
+GitHub仓库: https://github.com/IFTC-XLKJ/vvvfs
+
 ## 快速开始
 
 1. 安装依赖
@@ -31,7 +33,8 @@ const VVVFS = require("vvvfs"); // CommonJS
 
 ```javascript
 const vvvfs = new VVVFS("vvvfs", {
-    throwError: true, // 设置为true后，操作文件失败时，不会返回false，而是会抛出错误
+  throwError: true, // 设置为true后，操作文件失败时，不会返回false，而是会抛出错误
+  init: "IFTC", // 自动初始化，用户名为 IFTC
 }); // 创建一个名为vvvfs的虚拟文件系统
 ```
 
@@ -40,34 +43,40 @@ const vvvfs = new VVVFS("vvvfs", {
 ```javascript
 // 所有操作都是异步的
 (async function () {
-    await vvvfs.reset(); // 重置文件系统
-    await vvvfs.init("UserName"); // 初始化文件系统
-    vvvfs.watch("/home/user/Desktop/test.txt", (type) => {
-        console.log(type); // 打印文件操作的类型
-        return true; // 返回true或false，表示是否取消该操作
-    });
-    await vvvfs.lock("/home/user/Desktop/test.txt"); // 锁定文件，防止其他代码访问该文件
-    await vvvfs.unlock("/home/user/Desktop/test.txt"); // 解锁文件
-    await vvvfs.createDir("/home/user/Desktop"); // 创建目录，返回true和false
-    await vvvfs.writeText("/home/user/Desktop/test.txt", "Hello World!"); // 写入文本文件，写入文件还包括write(path: string, content: Blob)和writeJson(path: string, content: Record<string, any>)方法，返回true和false
-    await vvvfs.appendText("/home/user/Desktop/test.txt", "Hello World!"); // 追加文本文件，返回true和false
-    console.log(await vvvfs.readText("/home/user/Desktop/test.txt")); // 读取文本文件，读取文件还包括read(path: string): Blob | null和readJson(path: string): Record<string, any> | null方法
-    console.log(await vvvfs.readChunkText("/home/user/Desktop/test.txt", 0, 5)); // 读取文件块，返回string | null
-    await vvvfs.delete("/home/user/Desktop/test.txt"); // 删除文件，返回true和false
-    if (await vvvfs.exists("/home/user/Desktop")) {
-        // 判断文件或目录是否存在
-    }
-    console.log(await vvvfs.list("/home/user/Desktop")); // 列出目录下的文件，返回string[] | null
-    if (await vvvfs.isDir("/home/user/Desktop")) {
-        // 判断是否为目录
-    }
-    if (await vvvfs.isFile("/home/user/Desktop/test.txt")) {
-        // 判断是否为文件
-    }
-    await vvvfs.rename("/home/user/Desktop/test.txt", "test2.txt"); // 重命名文件，返回true和false
-    await vvvfs.move("/home/user/Desktop/test2.txt", "/home/user/Desktop/test.txt"); // 移动文件，返回true和false
-    await vvvfs.copy("/home/user/Desktop/test.txt", "/home/user/Desktop/test2.txt"); // 复制文件，返回true和false
-    await vvvfs.search("/home/user/Desktop", "test.txt"); // 搜索文件，返回string[] | null
+  await vvvfs.reset(); // 重置文件系统
+  await vvvfs.init("UserName"); // 初始化文件系统
+  vvvfs.watch("/home/user/Desktop/test.txt", (type) => {
+    console.log(type); // 打印文件操作的类型
+    return true; // 返回true或false，表示是否取消该操作
+  });
+  await vvvfs.lock("/home/user/Desktop/test.txt"); // 锁定文件，防止其他代码访问该文件
+  await vvvfs.unlock("/home/user/Desktop/test.txt"); // 解锁文件
+  await vvvfs.createDir("/home/user/Desktop"); // 创建目录，返回true和false
+  await vvvfs.writeText("/home/user/Desktop/test.txt", "Hello World!"); // 写入文本文件，写入文件还包括write(path: string, content: Blob)和writeJson(path: string, content: Record<string, any>)方法，返回true和false
+  await vvvfs.appendText("/home/user/Desktop/test.txt", "Hello World!"); // 追加文本文件，返回true和false
+  console.log(await vvvfs.readText("/home/user/Desktop/test.txt")); // 读取文本文件，读取文件还包括read(path: string): Blob | null和readJson(path: string): Record<string, any> | null方法
+  console.log(await vvvfs.readChunkText("/home/user/Desktop/test.txt", 0, 5)); // 读取文件块，返回string | null
+  await vvvfs.delete("/home/user/Desktop/test.txt"); // 删除文件，返回true和false
+  if (await vvvfs.exists("/home/user/Desktop")) {
+    // 判断文件或目录是否存在
+  }
+  console.log(await vvvfs.list("/home/user/Desktop")); // 列出目录下的文件，返回string[] | null
+  if (await vvvfs.isDir("/home/user/Desktop")) {
+    // 判断是否为目录
+  }
+  if (await vvvfs.isFile("/home/user/Desktop/test.txt")) {
+    // 判断是否为文件
+  }
+  await vvvfs.rename("/home/user/Desktop/test.txt", "test2.txt"); // 重命名文件，返回true和false
+  await vvvfs.move(
+    "/home/user/Desktop/test2.txt",
+    "/home/user/Desktop/test.txt",
+  ); // 移动文件，返回true和false
+  await vvvfs.copy(
+    "/home/user/Desktop/test.txt",
+    "/home/user/Desktop/test2.txt",
+  ); // 复制文件，返回true和false
+  await vvvfs.search("/home/user/Desktop", "test.txt"); // 搜索文件，返回string[] | null
 })();
 ```
 
@@ -75,17 +84,25 @@ const vvvfs = new VVVFS("vvvfs", {
 
 ```javascript
 (async function () {
-    const file = new VVVFS.File("/home/user/Desktop/test.txt");
-    // file.options.throwError = true;
-    await file.writeText("Hello World!");
-    console.log(await file.readText());
-    await file.delete();
+  const file = new VVVFS.File("/home/user/Desktop/test.txt");
+  // file.options.throwError = true;
+  await file.writeText("Hello World!");
+  console.log(await file.readText());
+  await file.delete();
 })();
 // 用法与 vvvfs 相当
 ```
 
 ## 更新日志
 
+### 0.1.7
+
+- 新增 `init` 选项，用于是否自动初始化，传入字符串时，则为初始化的用户名，传入true时，则为默认用户名。
+
+### 0.1.6
+
+- 新增 `VVVFS.path` ，用法与 NodeJS 的 `path` 模块类似。
+
 ### 0.1.5
 
 - 重新 `lock` 和 `unlock` 方法
@@ -149,3 +166,176 @@ const vvvfs = new VVVFS("vvvfs", {
 ### 0.0.1
 
 - 发布正式版
+
+---
+
+# English
+
+# 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
+
+```bash
+npm install vvvfs
+```
+
+2. Import
+
+```javascript
+import VVVFS from "vvvfs"; // ES6
+```
+
+```javascript
+const VVVFS = require("vvvfs"); // CommonJS
+```
+
+```html
+<script src="dist/vvvfs.min.js"></script>
+<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>
+<!-- Browser -->
+```
+
+3. Initialize
+
+```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
+```
+
+4. Usage
+
+```javascript
+// All operations are asynchronous
+(async function () {
+  await vvvfs.reset(); // Reset the file system
+  await vvvfs.init("UserName"); // Initialize the file system
+  vvvfs.watch("/home/user/Desktop/test.txt", (type) => {
+    console.log(type); // Log the type of the file operation
+    return true; // Return true or false to indicate whether to cancel the operation
+  });
+  await vvvfs.lock("/home/user/Desktop/test.txt"); // Lock the file to prevent other code from accessing it
+  await vvvfs.unlock("/home/user/Desktop/test.txt"); // Unlock the file
+  await vvvfs.createDir("/home/user/Desktop"); // Create a directory, returns true and false
+  await vvvfs.writeText("/home/user/Desktop/test.txt", "Hello World!"); // Write a text file. Writing also includes write(path: string, content: Blob) and writeJson(path: string, content: Record<string, any>), returns true and false
+  await vvvfs.appendText("/home/user/Desktop/test.txt", "Hello World!"); // Append text to a file, returns true and false
+  console.log(await vvvfs.readText("/home/user/Desktop/test.txt")); // Read a text file. Reading also includes read(path: string): Blob | null and readJson(path: string): Record<string, any> | null
+  console.log(await vvvfs.readChunkText("/home/user/Desktop/test.txt", 0, 5)); // Read a file chunk, returns string | null
+  await vvvfs.delete("/home/user/Desktop/test.txt"); // Delete a file, returns true and false
+  if (await vvvfs.exists("/home/user/Desktop")) {
+    // Check whether a file or directory exists
+  }
+  console.log(await vvvfs.list("/home/user/Desktop")); // List the files in a directory, returns string[] | null
+  if (await vvvfs.isDir("/home/user/Desktop")) {
+    // Check whether it is a directory
+  }
+  if (await vvvfs.isFile("/home/user/Desktop/test.txt")) {
+    // Check whether it is a file
+  }
+  await vvvfs.rename("/home/user/Desktop/test.txt", "test2.txt"); // Rename a file, returns true and false
+  await vvvfs.move(
+    "/home/user/Desktop/test2.txt",
+    "/home/user/Desktop/test.txt",
+  ); // Move a file, returns true and false
+  await vvvfs.copy(
+    "/home/user/Desktop/test.txt",
+    "/home/user/Desktop/test2.txt",
+  ); // Copy a file, returns true and false
+  await vvvfs.search("/home/user/Desktop", "test.txt"); // Search for files, returns string[] | null
+})();
+```
+
+Using the `VVVFS.File` class:
+
+```javascript
+(async function () {
+  const file = new VVVFS.File("/home/user/Desktop/test.txt");
+  // file.options.throwError = true;
+  await file.writeText("Hello World!");
+  console.log(await file.readText());
+  await file.delete();
+})();
+// The usage is equivalent to vvvfs
+```
+
+## Changelog
+
+### 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.
+
+### 0.1.5
+
+- Redesigned the `lock` and `unlock` methods
+
+### 0.1.4
+
+- Optimized the code with AI
+
+### 0.1.3
+
+- Added the `lock` and `unlock` methods, which can lock files to prevent other code from accessing them
+
+### 0.1.2
+
+- Added the `readChunk` and `readChunkText` methods for reading file chunks
+
+### 0.1.1
+
+- Added the `append` and `appendText` methods for appending content
+
+### 0.1.0
+
+- Fixed `init` rewriting existing files and directories when initialized repeatedly
+
+### 0.0.9
+
+- Updated the `watch` method: while watching, returning `true` cancels the operation
+
+### 0.0.8
+
+- Added the `watch` method (this is an experimental feature and may change in the future)
+
+### 0.0.7
+
+- Optimized a bit with AI
+
+### 0.0.6
+
+- Added the `dbname` and `options` properties to the `VVVFS.File` class
+- Added the `defaultDBName` property to `VVVFS`
+
+### 0.0.5
+
+- Added the `VVVFS.File` class
+
+### 0.0.4
+
+- Fixed IndexedDB spamming a bunch of warnings
+- Fixed a bug in `search`
+
+### 0.0.3
+
+- Added maximum length limits: 4096 characters for full paths and 255 characters for file names
+- Added the `init` method for initializing Linux files and directories
+- Fixed a bug where `list` returned an empty string (the root directory itself) in the array when listing the root directory
+
+### 0.0.2
+
+- Added the `throwError` option, which defaults to `false`
+
+### 0.0.1
+
+- Initial release

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;
 }
 
 /**
@@ -274,6 +276,215 @@ class VVVFSFile {
     }
 }
 
+/**
+ * path类（类似于NodeJS中的path模块）
+ */
+class Path {
+    /**
+     * 路径分隔符
+     */
+    static readonly sep = "/";
+    /**
+     * 环境变量PATH的分隔符
+     */
+    static readonly delimiter = ":";
+    /**
+     * 内部存储的路径
+     */
+    private _path: string;
+    /**
+     * 构造函数
+     * @param paths 路径片段
+     */
+    constructor(...paths: string[]) {
+        this._path = Path.resolve(...paths);
+    }
+    /**
+     * 获取路径
+     */
+    get path() {
+        return this._path;
+    }
+    /**
+     * 设置路径
+     * @param path 路径
+     */
+    set path(path: string) {
+        this._path = Path.resolve(path);
+    }
+    /**
+     * 获取文件名
+     */
+    get name() {
+        return Path.basename(this._path);
+    }
+    /**
+     * 获取文件所在目录
+     */
+    get parent() {
+        return Path.dirname(this._path);
+    }
+    /**
+     * 获取文件扩展名
+     */
+    get ext() {
+        return Path.extname(this._path);
+    }
+    /**
+     * 获取根目录（"/"或""）
+     */
+    get root() {
+        return Path.parse(this._path).root;
+    }
+    /**
+     * 判断路径是否为绝对路径
+     */
+    isAbsolute() {
+        return Path.isAbsolute(this._path);
+    }
+    /**
+     * 合并路径
+     * @param paths 路径片段
+     */
+    join(...paths: string[]) {
+        return Path.join(this._path, ...paths);
+    }
+    /**
+     * 转换为字符串
+     */
+    toString() {
+        return this._path;
+    }
+    /**
+     * 合并路径
+     * @param paths 路径片段
+     */
+    static join(...paths: string[]) {
+        return joinPath(...paths);
+    }
+    /**
+     * 解析路径为绝对路径
+     * @param paths 路径片段
+     */
+    static resolve(...paths: string[]) {
+        return paths.length === 0 ? "/" : joinPath(...paths);
+    }
+    /**
+     * 规范化路径（清除"."、解析".."）
+     * @param path 路径
+     */
+    static normalize(path: string) {
+        if (path.length === 0) return ".";
+        const isAbsolute = path.startsWith("/");
+        const trailingSlash = path.length > 1 && path.endsWith("/");
+        const stack: string[] = [];
+        for (const part of path.split("/")) {
+            if (part === "" || part === ".") {
+                continue;
+            } else if (part === "..") {
+                if (stack.length > 0 && stack[stack.length - 1] !== "..") {
+                    stack.pop();
+                } else if (!isAbsolute) {
+                    stack.push("..");
+                }
+            } else {
+                stack.push(part);
+            }
+        }
+        let result = stack.join("/");
+        if (isAbsolute) {
+            result = "/" + result;
+        } else if (result.length === 0) {
+            result = ".";
+        }
+        if (trailingSlash && result !== "/" && result !== "." && !result.endsWith("/")) {
+            result += "/";
+        }
+        return result;
+    }
+    /**
+     * 判断路径是否为绝对路径
+     * @param path 路径
+     */
+    static isAbsolute(path: string) {
+        return path.length > 0 && path.startsWith("/");
+    }
+    /**
+     * 获取文件名（可去除后缀）
+     * @param path 路径
+     * @param suffix 后缀（如扩展名）
+     */
+    static basename(path: string, suffix?: string) {
+        if (path.length === 0) return "";
+        const normalized = Path.normalize(path);
+        if (normalized === "/") return "/";
+        let base = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+        base = base.slice(base.lastIndexOf("/") + 1);
+        if (suffix && base !== suffix && base.endsWith(suffix)) {
+            base = base.slice(0, base.length - suffix.length);
+        }
+        return base;
+    }
+    /**
+     * 获取文件所在目录
+     * @param path 路径
+     */
+    static dirname(path: string) {
+        const normalized = Path.normalize(path);
+        if (normalized === "/" || normalized === ".") return normalized;
+        const parts = normalized.split("/");
+        parts.pop();
+        const result = parts.join("/");
+        if (result.length === 0) {
+            return Path.isAbsolute(normalized) ? "/" : ".";
+        }
+        return result;
+    }
+    /**
+     * 获取文件扩展名
+     * @param path 路径
+     */
+    static extname(path: string) {
+        const base = Path.basename(path);
+        const lastDot = base.lastIndexOf(".");
+        if (lastDot <= 0) return "";
+        return base.slice(lastDot);
+    }
+    /**
+     * 解析路径
+     * @param path 路径
+     */
+    static parse(path: string) {
+        const base = Path.basename(path);
+        const ext = Path.extname(base);
+        return {
+            root: Path.isAbsolute(path) ? "/" : "",
+            dir: Path.dirname(path),
+            base,
+            ext,
+            name: ext.length > 0 ? base.slice(0, base.length - ext.length) : base,
+        };
+    }
+    /**
+     * 计算从from到to的相对路径
+     * @param from 起始路径
+     * @param to 目标路径
+     */
+    static relative(from: string, to: string) {
+        const fromParts = Path.resolve(from).split("/").filter((part) => part.length > 0);
+        const toParts = Path.resolve(to).split("/").filter((part) => part.length > 0);
+        let i = 0;
+        while (i < fromParts.length && i < toParts.length && fromParts[i] === toParts[i]) {
+            i++;
+        }
+        const up = new Array<string>(Math.max(0, fromParts.length - i)).fill("..").join("/");
+        const down = toParts.slice(i).join("/");
+        if (up.length > 0 && down.length > 0) return up + "/" + down;
+        if (up.length > 0) return up;
+        return down;
+    }
+}
+
 const version = packageJson.version;
 
 class VVVFS {
@@ -288,6 +499,10 @@ class VVVFS {
      * 虚拟文件系统文件类
      */
     static File = VVVFSFile;
+    /**
+     * path类（类似于NodeJS中的path模块）
+     */
+    static path = Path;
     /**
      * 虚拟文件系统监听器
      */
@@ -369,6 +584,7 @@ class VVVFS {
         name?: string,
         options = {
             throwError: false,
+            init: false,
         },
     ) {
         this.options = options;
@@ -386,6 +602,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", "创建数据库失败");

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "vvvfs",
-  "version": "0.1.5",
-  "description": "一个使用IndexDB实现的虚拟文件系统",
-  "keywords": [
-    "Virtual",
-    "File",
-    "System",
-    "IFTC",
-    "VV",
-    "File",
-    "System",
-    "vfs",
-    "fs"
-  ],
-  "license": "MIT",
-  "author": "IFTC",
-  "type": "module",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "node esbuild.config.js"
-  },
-  "dependencies": {
-    "dexie": "^4.3.0",
-    "esbuild": "^0.27.3",
-    "mime": "^4.1.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/IFTC-XLKJ/vvvfs.git"
-  }
-}
+{
+  "name": "vvvfs",
+  "version": "0.1.7",
+  "description": "一个使用IndexDB实现的虚拟文件系统",
+  "keywords": [
+    "Virtual",
+    "File",
+    "System",
+    "IFTC",
+    "VV",
+    "File",
+    "System",
+    "vfs",
+    "fs"
+  ],
+  "license": "MIT",
+  "author": "IFTC",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "node esbuild.config.js"
+  },
+  "dependencies": {
+    "dexie": "^4.3.0",
+    "esbuild": "^0.27.3",
+    "mime": "^4.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IFTC-XLKJ/vvvfs.git"
+  }
+}

package/types/index.d.ts

@@ -44,9 +44,11 @@ declare interface VVVFSDatabase extends Dexie {
 /**
  * 虚拟文件系统配置项
  * @param throwError 是否抛出错误
+ * @param init 是否自动初始化，传入字符串时，为用户名，传入true时，使用默认用户名
  */
-declare interface VVVFSOptions {
+export interface VVVFSOptions {
     throwError: boolean;
+    init: boolean | string;
 }
 
 /**
@@ -203,6 +205,110 @@ declare class VVVFSFile {
     isLocked(): Promise<boolean>;
 }
 
+/**
+ * path类（类似于NodeJS中的path模块）
+ */
+declare class Path {
+    /**
+     * 路径分隔符
+     */
+    static readonly sep: string;
+    /**
+     * 环境变量PATH的分隔符
+     */
+    static readonly delimiter: string;
+    /**
+     * 构造函数
+     * @param paths 路径片段
+     */
+    constructor(...paths: string[]);
+    /**
+     * 获取路径
+     */
+    get path(): string;
+    /**
+     * 设置路径
+     * @param path 路径
+     */
+    set path(path: string);
+    /**
+     * 获取文件名
+     */
+    get name(): string;
+    /**
+     * 获取文件所在目录
+     */
+    get parent(): string;
+    /**
+     * 获取文件扩展名
+     */
+    get ext(): string;
+    /**
+     * 获取根目录（"/"或""）
+     */
+    get root(): string;
+    /**
+     * 判断路径是否为绝对路径
+     */
+    isAbsolute(): boolean;
+    /**
+     * 合并路径
+     * @param paths 路径片段
+     */
+    join(...paths: string[]): string;
+    /**
+     * 转换为字符串
+     */
+    toString(): string;
+    /**
+     * 合并路径
+     * @param paths 路径片段
+     */
+    static join(...paths: string[]): string;
+    /**
+     * 解析路径为绝对路径
+     * @param paths 路径片段
+     */
+    static resolve(...paths: string[]): string;
+    /**
+     * 规范化路径（清除"."、解析".."）
+     * @param path 路径
+     */
+    static normalize(path: string): string;
+    /**
+     * 判断路径是否为绝对路径
+     * @param path 路径
+     */
+    static isAbsolute(path: string): boolean;
+    /**
+     * 获取文件名（可去除后缀）
+     * @param path 路径
+     * @param suffix 后缀（如扩展名）
+     */
+    static basename(path: string, suffix?: string): string;
+    /**
+     * 获取文件所在目录
+     * @param path 路径
+     */
+    static dirname(path: string): string;
+    /**
+     * 获取文件扩展名
+     * @param path 路径
+     */
+    static extname(path: string): string;
+    /**
+     * 解析路径
+     * @param path 路径
+     */
+    static parse(path: string): { root: string; dir: string; base: string; ext: string; name: string };
+    /**
+     * 计算从from到to的相对路径
+     * @param from 起始路径
+     * @param to 目标路径
+     */
+    static relative(from: string, to: string): string;
+}
+
 /**
  * 虚拟文件系统
  * @author IFTC
@@ -222,6 +328,10 @@ declare class VVVFS {
      * 虚拟文件系统文件类
      */
     static File: typeof VVVFSFile;
+    /**
+     * path类（类似于NodeJS中的path模块）
+     */
+    static path: typeof Path;
 
     options: VVVFSOptions;