fsd-fs 0.14.1 → 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liang Xingchen https://github.com/liangxingchen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, destribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,29 +1,79 @@
 # fsd-fs
-FSD 本地磁盘文件读写适配器。
 
-```js
-const FSD = require('fsd');
-const FSAdapter = require('fsd-fs');
+FSD 本地文件系统适配器 - 提供对服务器磁盘文件的读写访问。
 
-const adapter = new FSAdapter(config);
+[![npm version](https://badge.fury.io/js/fsd-fs.svg)](https://www.npmjs.com/package/fsd-fs)
 
-const fsd = FSD({ adapter: adapter });
+## 概述
 
-let file = fsd('/test.txt');
+`fsd-fs` 是 `fsd` 核心库的本地文件系统适配器，提供完整的文件和目录操作能力。
 
-let content = await fsd.read();
+### 核心特性
 
+- ✅ 完整的文件读写操作
+- ✅ 目录管理（创建、删除、遍历）
+- ✅ 流式读写（大文件处理）
+- ✅ 分段上传（大文件优化）
+- ✅ 递归目录列表
+- ✅ Glob 模式匹配
+- ✅ 文件权限控制
+- ✅ 并发控制优化
+
+## 安装
+
+```bash
+npm install fsd-fs
 ```
 
-FSD 文档： https://github.com/liangxingchen/fsd
+## 配置
+
+```typescript
+import FSD from 'fsd';
+import FSAdapter from 'fsd-fs';
+
+// 创建适配器
+const adapter = new FSAdapter({
+  root: '/app/uploads',        // 必需：本地存储根路径
+  mode: 0o644,                  // 可选：创建文件权限（默认 0o644）
+  tmpdir: '/tmp/fsd-multipart', // 可选：临时目录（分段上传时使用，默认系统临时目录）
+  urlPrefix: 'https://cdn.example.com' // 可选：URL 前缀（生成访问链接时使用）
+});
+
+// 创建 FSD 实例
+const fsd = FSD({ adapter });
+```
+
+### 配置选项说明
+
+| 选项 | 类型 | 必需 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `root` | string | 是 | - | 本地存储根路径，所有文件操作限制在此目录下 |
+| `mode` | number | 否 | 0o644 | 创建文件时的权限模式（八进制） |
+| `tmpdir` | string | 否 | os.tmpdir() | 分段上传时的临时文件存储目录 |
+| `urlPrefix` | string | 否 | - | URL 前缀，用于生成访问链接，通常配合 CDN 或反向代理使用 |
+
+### 文件权限模式
+
+文件权限使用八进制表示法：
+
+| 模式 | 说明 |
+|------|------|
+| 0o644 | rw-r--r-- (用户读写，组和其他只读) - 最常用 |
+| 0o755 | rwxr-xr-x (用户读写执行，组和其他读执行) - 目录常用 |
+| 0o600 | rw------- (仅用户可读写) - 敏感文件 |
+| 0o666 | rw-rw-rw- (用户、组、其他都可读写) - 默认值 |
 
-适配器初始化选项：
+权限位说明：
+- `4` = read (读)
+- `2` = write (写)
+- `1` = execute (执行)
+- `0` = 无权限
 
-| 选项        | 类型     | 必须   | 说明                            |
-| --------- | ------ | ---- | ----------------------------- |
-| root      | string | Yes  | 本地存储根路径，例如 '/app/uploads'     |
-| mode      | number |      | 创建的文件权限，默认 `0o666`            |
-| tmpdir    | string |      | 临时目录，用于分段上传时暂存文件，如不使用分段上传，可省略 |
-| urlPrefix | string |      | URL前缀，用于生成下载链接                |
+示例 `0o644`:
+- 用户: 4+2+0 = 6 (rw)
+- 组: 4+0+0 = 4 (r--)
+- 其他: 4+0+0 = 4 (r--)
 
+## License
 
+MIT

package/index.d.ts

@@ -1,10 +1,148 @@
 import { Adapter } from 'fsd';
 
+/**
+ * FSAdapter 配置选项
+ *
+ * 本地文件系统适配器的初始化配置。
+ *
+ * @example
+ * ```typescript
+ * const adapter = new FSAdapter({
+ *   root: '/app/uploads',
+ *   mode: 0o644,
+ *   tmpdir: '/tmp/fsd-tmp',
+ *   urlPrefix: 'https://cdn.example.com'
+ * });
+ * ```
+ */
 export interface FSAdapterOptions {
+  /**
+   * 本地存储根路径（必需）
+   *
+   * 所有文件操作都会在此根路径下进行。
+   * 此路径必须是绝对路径，并且适配器有读取/写入权限。
+   *
+   * @example
+   * ```typescript
+   * // Linux/Mac
+   * root: '/app/uploads'
+   *
+   * // Windows
+   * root: 'C:\\app\\uploads'
+   * ```
+   *
+   * @remarks
+   * 确保此目录存在且有适当的读写权限。
+   */
   root: string;
+
+  /**
+   * 创建文件的权限模式（可选）
+   *
+   * 默认值：`0o644` (rw-rw-rw-)
+   *
+   * @example
+   * ```typescript
+   * mode: 0o644,  // rw-r--r-- (用户读写，组和其他只读）
+   * mode: 0o755,  // rwxr-xr-x (用户读写执行，组和其他读执行)
+   * mode: 0o600,  // rw------- (仅用户可读写）
+   * ```
+   *
+   * @remarks
+   * 使用八进制表示法（0o 前缀）或十进制都可以。
+   */
   mode?: number;
+
+  /**
+   * URL 前缀（可选）
+   *
+   * 用于生成访问链接时添加前缀。
+   * 通常配合 CDN 或反向代理使用。
+   *
+   * @example
+   * ```typescript
+   * urlPrefix: 'https://cdn.example.com',
+   * // file.createUrl() 返回: https://cdn.example.com/uploads/file.txt
+   * ```
+   *
+   * @remarks
+   * 尾部会自动去除 `/`，例如 `'https://cdn.com/'` 会被标准化为 `'https://cdn.com'`。
+   */
   urlPrefix?: string;
+
+  /**
+   * 临时目录（可选）
+   *
+   * 用于分段上传时暂存分片文件。
+   * 如果不使用分段上传功能，可以省略此选项。
+   *
+   * @example
+   * ```typescript
+   * tmpdir: '/tmp/fsd-multipart',
+   * // 或使用系统默认临时目录
+   * tmpdir: os.tmpdir()
+   * ```
+   *
+   * @remarks
+   * 默认值：系统临时目录（通过 `os.tmpdir()` 获取）。
+   * 确保临时目录有足够的磁盘空间用于存储分片文件。
+   */
   tmpdir?: string;
 }
 
+/**
+ * 本地文件系统适配器
+ *
+ * 提供对服务器本地磁盘文件的读写访问。
+ *
+ * @remarks
+ * ### 特性
+ * - 支持完整的文件和目录操作
+ * - 支持流式读写
+ * - 支持分段上传（大文件）
+ * - 支持递归目录列表
+ * - 使用 glob 模式匹配
+ *
+ * ### 权限要求
+ * - `root` 目录必须有读写权限
+ * - `tmpdir` 目录（用于分段上传）必须有读写权限
+ *
+ * ### 性能优化
+ * - 使用 `mapLimit` 限制并发操作，避免文件系统过载
+ * - 使用 `glob` 进行高效的目录遍历
+ *
+ * ### 分段上传机制
+ * 1. 调用 `initMultipartUpload()` 初始化任务
+ * 2. 每个分片写入到 `tmpdir` 下的临时文件
+ * 3. 调用 `completeMultipartUpload()` 时，所有临时文件会被顺序追加到目标文件
+ * 4. 完成后临时文件会被自动删除
+ *
+ * @example
+ * ```typescript
+ * import FSAdapter from 'fsd-fs';
+ * import FSD from 'fsd';
+ *
+ * // 创建适配器
+ * const adapter = new FSAdapter({
+ *   root: '/app/uploads',
+ *   mode: 0o644,
+ *   tmpdir: '/tmp/fsd-tmp'
+ * });
+ *
+ * // 创建 FSD 实例
+ * const fsd = FSD({ adapter });
+ *
+ * // 基本操作
+ * await fsd('/test.txt').write('Hello, FS!');
+ * const content = await fsd('/test.txt').read('utf8');
+ *
+ * // 分段上传大文件
+ * const file = fsd('/large-file.dat');
+ * const tasks = await file.initMultipartUpload(3);
+ * for (let i = 0; i < tasks.length; i++) {
+ *   await file.writePart(tasks[i], getDataForPart(i));
+ * }
+ * await file.completeMultipartUpload(['part://...', 'part://...', 'part://...']);
+ * ```
+ */
 export default class FSAdapter extends Adapter<FSAdapterOptions> {}

package/lib/index.js

@@ -25,7 +25,7 @@ class FSAdapter {
         this._options = Object.assign({
             urlPrefix: '',
             root: '/',
-            mode: 0o666,
+            mode: 0o644,
             tmpdir: os_1.default.tmpdir()
         }, options);
         let { urlPrefix } = this._options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fsd-fs",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "File system adapter for fsd",
   "main": "lib/index.js",
   "types": "index.d.ts",
@@ -9,12 +9,17 @@
     "prepublish": "npm run build"
   },
   "repository": "https://github.com/liangxingchen/fsd/tree/master/packages/fsd-fs",
-  "author": "Liang <liang@miaomo.cc> (https://github.com/liangxingchen)",
+  "author": {
+    "name": "Liang",
+    "email": "liang@miaomo.cn",
+    "url": "https://github.com/liangxingchen"
+  },
   "license": "MIT",
   "dependencies": {
     "async": "*",
     "debug": "^4.4.3",
     "glob": "^10.5.0",
     "is-stream": "^2.0.1"
-  }
+  },
+  "gitHead": "ea754919fb95b49deffd529b5c01c66da0dc08f9"
 }