fsd-tos 0.15.2

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/index.d.ts

@@ -0,0 +1,228 @@
+import { Adapter } from 'fsd';
+
+/**
+ * TOSAdapter 配置选项
+ *
+ * 火山引擎 TOS 对象存储适配器的初始化配置。
+ *
+ * @example
+ * ```typescript
+ * const adapter = new TOSAdapter({
+ *   accessKeyId: 'your-access-key-id',
+ *   accessKeySecret: 'your-access-key-secret',
+ *   region: 'cn-beijing',
+ *   bucket: 'my-bucket'
+ * });
+ * ```
+ */
+export interface TOSAdapterOptions {
+  /**
+   * TOS 访问 Key ID（必需）
+   *
+   * 火山引擎的 Access Key ID。
+   */
+  accessKeyId: string;
+
+  /**
+   * TOS 访问 Key Secret（必需）
+   *
+   * 火山引擎的 Access Key Secret。
+   *
+   * @remarks
+   * 请妥善保管此密钥，不要提交到代码仓库。
+   * 建议使用环境变量存储。
+   */
+  accessKeySecret: string;
+
+  /**
+   * TOS 区域（必需）
+   *
+   * 火山引擎 TOS 的区域，如 'cn-beijing'。
+   *
+   * @example
+   * ```typescript
+   * region: 'cn-beijing',   // 华北-北京
+   * region: 'cn-guangzhou', // 华南-广州
+   * region: 'cn-shanghai'   // 华东-上海
+   * ```
+   */
+  region: string;
+
+  /**
+   * TOS Bucket 名称（可选）
+   *
+   * 如果不指定，需要在上传时在 path 中包含 bucket 名称。
+   */
+  bucket?: string;
+
+  /**
+   * TOS Endpoint（可选）
+   *
+   * 默认根据 region 自动生成。
+   * 如需自定义可手动指定，如 'tos-cn-beijing.volces.com'。
+   */
+  endpoint?: string;
+
+  /**
+   * TOS 存储根路径（可选）
+   *
+   * 以 TOS 子目录作为存储根路径。
+   * 所有文件操作都会在此路径下进行。
+   *
+   * @defaultValue '/'
+   */
+  root?: string;
+
+  /**
+   * URL 前缀（可选）
+   *
+   * 用于生成访问链接时添加前缀。
+   * 通常配合 CDN 或反向代理使用。
+   */
+  urlPrefix?: string;
+
+  /**
+   * 是否公共读（可选）
+   *
+   * - `true`: 公共 Bucket，生成直接访问 URL（无需签名）
+   * - `false`: 私有 Bucket，生成带签名的临时 URL（默认值）
+   */
+  publicRead?: boolean;
+
+  /**
+   * 请求超时时间（可选）
+   *
+   * 单位：毫秒。
+   */
+  timeout?: number;
+
+  /**
+   * STS 临时 Token（可选）
+   *
+   * 用于临时凭证访问。
+   */
+  stsToken?: string;
+
+  /**
+   * 火山引擎账号 ID（可选）
+   *
+   * 用于 STS 角色扮演，生成边缘上传的临时凭证。
+   *
+   * @example
+   * ```typescript
+   * accountId: '2000000001',
+   * roleName: 'TOSUploadRole'
+   * ```
+   *
+   * @remarks
+   * 当同时提供 `accountId` 和 `roleName` 时，适配器会生成 STS 临时凭证。
+   * 临时凭证用于客户端直接上传到 TOS，无需通过服务器中转。
+   */
+  accountId?: string;
+
+  /**
+   * 火山引擎角色名称（可选）
+   *
+   * 用于 STS 角色扮演，配合 `accountId` 使用。
+   *
+   * @example
+   * ```typescript
+   * accountId: '2000000001',
+   * roleName: 'TOSUploadRole'
+   * ```
+   */
+  roleName?: string;
+
+  /**
+   * 上传回调 URL（可选）
+   *
+   * 文件上传完成后，TOS 会调用此 URL 通知应用。
+   *
+   * @example
+   * ```typescript
+   * callbackUrl: 'https://api.example.com/tos/callback'
+   * ```
+   */
+  callbackUrl?: string;
+}
+
+/**
+ * 火山引擎 TOS 适配器
+ *
+ * 提供对火山引擎 TOS 对象存储的访问能力。
+ *
+ * @remarks
+ * ### 核心特性
+ * - 完整的文件 CRUD 操作
+ * - 原生追加上传（AppendObject）
+ * - 分段上传（大文件优化）
+ * - 原生重命名（RenameObject）
+ * - 预签名 URL
+ *
+ * ### 不支持的操作
+ * - `createWriteStream({ start })` - 不支持 start 选项
+ *
+ * @example
+ * ```typescript
+ * import TOSAdapter from 'fsd-tos';
+ * import FSD from 'fsd';
+ *
+ * const adapter = new TOSAdapter({
+ *   accessKeyId: process.env.TOS_ACCESS_KEY_ID,
+ *   accessKeySecret: process.env.TOS_ACCESS_KEY_SECRET,
+ *   region: 'cn-beijing',
+ *   bucket: process.env.TOS_BUCKET
+ * });
+ *
+ * const fsd = FSD({ adapter });
+ * await fsd('/uploads/file.jpg').write(buffer);
+ * const url = await fsd('/uploads/file.jpg').createUrl({ expires: 3600 });
+ * ```
+ */
+/**
+ * 上传凭证
+ *
+ * 包含临时访问凭证的返回值。
+ */
+export interface UploadToken {
+  auth: {
+    accessKeyId: string;
+    accessKeySecret: string;
+    stsToken: string;
+    bucket: string;
+    endpoint: string;
+  };
+  path: string;
+  expiration: string;
+  callback?: any;
+}
+
+/**
+ * 带自动刷新的上传凭证
+ */
+export interface UploadTokenWithAutoRefresh {
+  auth: {
+    accessKeyId: string;
+    accessKeySecret: string;
+    stsToken: string;
+    bucket: string;
+    endpoint: string;
+    refreshSTSToken: () => Promise<{
+      accessKeyId: string;
+      accessKeySecret: string;
+      stsToken: string;
+    }>;
+  };
+  path: string;
+  expiration: string;
+  callback?: any;
+}
+
+export default class TOSAdapter extends Adapter<TOSAdapterOptions> {
+  createUploadToken: (path: string, meta?: any, durationSeconds?: number) => Promise<UploadToken>;
+  createUploadTokenWithAutoRefresh: (
+    path: string,
+    meta?: any,
+    durationSeconds?: number
+  ) => Promise<UploadTokenWithAutoRefresh>;
+}

