object-storage-js/dist/index.d.ts

Object storage SDK for browser — supports server upload, MinIO, OBS, OSS, AWS S3, Qiniu Kodo, and Baidu BOS

/*!
 * object-storage-js v0.0.4
 * Object storage SDK for browser — supports server upload, MinIO, OBS, OSS, AWS S3, Qiniu Kodo, and Baidu BOS
 * https://gitee.com/lilele01/object-storage-js
 * Released under the MIT License.
 */
/**
 * 统一的上传进度快照。
 */
interface UploadProgress {
    /** 已上传字节数。 */
    loaded: number;
    /** 本次上传的总字节数。 */
    total: number;
    /** 上传百分比，范围为 0-100，保留 2 位小数。 */
    percent: number;
}
/**
 * 所有存储类型共用的上传参数。
 */
interface UploadParams {
    /** 需要上传的浏览器 File 对象。 */
    file: File;
    /** 目标对象 key；不传时默认使用 file.name。 */
    fileName?: string;
    /** 切换为分片上传的文件大小阈值。 */
    maxSize?: number;
    /** 分片大小，单位为字节。 */
    partSize?: number;
    /** 分片上传时允许同时上传的最大分片数。 */
    queueLength?: number;
    /** 服务端上传地址，仅 normal 上传需要。 */
    uploadUrl?: string;
    /** 服务端合并地址，仅 normal 分片上传需要。 */
    mergeUrl?: string;
    /** 上传凭证；例如七牛云上传 token。 */
    uploadToken?: string;
    /** 内容类型；未传时优先使用 file.type 或由 SDK 推断。 */
    contentType?: string;
    /** 透传给厂商上传方法的额外参数。 */
    sdkUploadParams?: Record<string, unknown>;
    /** 接收标准化后的整文件上传进度。 */
    onUploadProgress?: (progress: UploadProgress) => void;
    /** 上传可取消后接收取消句柄。 */
    onCancel?: (handle: CancelHandle) => void;
}
/**
 * 不同厂商 SDK 返回结构不一致，这里刻意保持宽松类型，仅约束 Promise 边界。
 */
type UploadResult = unknown;
/**
 * 支持的上传后端类型。
 */
declare enum ObjectStorageType {
    /** 上传到业务服务端接口。 */
    NORMAL = "normal",
    /** 阿里云 OSS 浏览器 SDK。 */
    OSS = "oss",
    /** 华为云 OBS 浏览器 SDK。 */
    OBS = "obs",
    /** 通过 AWS SDK v2 接入兼容 S3 协议的 MinIO。 */
    MINIO = "minio",
    /** 通过 AWS SDK v2 接入 AWS S3。 */
    AWS = "aws",
    /** 七牛云 Kodo JS SDK。 */
    QINIU = "qiniu",
    /** 百度智能云 BOS 浏览器 SDK。 */
    BOS = "bos"
}
/**
 * 暴露给调用方的上传取消句柄。
 */
interface CancelHandle {
    /** 基于 XHR 上传时的当前 XHR 实例。 */
    instance: XMLHttpRequest | null;
    /** 中断该句柄对应的上传任务。 */
    cancel: () => void;
}
/**
 * 内部适配器协议，用于隔离不同厂商 SDK 的差异。
 */
interface StorageAdapter<TInstance = unknown> {
    /** 当前适配器实现的存储后端类型。 */
    readonly type: ObjectStorageType;
    /** 已初始化的第三方 SDK 实例；normal 上传没有 SDK 实例。 */
    readonly instance: TInstance;
    /** 上传文件，并隐藏具体厂商实现细节。 */
    upload(params: UploadParams): Promise<UploadResult>;
    /** 当 SDK 支持全局取消时，取消厂商侧上传任务。 */
    cancel?(): void;
}
/**
 * 存储配置的公共字段。
 */
interface BaseObjectStorageConfig<TSdkObject = unknown> {
    /** 存储后端类型。 */
    type: ObjectStorageType;
    /** 透传给厂商 SDK 构造函数的额外参数。 */
    sdkOtherParams?: Record<string, unknown>;
    /** 由业务方传入的 SDK 构造函数或模块，避免本包内置厂商 SDK。 */
    sdkObject?: TSdkObject;
}
/**
 * 业务服务端上传配置。
 */
interface NormalObjectStorageConfig<TSdkObject = unknown> extends BaseObjectStorageConfig<TSdkObject> {
    type: ObjectStorageType.NORMAL;
}
/**
 * 阿里云 OSS 上传配置。
 */
interface OssObjectStorageConfig<TSdkObject = unknown> extends BaseObjectStorageConfig<TSdkObject> {
    type: ObjectStorageType.OSS;
    /** OSS SDK 构造函数，例如 ali-oss 的默认导出。 */
    sdkObject: TSdkObject;
    /** OSS endpoint，例如 https://oss-cn-hangzhou.aliyuncs.com。 */
    endPoint: string;
    /** SDK 客户端使用的 bucket 名称。 */
    bucketName: string;
    /** AccessKeyId；浏览器侧建议使用 STS 临时凭证。 */
    accessKey?: string;
    /** AccessKeySecret；浏览器侧建议使用 STS 临时凭证。 */
    secretKey?: string;
    /** 临时安全令牌。 */
    securityToken?: string;
    /** OSS region；不传时会尽量从 endPoint 推断。 */
    region?: string;
}
/**
 * 华为云 OBS 上传配置。
 */