package/lib/index.js

@@ -0,0 +1,429 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const slash_1 = tslib_1.__importDefault(require("slash"));
+const minimatch_1 = require("minimatch");
+const debug_1 = tslib_1.__importDefault(require("debug"));
+const tos_sdk_1 = require("@volcengine/tos-sdk");
+const openapi_1 = require("@volcengine/openapi");
+const stream_1 = require("stream");
+const debug = (0, debug_1.default)('fsd-tos');
+class TOSAdapter {
+    constructor(options) {
+        this.instanceOfFSDAdapter = true;
+        this.name = 'TOSAdapter';
+        this.needEnsureDir = false;
+        if (!options.accessKeyId)
+            throw new Error('option accessKeyId is required for fsd-tos');
+        if (!options.accessKeySecret)
+            throw new Error('option accessKeySecret is required for fsd-tos');
+        if (!options.region)
+            throw new Error('option region is required for fsd-tos');
+        options = Object.assign({}, options, { root: options.root || '/' });
+        if (options.root[0] !== '/') {
+            options.root = `/${options.root}`;
+        }
+        this._options = options;
+        this._tos = new tos_sdk_1.TosClient({
+            accessKeyId: options.accessKeyId,
+            accessKeySecret: options.accessKeySecret,
+            region: options.region,
+            bucket: options.bucket,
+            endpoint: options.endpoint,
+            stsToken: options.stsToken,
+            secure: true,
+            requestTimeout: options.timeout
+        });
+        if (options.accountId && options.roleName) {
+            this._sts = new openapi_1.sts.StsService();
+            this._sts.setAccessKeyId(options.accessKeyId);
+            this._sts.setSecretKey(options.accessKeySecret);
+        }
+        this.createUploadToken = async (path, meta, durationSeconds) => {
+            if (!options.accountId || !options.roleName)
+                throw new Error('Can not create sts token, missing options: accountId and roleName!');
+            path = (0, slash_1.default)(path_1.default.join(options.root, path)).substring(1);
+            let params = {
+                RoleTrn: `trn:iam::${options.accountId}:role/${options.roleName}`,
+                RoleSessionName: 'fsd',
+                Policy: JSON.stringify({
+                    Version: '1',
+                    Statement: [
+                        {
+                            Effect: 'Allow',
+                            Action: ['tos:PutObject'],
+                            Resource: [`trn:tos:*:*:${options.bucket}/${path}`]
+                        }
+                    ]
+                }),
+                DurationSeconds: durationSeconds || 3600
+            };
+            let result = await this._sts.AssumeRole(params);
+            if (result.ResponseMetadata?.Error) {
+                throw new Error(result.ResponseMetadata.Error.Message);
+            }
+            let creds = result.Result.Credentials;
+            let token = {
+                auth: {
+                    accessKeyId: creds.AccessKeyId,
+                    accessKeySecret: creds.SecretAccessKey,
+                    stsToken: creds.SessionToken,
+                    bucket: options.bucket,
+                    endpoint: `tos-${options.region}.volces.com`
+                },
+                path,
+                expiration: creds.ExpiredTime
+            };
+            if (options.callbackUrl) {
+                token.callback = {
+                    url: options.callbackUrl,
+                    body: Object.keys(meta || {})
+                        .map((key) => `${key}=\${x:${key}}`)
+                        .join('&'),
+                    contentType: 'application/x-www-form-urlencoded',
+                    customValue: meta
+                };
+            }
+            return token;
+        };
+        this.createUploadTokenWithAutoRefresh = async (path, meta, durationSeconds) => {
+            let token = await this.createUploadToken(path, meta, durationSeconds);
+            let auth = token.auth;
+            auth = Object.assign({}, auth, {
+                refreshSTSToken: async () => {
+                    let t = await this.createUploadToken(path, meta, durationSeconds);
+                    return t.auth;
+                }
+            });
+            return Object.assign({}, token, { auth });
+        };
+    }
+    async append(path, data) {
+        debug('append %s', path);
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        if (typeof data === 'string') {
+            data = Buffer.from(data);
+        }
+        if (Buffer.isBuffer(data)) {
+            let position = 0;
+            try {
+                position = await this.size(path);
+            }
+            catch (_e) { }
+            await this._tos.appendObject({ key: p, body: data, offset: position });
+        }
+        else {
+            let chunks = [];
+            await new Promise((resolve, reject) => {
+                data.on('data', (chunk) => chunks.push(chunk));
+                data.on('end', resolve);
+                data.on('error', reject);
+            });
+            let buf = Buffer.concat(chunks);
+            let position = 0;
+            try {
+                position = await this.size(path);
+            }
+            catch (_e) { }
+            await this._tos.appendObject({ key: p, body: buf, offset: position });
+        }
+    }
+    async createReadStream(path, options) {
+        debug('createReadStream %s options: %o', path, options);
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        let input = { key: p };
+        if (options) {
+            if (typeof options.start === 'number') {
+                input.rangeStart = options.start;
+            }
+            if (typeof options.end === 'number') {
+                input.rangeEnd = options.end;
+            }
+        }
+        let result = await this._tos.getObjectV2(input);
+        return result.data.content;
+    }
+    async createWriteStream(path, options) {
+        debug('createWriteStream %s', path);
+        if (options?.start)
+            throw new Error('fsd-tos write stream does not support start options');
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        let stream = new stream_1.PassThrough();
+        stream.promise = this._tos.putObject({ key: p, body: stream });
+        return stream;
+    }
+    async unlink(path) {
+        debug('unlink %s', path);
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        if (path.endsWith('/')) {
+            let continuationToken = '';
+            do {
+                let result = await this._tos.listObjectsType2({
+                    prefix: p,
+                    continuationToken,
+                    maxKeys: 1000
+                });
+                debug('unlink list: %O', result.data);
+                let list = result.data;
+                continuationToken = list.NextContinuationToken || '';
+                if (list.Contents?.length) {
+                    let objects = list.Contents.map((o) => ({ key: o.Key }));
+                    await this._tos.deleteMultiObjects({ objects, quiet: true });
+                }
+            } while (continuationToken);
+        }
+        else {
+            await this._tos.deleteObject({ key: p });
+        }
+    }
+    async mkdir(path, recursive) {
+        debug('mkdir %s', path);
+        let parent = path_1.default.dirname(path);
+        if (recursive && parent !== '/') {
+            parent += '/';
+            if (!(await this.exists(parent))) {
+                debug('mkdir prefix: %s', parent);
+                this.mkdir(parent, true);
+            }
+        }
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        await this._tos.putObject({ key: p, body: Buffer.from('') });
+    }
+    async readdir(path, recursion) {
+        debug('readdir %s', path);
+        let delimiter = recursion ? '' : '/';
+        let pattern = '';
+        if (recursion === true) {
+            pattern = '**/*';
+        }
+        else if (recursion) {
+            pattern = recursion;
+        }
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        let results = Object.create(null);
+        let continuationToken = '';
+        let hasContents = false;
+        let hasCommonPrefixes = false;
+        do {
+            let result = await this._tos.listObjectsType2({
+                prefix: p,
+                delimiter,
+                continuationToken,
+                maxKeys: 1000
+            });
+            let list = result.data;
+            debug('list: %O', list);
+            continuationToken = list.NextContinuationToken || '';
+            if (list.Contents) {
+                hasContents = true;
+                list.Contents.forEach((object) => {
+                    let relative = (0, slash_1.default)(path_1.default.relative(p, object.Key));
+                    if (!relative)
+                        return;
+                    if (object.Key.endsWith('/'))
+                        relative += '/';
+                    if (pattern && pattern !== '**/*' && !(0, minimatch_1.minimatch)(relative, pattern))
+                        return;
+                    results[relative] = {
+                        name: relative,
+                        metadata: {
+                            size: object.Size,
+                            lastModified: new Date(object.LastModified)
+                        }
+                    };
+                });
+            }
+            if (list.CommonPrefixes) {
+                hasCommonPrefixes = true;
+                list.CommonPrefixes.forEach((item) => {
+                    let relative = (0, slash_1.default)(path_1.default.relative(p, item.Prefix));
+                    if (!relative)
+                        return;
+                    relative += '/';
+                    results[relative] = {
+                        name: relative
+                    };
+                });
+            }
+        } while (continuationToken);
+        if (hasContents && hasCommonPrefixes) {
+            return Object.keys(results)
+                .sort()
+                .map((key) => results[key]);
+        }
+        return Object.values(results);
+    }
+    async createUrl(path, options) {
+        debug('createUrl %s', path);
+        options = Object.assign({}, options);
+        const { root, urlPrefix, publicRead } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path));
+        if (urlPrefix && publicRead) {
+            return urlPrefix + p;
+        }
+        let url = this._tos.getPreSignedUrl({
+            method: 'GET',
+            key: p.substring(1),
+            expires: options?.expires || 3600,
+            response: options?.response
+        });
+        if (urlPrefix) {
+            url = url.replace(/https?:\/\/[^/]+/, urlPrefix);
+        }
+        return url;
+    }
+    async copy(path, dest) {
+        debug('copy %s to %s', path, dest);
+        if (!(await this.exists(path)))
+            throw new Error('The source path is not exists!');
+        const { root, bucket } = this._options;
+        let from = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        let to = (0, slash_1.default)(path_1.default.join(root, dest)).substring(1);
+        if (path.endsWith('/')) {
+            debug('copy directory %s -> %s', from, to);
+            let continuationToken = '';
+            do {
+                let result = await this._tos.listObjectsType2({
+                    prefix: from,
+                    continuationToken,
+                    maxKeys: 1000
+                });
+                let list = result.data;
+                debug('list result: %O', list);
+                continuationToken = list.NextContinuationToken || '';
+                if (list.Contents?.length) {
+                    for (let object of list.Contents) {
+                        debug(' -> copy %s', object.Key);
+                        let relative = (0, slash_1.default)(path_1.default.relative(from, object.Key));
+                        let target = (0, slash_1.default)(path_1.default.join(to, relative));
+                        await this._tos.copyObject({
+                            key: target,
+                            srcBucket: bucket,
+                            srcKey: object.Key
+                        });
+                    }
+                }
+            } while (continuationToken);
+        }
+        else {
+            debug('copy file %s -> %s', from, to);
+            await this._tos.copyObject({
+                key: to,
+                srcBucket: bucket,
+                srcKey: from
+            });
+        }
+    }
+    async rename(path, dest) {
+        debug('rename %s to %s', path, dest);
+        if (!(await this.exists(path)))
+            throw new Error('Source path not found');
+        if (await this.exists(dest))
+            throw new Error('Target path already exists');
+        await this.copy(path, dest);
+        await this.unlink(path);
+    }
+    async exists(path) {
+        debug('check exists %s', path);
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        if (path.endsWith('/')) {
+            let result = await this._tos.listObjectsType2({
+                prefix: p,
+                maxKeys: 1
+            });
+            return result.data.Contents !== null && result.data.Contents.length > 0;
+        }
+        try {
+            await this._tos.headObject({ key: p });
+            return true;
+        }
+        catch (_e) {
+            return false;
+        }
+    }
+    async isFile(path) {
+        debug('check is file %s', path);
+        const { root } = this._options;
+        let p = (0, slash_1.default)(path_1.default.join(root, path)).substring(1);
+        try {
+            await this._tos.headObject({ key: p });
+            return true;
+        }
+        catch (_e) {
+            return false;
+        }
+    }
+    async isDirectory(path) {
+        debug('check is directory %s', path);
+        let p = (0, slash_1.default)(path_1.default.join(this._options.root, path)).substring(1);
+        try {
+            await this._tos.headObject({ key: p });
+            return true;
+        }
+        catch (_e) {
+            return false;
+        }
+    }
+    async size(path) {
+        debug('get file size %s', path);
+        let p = (0, slash_1.default)(path_1.default.join(this._options.root, path)).substring(1);
+        let result = await this._tos.headObject({ key: p });
+        return parseInt(result.data['content-length']) || 0;
+    }
+    async lastModified(path) {
+        debug('get file lastModified %s', path);
+        let p = (0, slash_1.default)(path_1.default.join(this._options.root, path)).substring(1);
+        let result = await this._tos.headObject({ key: p });
+        return new Date(result.data['last-modified']);
+    }
+    async initMultipartUpload(path, partCount) {
+        debug('initMultipartUpload %s, partCount: %d', path, partCount);
+        let p = (0, slash_1.default)(path_1.default.join(this._options.root, path)).substring(1);
+        let result = await this._tos.createMultipartUpload({ key: p });
+        let uploadId = result.data.UploadId;
+        let files = [];
+        for (let i = 1; i <= partCount; i += 1) {
+            files.push(`task://${uploadId}?${i}`);
+        }
+        return files;
+    }
+    async writePart(path, partTask, data, _size) {
+        debug('writePart %s, task: %s', path, partTask);
+        let p = (0, slash_1.default)(path_1.default.join(this._options.root, path)).substring(1);
+        if (!partTask.startsWith('task://'))
+            throw new Error('Invalid part task id');
+        let [uploadId, no] = partTask.replace('task://', '').split('?');
+        let result = await this._tos.uploadPart({
+            key: p,
+            uploadId,
+            partNumber: parseInt(no),
+            body: data
+        });
+        let etag = result.data.ETag;
+        return `${partTask.replace('task://', 'part://')}#${etag}`;
+    }
+    async completeMultipartUpload(path, parts) {
+        debug('completeMultipartUpload %s', path);
+        let uploadId = parts[0].replace('part://', '').split('?')[0];
+        let p = (0, slash_1.default)(path_1.default.join(this._options.root, path)).substring(1);
+        debug('upload id: %s, target: %s', uploadId, p);
+        let mappedParts = parts.map((item, key) => ({
+            eTag: item.split('#')[1],
+            partNumber: key + 1
+        }));
+        await this._tos.completeMultipartUpload({
+            key: p,
+            uploadId,
+            parts: mappedParts
+        });
+    }
+}
+exports.default = TOSAdapter;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "fsd-tos",
+  "version": "0.15.2",
+  "description": "Volcengine TOS adapter for fsd",
+  "main": "lib/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublish": "npm run build"
+  },
+  "repository": "https://github.com/liangxingchen/fsd/tree/master/packages/fsd-tos",
+  "author": {
+    "name": "Liang",
+    "email": "liang@miaomo.cn",
+    "url": "https://github.com/liangxingchen"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@volcengine/openapi": "^1.36.0",
+    "@volcengine/tos-sdk": "^2.9.1",
+    "debug": "^4.4.3",
+    "minimatch": "^9.0.5",
+    "slash": "^3.0.0"
+  },
+  "gitHead": "f65390dbe513ce81cd033ece4607aec024a88e48"
+}

package/src/index.ts

@@ -0,0 +1,484 @@
+import Path from 'path';
+import slash from 'slash';
+import { minimatch } from 'minimatch';
+import Debugger from 'debug';
+import { TosClient } from '@volcengine/tos-sdk';
+import { sts as volcSTS } from '@volcengine/openapi';
+import { PassThrough } from 'stream';
+import type {
+  ReadStreamOptions,
+  WriteStreamOptions,
+  Task,
+  Part,
+  FileMetadata,
+  CreateUrlOptions,
+  WithPromise
+} from 'fsd';
+import type { TOSAdapterOptions, UploadToken, UploadTokenWithAutoRefresh } from '..';
+
+const debug = Debugger('fsd-tos');
+
+export default class TOSAdapter {
+  instanceOfFSDAdapter: true;
+  name: string;
+  needEnsureDir: boolean;
+  _options: TOSAdapterOptions;
+  _tos: TosClient;
+  _sts: volcSTS.StsService;
+  createUploadToken: (path: string, meta?: any, durationSeconds?: number) => Promise<UploadToken>;
+  createUploadTokenWithAutoRefresh: (
+    path: string,
+    meta?: any,
+    durationSeconds?: number
+  ) => Promise<UploadTokenWithAutoRefresh>;
+
+  constructor(options: TOSAdapterOptions) {
+    this.instanceOfFSDAdapter = true;
+    this.name = 'TOSAdapter';
+    this.needEnsureDir = false;
+    /* istanbul ignore if */
+    if (!options.accessKeyId) throw new Error('option accessKeyId is required for fsd-tos');
+    /* istanbul ignore if */
+    if (!options.accessKeySecret) throw new Error('option accessKeySecret is required for fsd-tos');
+    /* istanbul ignore if */
+    if (!options.region) throw new Error('option region is required for fsd-tos');
+    options = Object.assign({}, options, { root: options.root || '/' });
+    if (options.root[0] !== '/') {
+      options.root = `/${options.root}`;
+    }
+    this._options = options;
+    this._tos = new TosClient({
+      accessKeyId: options.accessKeyId,
+      accessKeySecret: options.accessKeySecret,
+      region: options.region,
+      bucket: options.bucket,
+      endpoint: options.endpoint,
+      stsToken: options.stsToken,
+      secure: true,
+      requestTimeout: options.timeout
+    });
+
+    if (options.accountId && options.roleName) {
+      this._sts = new volcSTS.StsService();
+      this._sts.setAccessKeyId(options.accessKeyId);
+      this._sts.setSecretKey(options.accessKeySecret);
+    }
+
+    this.createUploadToken = async (path: string, meta?: any, durationSeconds?: number) => {
+      if (!options.accountId || !options.roleName)
+        throw new Error('Can not create sts token, missing options: accountId and roleName!');
+
+      path = slash(Path.join(options.root, path)).substring(1);
+      let params = {
+        RoleTrn: `trn:iam::${options.accountId}:role/${options.roleName}`,
+        RoleSessionName: 'fsd',
+        Policy: JSON.stringify({
+          Version: '1',
+          Statement: [
+            {
+              Effect: 'Allow',
+              Action: ['tos:PutObject'],
+              Resource: [`trn:tos:*:*:${options.bucket}/${path}`]
+            }
+          ]
+        }),
+        DurationSeconds: durationSeconds || 3600
+      };
+      let result = await this._sts.AssumeRole(params);
+      if (result.ResponseMetadata?.Error) {
+        throw new Error(result.ResponseMetadata.Error.Message);
+      }
+      let creds = result.Result!.Credentials;
+
+      let token: UploadToken = {
+        auth: {
+          accessKeyId: creds.AccessKeyId,
+          accessKeySecret: creds.SecretAccessKey,
+          stsToken: creds.SessionToken,
+          bucket: options.bucket,
+          endpoint: `tos-${options.region}.volces.com`
+        },
+        path,
+        expiration: creds.ExpiredTime
+      };
+
+      if (options.callbackUrl) {
+        token.callback = {
+          url: options.callbackUrl,
+          body: Object.keys(meta || {})
+            .map((key) => `${key}=\${x:${key}}`)
+            .join('&'),
+          contentType: 'application/x-www-form-urlencoded',
+          customValue: meta
+        };
+      }
+
+      return token;
+    };
+
+    this.createUploadTokenWithAutoRefresh = async (
+      path: string,
+      meta?: any,
+      durationSeconds?: number
+    ) => {
+      let token = await this.createUploadToken(path, meta, durationSeconds);
+      let auth = token.auth;
+      auth = Object.assign({}, auth, {
+        refreshSTSToken: async () => {
+          let t = await this.createUploadToken(path, meta, durationSeconds);
+          return t.auth;
+        }
+      });
+      return Object.assign({}, token, { auth }) as UploadTokenWithAutoRefresh;
+    };
+  }
+
+  async append(path: string, data: string | Buffer | NodeJS.ReadableStream): Promise<void> {
+    debug('append %s', path);
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+    if (typeof data === 'string') {
+      data = Buffer.from(data);
+    }
+    if (Buffer.isBuffer(data)) {
+      let position = 0;
+      try {
+        position = await this.size(path);
+      } catch (_e) {}
+      await this._tos.appendObject({ key: p, body: data, offset: position });
+    } else {
+      let chunks: Buffer[] = [];
+      await new Promise<void>((resolve, reject) => {
+        data.on('data', (chunk: Buffer) => chunks.push(chunk));
+        data.on('end', resolve);
+        data.on('error', reject);
+      });
+      let buf = Buffer.concat(chunks);
+      let position = 0;
+      try {
+        position = await this.size(path);
+      } catch (_e) {}
+      await this._tos.appendObject({ key: p, body: buf, offset: position });
+    }
+  }
+
+  async createReadStream(
+    path: string,
+    options?: ReadStreamOptions
+  ): Promise<NodeJS.ReadableStream> {
+    debug('createReadStream %s options: %o', path, options);
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+    let input: any = { key: p };
+    if (options) {
+      if (typeof options.start === 'number') {
+        input.rangeStart = options.start;
+      }
+      if (typeof options.end === 'number') {
+        input.rangeEnd = options.end;
+      }
+    }
+    // Default dataType='stream' returns GetObjectV2OutputStream with content: NodeJS.ReadableStream
+    let result: any = await this._tos.getObjectV2(input);
+    return result.data.content;
+  }
+
+  async createWriteStream(
+    path: string,
+    options?: WriteStreamOptions
+  ): Promise<NodeJS.WritableStream & WithPromise> {
+    debug('createWriteStream %s', path);
+    if (options?.start) throw new Error('fsd-tos write stream does not support start options');
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+    let stream: NodeJS.WritableStream & WithPromise = new PassThrough();
+    stream.promise = this._tos.putObject({ key: p, body: stream as any });
+    return stream;
+  }
+
+  async unlink(path: string): Promise<void> {
+    debug('unlink %s', path);
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+    if (path.endsWith('/')) {
+      let continuationToken = '';
+      do {
+        let result = await this._tos.listObjectsType2({
+          prefix: p,
+          continuationToken,
+          maxKeys: 1000
+        });
+        debug('unlink list: %O', result.data);
+        let list = result.data;
+        continuationToken = list.NextContinuationToken || '';
+        if (list.Contents?.length) {
+          let objects = list.Contents.map((o) => ({ key: o.Key }));
+          await this._tos.deleteMultiObjects({ objects, quiet: true });
+        }
+      } while (continuationToken);
+    } else {
+      await this._tos.deleteObject({ key: p });
+    }
+  }
+
+  async mkdir(path: string, recursive?: boolean): Promise<void> {
+    debug('mkdir %s', path);
+    let parent = Path.dirname(path);
+    if (recursive && parent !== '/') {
+      parent += '/';
+      if (!(await this.exists(parent))) {
+        debug('mkdir prefix: %s', parent);
+        this.mkdir(parent, true);
+      }
+    }
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+    await this._tos.putObject({ key: p, body: Buffer.from('') });
+  }
+
+  async readdir(
+    path: string,
+    recursion?: true | string
+  ): Promise<Array<{ name: string; metadata?: FileMetadata }>> {
+    debug('readdir %s', path);
+    let delimiter = recursion ? '' : '/';
+    let pattern = '';
+    if (recursion === true) {
+      pattern = '**/*';
+    } else if (recursion) {
+      pattern = recursion;
+    }
+
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+
+    let results: Record<string, { name: string; metadata?: FileMetadata }> = Object.create(null);
+    let continuationToken = '';
+    let hasContents = false;
+    let hasCommonPrefixes = false;
+    do {
+      let result = await this._tos.listObjectsType2({
+        prefix: p,
+        delimiter,
+        continuationToken,
+        maxKeys: 1000
+      });
+      let list = result.data;
+      debug('list: %O', list);
+      continuationToken = list.NextContinuationToken || '';
+      if (list.Contents) {
+        hasContents = true;
+        list.Contents.forEach((object) => {
+          let relative = slash(Path.relative(p, object.Key));
+          if (!relative) return;
+          if (object.Key.endsWith('/')) relative += '/';
+          if (pattern && pattern !== '**/*' && !minimatch(relative, pattern)) return;
+          results[relative] = {
+            name: relative,
+            metadata: {
+              size: object.Size,
+              lastModified: new Date(object.LastModified)
+            }
+          };
+        });
+      }
+      if (list.CommonPrefixes) {
+        hasCommonPrefixes = true;
+        list.CommonPrefixes.forEach((item) => {
+          let relative = slash(Path.relative(p, item.Prefix));
+          if (!relative) return;
+          relative += '/';
+          results[relative] = {
+            name: relative
+          };
+        });
+      }
+    } while (continuationToken);
+    if (hasContents && hasCommonPrefixes) {
+      return Object.keys(results)
+        .sort()
+        .map((key) => results[key]);
+    }
+    return Object.values(results);
+  }
+
+  async createUrl(path: string, options?: CreateUrlOptions): Promise<string> {
+    debug('createUrl %s', path);
+    options = Object.assign({}, options);
+    const { root, urlPrefix, publicRead } = this._options;
+    let p = slash(Path.join(root, path));
+    if (urlPrefix && publicRead) {
+      return urlPrefix + p;
+    }
+    let url = this._tos.getPreSignedUrl({
+      method: 'GET',
+      key: p.substring(1),
+      expires: options?.expires || 3600,
+      response: options?.response as any
+    });
+    if (urlPrefix) {
+      url = url.replace(/https?:\/\/[^/]+/, urlPrefix);
+    }
+    return url;
+  }
+
+  async copy(path: string, dest: string): Promise<void> {
+    debug('copy %s to %s', path, dest);
+    /* istanbul ignore if */
+    if (!(await this.exists(path))) throw new Error('The source path is not exists!');
+
+    const { root, bucket } = this._options;
+    let from = slash(Path.join(root, path)).substring(1);
+    let to = slash(Path.join(root, dest)).substring(1);
+
+    if (path.endsWith('/')) {
+      debug('copy directory %s -> %s', from, to);
+      let continuationToken = '';
+      do {
+        let result = await this._tos.listObjectsType2({
+          prefix: from,
+          continuationToken,
+          maxKeys: 1000
+        });
+        let list = result.data;
+        debug('list result: %O', list);
+        continuationToken = list.NextContinuationToken || '';
+        if (list.Contents?.length) {
+          for (let object of list.Contents) {
+            debug(' -> copy %s', object.Key);
+            let relative = slash(Path.relative(from, object.Key));
+            let target = slash(Path.join(to, relative));
+            await this._tos.copyObject({
+              key: target,
+              srcBucket: bucket,
+              srcKey: object.Key
+            });
+          }
+        }
+      } while (continuationToken);
+    } else {
+      debug('copy file %s -> %s', from, to);
+      await this._tos.copyObject({
+        key: to,
+        srcBucket: bucket,
+        srcKey: from
+      });
+    }
+  }
+
+  async rename(path: string, dest: string): Promise<void> {
+    debug('rename %s to %s', path, dest);
+    /* istanbul ignore if */
+    if (!(await this.exists(path))) throw new Error('Source path not found');
+    /* istanbul ignore if */
+    if (await this.exists(dest)) throw new Error('Target path already exists');
+    await this.copy(path, dest);
+    await this.unlink(path);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    debug('check exists %s', path);
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+    if (path.endsWith('/')) {
+      let result = await this._tos.listObjectsType2({
+        prefix: p,
+        maxKeys: 1
+      });
+      return result.data.Contents !== null && result.data.Contents.length > 0;
+    }
+    try {
+      await this._tos.headObject({ key: p });
+      return true;
+    } catch (_e) {
+      return false;
+    }
+  }
+
+  async isFile(path: string): Promise<boolean> {
+    debug('check is file %s', path);
+    const { root } = this._options;
+    let p = slash(Path.join(root, path)).substring(1);
+    try {
+      await this._tos.headObject({ key: p });
+      return true;
+    } catch (_e) {
+      return false;
+    }
+  }
+
+  async isDirectory(path: string): Promise<boolean> {
+    debug('check is directory %s', path);
+    let p = slash(Path.join(this._options.root, path)).substring(1);
+    try {
+      await this._tos.headObject({ key: p });
+      return true;
+    } catch (_e) {
+      return false;
+    }
+  }
+
+  async size(path: string): Promise<number> {
+    debug('get file size %s', path);
+    let p = slash(Path.join(this._options.root, path)).substring(1);
+    let result = await this._tos.headObject({ key: p });
+    return parseInt(result.data['content-length']) || 0;
+  }
+
+  async lastModified(path: string): Promise<Date> {
+    debug('get file lastModified %s', path);
+    let p = slash(Path.join(this._options.root, path)).substring(1);
+    let result = await this._tos.headObject({ key: p });
+    return new Date(result.data['last-modified']);
+  }
+
+  async initMultipartUpload(path: string, partCount: number): Promise<Task[]> {
+    debug('initMultipartUpload %s, partCount: %d', path, partCount);
+    let p = slash(Path.join(this._options.root, path)).substring(1);
+    let result = await this._tos.createMultipartUpload({ key: p });
+    let uploadId = result.data.UploadId;
+    let files = [];
+    for (let i = 1; i <= partCount; i += 1) {
+      files.push(`task://${uploadId}?${i}`);
+    }
+    return files;
+  }
+
+  async writePart(
+    path: string,
+    partTask: Task,
+    data: NodeJS.ReadableStream,
+    _size: number
+  ): Promise<Part> {
+    debug('writePart %s, task: %s', path, partTask);
+    let p = slash(Path.join(this._options.root, path)).substring(1);
+
+    if (!partTask.startsWith('task://')) throw new Error('Invalid part task id');
+
+    let [uploadId, no] = partTask.replace('task://', '').split('?');
+    let result = await this._tos.uploadPart({
+      key: p,
+      uploadId,
+      partNumber: parseInt(no),
+      body: data
+    });
+    let etag = result.data.ETag;
+    return `${partTask.replace('task://', 'part://')}#${etag}`;
+  }
+
+  async completeMultipartUpload(path: string, parts: Part[]): Promise<void> {
+    debug('completeMultipartUpload %s', path);
+    let uploadId = parts[0].replace('part://', '').split('?')[0];
+    let p = slash(Path.join(this._options.root, path)).substring(1);
+    debug('upload id: %s, target: %s', uploadId, p);
+    let mappedParts = parts.map((item, key) => ({
+      eTag: item.split('#')[1],
+      partNumber: key + 1
+    }));
+    await this._tos.completeMultipartUpload({
+      key: p,
+      uploadId,
+      parts: mappedParts
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    // "strict": true,
+    "noImplicitAny": true,
+    // "strictNullChecks": true,
+    // "strictFunctionTypes": true,
+    // "strictBindCallApply": true,
+    // "strictPropertyInitialization": true,
+    // "noImplicitThis": true,
+    "alwaysStrict": true,
+    "newLine": "lf",
+    "moduleResolution": "node",
+    "module": "CommonJS",
+    "importHelpers": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "removeComments": true,
+    "preserveConstEnums": true,
+    "outDir": "lib",
+    "baseUrl": ".",
+    "paths": {
+      "*": [
+        "../../packages/*",
+        "../../typings/*"
+      ]
+    },
+    "useDefineForClassFields": false,
+    "target": "ES2023",
+    "lib": [
+      "ES2023"
+    ]
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}