interface ObsObjectStorageConfig<TSdkObject = unknown> extends BaseObjectStorageConfig<TSdkObject> {
    type: ObjectStorageType.OBS;
    /** OBS SDK 构造函数。 */
    sdkObject: TSdkObject;
    /** OBS 服务端点。 */
    endPoint: string;
    /** 签名和分片上传使用的 bucket 名称。 */
    bucketName: string;
    /** AccessKeyId；浏览器侧建议使用临时凭证。 */
    accessKey?: string;
    /** SecretAccessKey；浏览器侧建议使用临时凭证。 */
    secretKey?: string;
    /** 临时安全令牌。 */
    securityToken?: string;
}
/**
 * AWS S3 以及兼容 S3 协议的 MinIO 上传配置。
 */
interface S3ObjectStorageConfig<TSdkObject = unknown> extends BaseObjectStorageConfig<TSdkObject> {
    type: ObjectStorageType.MINIO | ObjectStorageType.AWS;
    /** 暴露 S3 构造函数的 AWS SDK v2 模块。 */
    sdkObject: TSdkObject;
    /** 目标 bucket 名称。 */
    bucketName: string;
    /** AccessKeyId；浏览器侧建议使用临时凭证。 */
    accessKey?: string;
    /** SecretAccessKey；浏览器侧建议使用临时凭证。 */
    secretKey?: string;
    /** 临时会话令牌。 */
    securityToken?: string;
    /** S3 endpoint；MinIO 或自建兼容 S3 服务通常必填。 */
    endPoint?: string;
    /** 目标服务需要时传入 AWS region。 */
    region?: string;
}
/**
 * 七牛云 Kodo 上传配置。
 */
interface QiniuObjectStorageConfig<TSdkObject = unknown> extends BaseObjectStorageConfig<TSdkObject> {
    type: ObjectStorageType.QINIU;
    /** 七牛云 JS SDK 模块，需暴露 upload 方法。 */
    sdkObject: TSdkObject;
    /** 默认上传 token；也可以在 upload(params.uploadToken) 中按次传入。 */
    uploadToken?: string;
}
/**
 * 百度智能云 BOS 上传配置。
 */
interface BosObjectStorageConfig<TSdkObject = unknown> extends BaseObjectStorageConfig<TSdkObject> {
    type: ObjectStorageType.BOS;
    /** 百度 BOS 浏览器 SDK 模块，需暴露 BosClient。 */
    sdkObject: TSdkObject;
    /** 目标 bucket 名称。 */
    bucketName: string;
    /** BOS endpoint，例如 https://bj.bcebos.com。 */
    endPoint: string;
    /** AccessKeyId；浏览器侧建议使用服务端签名或临时策略。 */
    accessKey?: string;
    /** SecretAccessKey；浏览器侧建议使用服务端签名或临时策略。 */
    secretKey?: string;
    /** 服务端签名接口；传入后会覆盖 SDK 默认签名逻辑。 */
    signatureUrl?: string;
}
/**
 * 所有支持的存储配置联合类型。
 */
type ObjectStorageConfig<TSdkObject = unknown> = NormalObjectStorageConfig<TSdkObject> | OssObjectStorageConfig<TSdkObject> | ObsObjectStorageConfig<TSdkObject> | S3ObjectStorageConfig<TSdkObject> | QiniuObjectStorageConfig<TSdkObject> | BosObjectStorageConfig<TSdkObject>;

/**
 * 浏览器端统一对象存储客户端。
 *
 * 该类保持对外 API 稳定，并将厂商初始化、上传等差异委托给内部适配器。
 */
declare class ObjectStorage<TInstance = unknown, TSdkObject = unknown> {
    private readonly adapter;
    /** 云厂商上传时为已初始化的 SDK 实例；normal 上传时为 undefined。 */
    readonly instance: TInstance;
    /** 当前存储后端使用 bucket 时的 bucket 名称。 */
    readonly bucketName: string | undefined;
    /** 当前选择的上传后端类型。 */
    readonly uploadType: ObjectStorageType;
    /**
     * 根据厂商配置创建存储客户端。
     */
    constructor(config: ObjectStorageConfig<TSdkObject>);
    /**
     * 使用当前配置的后端上传文件。
     */
    upload(params: UploadParams): Promise<UploadResult>;
    /**
     * 当适配器支持取消时，取消厂商侧上传任务。
     */
    cancel(): void;
}

export { ObjectStorage, ObjectStorageType, ObjectStorage as default };
export type { BaseObjectStorageConfig, BosObjectStorageConfig, CancelHandle, NormalObjectStorageConfig, ObjectStorageConfig, ObsObjectStorageConfig, OssObjectStorageConfig, QiniuObjectStorageConfig, S3ObjectStorageConfig, StorageAdapter, UploadParams, UploadProgress, UploadResult };