tiny-oss 0.5.0 → 1.0.0

package/UPGRADING.md

@@ -0,0 +1,151 @@
+# Upgrading to 1.0
+
+This guide walks through migrating a tiny-oss 0.x application (latest release: 0.5.1) to 1.0.0.
+
+tiny-oss 1.0 replaces the class-based API with a functional API. The `TinyOSS` class, the `new TinyOSS(...)` constructor and the `TinyOSS.*` namespace types are gone: every operation is a standalone function that takes the client options as its first argument, and all public types are top-level named exports. The SDK also grows from browser-only Aliyun OSS to multi-provider, multi-environment support — Tencent Cloud COS, Huawei Cloud OBS, AWS S3, Azure Blob Storage, plus Node.js, Service Workers and WeChat mini programs.
+
+## Quick migration
+
+Before (0.x):
+
+```js
+import TinyOSS from 'tiny-oss';
+
+const oss = new TinyOSS({
+  accessKeyId: 'your accessKeyId',
+  accessKeySecret: 'your accessKeySecret',
+  stsToken: 'security token',
+  region: 'oss-cn-beijing',
+  bucket: 'your bucket',
+});
+
+await oss.put('hello-world', blob);
+```
+
+After (1.0):
+
+```js
+import { put } from 'tiny-oss';
+
+const options = {
+  accessKeyId: 'your accessKeyId',
+  accessKeySecret: 'your accessKeySecret',
+  stsToken: 'security token',
+  region: 'oss-cn-beijing',
+  bucket: 'your bucket',
+};
+
+await put(options, 'hello-world', blob);
+```
+
+If you call operations from many places, `bindOptions` keeps the credentials in one place:
+
+```js
+import { put, bindOptions } from 'tiny-oss';
+
+const upload = bindOptions(put, {
+  accessKeyId: 'your accessKeyId',
+  accessKeySecret: 'your accessKeySecret',
+  region: 'oss-cn-beijing',
+  bucket: 'your bucket',
+});
+
+await upload('hello-world', blob);
+```
+
+## Breaking changes
+
+### 1. The `TinyOSS` class is removed
+
+| 0.x | 1.0 |
+| --- | --- |
+| `oss.put(name, blob)` | `put(options, name, blob)` |
+| `oss.putSymlink(name, target)` | `putSymlink(options, name, target)` |
+| `oss.signatureUrl(name, opts)` | `signatureUrl(options, name, opts)` |
+
+The options object is now required on every call, unless you bind it once with `bindOptions`. Other operations that were never on the 0.x class — the multipart and listing functions — use the same `options`-first convention.
+
+### 2. Types are top-level named exports
+
+Before:
+
+```ts
+import TinyOSS from 'tiny-oss';
+
+const options: TinyOSS.TinyOSSOptions = { /* ... */ };
+```
+
+After:
+
+```ts
+import { put, type Options, type PutOptions, type Progress, type SignatureUrlOptions } from 'tiny-oss';
+```
+
+`TinyOSSOptions` is renamed to `Options`. The `Progress` type is new.
+
+### 3. Progress callback shape changed
+
+0.x passed the native `ProgressEvent`; 1.0 passes a plain object:
+
+```ts
+interface Progress {
+  loaded: number;
+  total: number;
+  lengthComputable: boolean;
+}
+```
+
+`lengthComputable` can be `false` for transports without native progress reporting (fetch, wx.request); those adapters fire a 0% event before sending and a 100% event after.
+
+### 4. Input data widened
+
+0.x accepted `Blob` only; 1.0 accepts `Blob | ArrayBuffer | Uint8Array | string`. WeChat mini programs pass `ArrayBuffer`.
+
+### 5. Node.js and WeChat users must pick a transport
+
+The default transport is `XMLHttpRequest` (browsers). In Node.js / Service Workers:
+
+```js
+import { put, setTransport, fetchTransport } from 'tiny-oss';
+
+setTransport(fetchTransport);
+```
+
+In WeChat mini programs:
+
+```js
+import { put, setTransport, wxRequestTransport } from 'tiny-oss';
+
+setTransport(wxRequestTransport);
+```
+
+### 6. Provider entry points
+
+0.x was Aliyun OSS only, imported from the package root. 1.0 keeps OSS at the root and adds per-provider entries:
+
+- `tiny-oss` — Aliyun OSS
+- `tiny-oss/cos` — Tencent Cloud COS
+- `tiny-oss/obs` — Huawei Cloud OBS
+- `tiny-oss/aws` — AWS S3 and S3-compatible stores (MinIO, Cloudflare R2, Google Cloud Storage)
+- `tiny-oss/azure` — Azure Blob Storage
+- `tiny-oss/protocol` — the protocol layer for building custom providers
+
+Each entry exports its own `setTransport`, `getTransport`, `bindOptions` and its operation types by name.
+
+### 7. `Options` gained a field
+
+`pathStyle?: boolean` — S3-style path addressing (bucket in the URL path), required for S3-compatible endpoints such as MinIO and Cloudflare R2. Ignored by OSS.
+
+## New capabilities (no migration needed)
+
+1.0 adds operations 0.x never had:
+
+- `multipartUpload`, `initMultipartUpload`, `uploadPart`, `completeMultipartUpload`, `abortMultipartUpload`
+- `listParts`, `listUploads`, `uploadPartCopy`
+
+and two helpers: `bindOptions` (bind credentials to an operation once) and `setTransport`/`getTransport` (swap the network layer).
+
+## Notes
+
+- `put` still resolves to the parsed response body.
+- All 0.x option fields (`accessKeyId`, `accessKeySecret`, `stsToken`, `bucket`, `endpoint`, `region`, `internal`, `secure`, `timeout`, `cname`) are unchanged and keep their meaning.

package/dist/aws.d.ts

@@ -0,0 +1,208 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export declare const abortMultipartUpload: (options: Options, objectName: string, uploadId: string, multipartOptions?: MultipartOptions) => Promise<void>;
+export declare const completeMultipartUpload: (options: Options, objectName: string, uploadId: string, parts: PartInfo[], multipartOptions?: MultipartOptions) => Promise<CompleteMultipartUploadResult>;
+export declare const initMultipartUpload: (options: Options, objectName: string, multipartOptions?: MultipartOptions) => Promise<InitMultipartUploadResult>;
+export declare const listParts: (options: Options, objectName: string, uploadId: string, query?: ListQuery, multipartOptions?: MultipartOptions) => Promise<ListPartsResult>;
+export declare const listUploads: (options: Options, query?: ListUploadsQuery, multipartOptions?: MultipartOptions) => Promise<ListUploadsResult>;
+export declare const multipartUpload: (options: Options, objectName: string, file: BlobLike | string, multipartOptions?: MultipartUploadOptions) => Promise<CompleteMultipartUploadResult>;
+export declare const put: (options: Options, objectName: string, data: BlobLike | string, putOptions?: PutOptions) => Promise<any>;
+export declare const signatureUrl: (options: Options, objectName: string, urlOptions?: SignatureUrlOptions) => string;
+export declare const uploadPart: (options: Options, objectName: string, uploadId: string, partNo: number, data: BlobLike | string, start: number, end: number, multipartOptions?: MultipartOptions) => Promise<UploadPartResult>;
+export declare const uploadPartCopy: (options: Options, objectName: string, uploadId: string, partNo: number, range: string, sourceData: SourceData, copyOptions?: UploadPartCopyOptions) => Promise<UploadPartCopyResult>;
+/**
+ * Bind client options to an operation function, so callers don't have to
+ * repeat the credentials on every call. The returned function keeps the
+ * operation's original signature minus the leading options argument.
+ *
+ * Unlike a client object factory, this never references operations it
+ * isn't given, so tree shaking keeps working: importing `put` plus
+ * `bindOptions` still excludes the multipart code from the bundle.
+ *
+ * @example
+ * import { put, bindOptions } from 'tiny-oss';
+ * const upload = bindOptions(put, { accessKeyId, accessKeySecret, region, bucket });
+ * upload('hello.txt', blob);
+ */
+export declare function bindOptions<O, A extends unknown[], R>(operation: (options: O, ...args: A) => R, options: O): (...args: A) => R;
+/**
+ * fetch-based transport for Service Workers and Node.js, where
+ * XMLHttpRequest is unavailable. fetch cannot report intermediate
+ * upload progress, so a synthetic 0% event fires before sending and a
+ * 100% event after, with lengthComputable false.
+ */
+export declare function fetchTransport(url: string, options: TransportOptions): Promise<TransportResponse>;
+export declare function getTransport(): Transport;
+/**
+ * Replace the network layer. Defaults to XMLHttpRequest; pass a
+ * fetch-based adapter in Service Workers or a wx.request-based adapter
+ * in WeChat mini programs.
+ */
+export declare function setTransport(transport: Transport): void;
+/**
+ * wx.request-based transport for WeChat mini programs. Mini programs
+ * have no XMLHttpRequest and no Blob, so uploads must pass ArrayBuffer
+ * (see README). wx.request cannot report intermediate upload progress,
+ * so a synthetic 0% event fires before sending and a 100% event after,
+ * with lengthComputable false.
+ */
+export declare function wxRequestTransport(url: string, options: TransportOptions): Promise<TransportResponse>;
+export interface Checkpoint {
+	file: BlobLike | string;
+	name: string;
+	uploadId: string;
+	partSize: number;
+	parts: PartInfo[];
+	doneParts: PartInfo[];
+}
+export interface CompleteMultipartUploadResult {
+	name: string;
+	etag: string;
+	bucket?: string;
+	res?: any;
+}
+export interface InitMultipartUploadResult {
+	name: string;
+	uploadId: string;
+	res?: any;
+}
+export interface ListPartsResult {
+	isTruncated: boolean;
+	nextPartNumberMarker: number;
+	parts: Part[];
+	res?: any;
+}
+export interface ListQuery {
+	"max-parts"?: number;
+	"part-number-marker"?: number;
+}
+export interface ListUploadsQuery {
+	prefix?: string;
+	marker?: string;
+	"max-uploads"?: number;
+	"upload-id-marker"?: string;
+}
+export interface ListUploadsResult {
+	uploads: UploadInfo[];
+	isTruncated: boolean;
+	nextKeyMarker?: string;
+	nextUploadIdMarker?: string;
+	res?: any;
+}
+export interface MultipartOptions {
+	timeout?: number;
+	headers?: Record<string, any>;
+}
+export interface MultipartUploadOptions extends MultipartOptions {
+	parallel?: number;
+	partSize?: number;
+	checkpoint?: Checkpoint;
+	progress?: (percentage: number, checkpoint: Checkpoint, res?: any) => void;
+	meta?: Record<string, any>;
+	mime?: string;
+}
+export interface ObjectCallback {
+	url: string;
+	host?: string;
+	body: string;
+	contentType?: string;
+	customValue?: object;
+	headers?: object;
+}
+export interface Options {
+	accessKeyId: string;
+	accessKeySecret: string;
+	stsToken?: string;
+	bucket?: string;
+	endpoint?: string;
+	region?: string;
+	internal?: boolean;
+	secure?: boolean;
+	timeout?: string | number;
+	cname?: boolean;
+	pathStyle?: boolean;
+}
+export interface Part {
+	PartNumber: number;
+	LastModified: string;
+	ETag: string;
+	Size: number;
+}
+export interface PartInfo {
+	number: number;
+	etag: string;
+}
+export interface Progress {
+	loaded: number;
+	total: number;
+	lengthComputable: boolean;
+}
+export interface PutOptions {
+	onprogress?: (e: Progress) => any;
+}
+export interface ResponseHeaderType {
+	"content-type"?: string;
+	"content-disposition"?: string;
+	"cache-control"?: string;
+	"content-encoding"?: string;
+	"content-language"?: string;
+}
+export interface SignatureUrlOptions {
+	expires?: number;
+	method?: HTTPMethods;
+	"Content-Type"?: string;
+	process?: string;
+	response?: ResponseHeaderType;
+	callback?: ObjectCallback;
+	[key: string]: any;
+}
+export interface SourceData {
+	sourceKey: string;
+	sourceBucket?: string;
+}
+export interface TransportOptions {
+	method: string;
+	headers: Record<string, string>;
+	data?: any;
+	timeout?: number;
+	/**
+	 * Total payload size in bytes; transports without native progress
+	 * events use it to fire 0%/100% synthetic events.
+	 */
+	total?: number;
+	/**
+	 * Upload progress. lengthComputable is false when the environment
+	 * cannot report intermediate progress (fetch, wx.request); such
+	 * adapters fire a 0% event before sending and a 100% event after.
+	 */
+	onprogress?: (e: Progress) => void;
+}
+export interface TransportResponse {
+	data: string;
+	headers: Record<string, string>;
+	status: number;
+	statusText: string;
+}
+export interface UploadInfo {
+	uploadId: string;
+	name: string;
+	initiated: string;
+}
+export interface UploadPartCopyOptions extends MultipartOptions {
+	headers?: Record<string, any>;
+}
+export interface UploadPartCopyResult {
+	etag: string;
+	lastModified: string;
+	res?: any;
+}
+export interface UploadPartResult {
+	name: string;
+	etag: string;
+	res?: any;
+}
+export type BlobLike = Blob | ArrayBuffer | Uint8Array;
+export type HTTPMethods = "GET" | "POST" | "DELETE" | "PUT";
+export type Transport = (url: string, options: TransportOptions) => Promise<TransportResponse>;
+
+export {};

package/dist/azure.d.ts

@@ -0,0 +1,204 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export declare const multipartUpload: (options: Options, objectName: string, file: BlobLike | string, multipartOptions?: MultipartUploadOptions) => Promise<CompleteMultipartUploadResult>;
+export declare const put: (options: Options, objectName: string, data: BlobLike | string, putOptions?: PutOptions) => Promise<any>;
+export declare const signatureUrl: (options: Options, objectName: string, urlOptions?: SignatureUrlOptions) => string;
+/**
+ * Bind client options to an operation function, so callers don't have to
+ * repeat the credentials on every call. The returned function keeps the
+ * operation's original signature minus the leading options argument.
+ *
+ * Unlike a client object factory, this never references operations it
+ * isn't given, so tree shaking keeps working: importing `put` plus
+ * `bindOptions` still excludes the multipart code from the bundle.
+ *
+ * @example
+ * import { put, bindOptions } from 'tiny-oss';
+ * const upload = bindOptions(put, { accessKeyId, accessKeySecret, region, bucket });
+ * upload('hello.txt', blob);
+ */
+export declare function bindOptions<O, A extends unknown[], R>(operation: (options: O, ...args: A) => R, options: O): (...args: A) => R;
+export declare function completeMultipartUpload(options: Options, objectName: string, uploadId: string, parts: PartInfo[], multipartOptions?: MultipartOptions): Promise<CompleteMultipartUploadResult>;
+/**
+ * fetch-based transport for Service Workers and Node.js, where
+ * XMLHttpRequest is unavailable. fetch cannot report intermediate
+ * upload progress, so a synthetic 0% event fires before sending and a
+ * 100% event after, with lengthComputable false.
+ */
+export declare function fetchTransport(url: string, options: TransportOptions): Promise<TransportResponse>;
+export declare function getTransport(): Transport;
+export declare function initMultipartUpload(options: Options, objectName: string, multipartOptions?: MultipartOptions): Promise<InitMultipartUploadResult>;
+/**
+ * Replace the network layer. Defaults to XMLHttpRequest; pass a
+ * fetch-based adapter in Service Workers or a wx.request-based adapter
+ * in WeChat mini programs.
+ */
+export declare function setTransport(transport: Transport): void;
+export declare function uploadPart(options: Options, objectName: string, uploadId: string, partNo: number, data: BlobLike | string, start: number, end: number, multipartOptions?: MultipartOptions): Promise<UploadPartResult>;
+/**
+ * wx.request-based transport for WeChat mini programs. Mini programs
+ * have no XMLHttpRequest and no Blob, so uploads must pass ArrayBuffer
+ * (see README). wx.request cannot report intermediate upload progress,
+ * so a synthetic 0% event fires before sending and a 100% event after,
+ * with lengthComputable false.
+ */
+export declare function wxRequestTransport(url: string, options: TransportOptions): Promise<TransportResponse>;
+export interface Checkpoint {
+	file: BlobLike | string;
+	name: string;
+	uploadId: string;
+	partSize: number;
+	parts: PartInfo[];
+	doneParts: PartInfo[];
+}
+export interface CompleteMultipartUploadResult {
+	name: string;
+	etag: string;
+	bucket?: string;
+	res?: any;
+}
+export interface InitMultipartUploadResult {
+	name: string;
+	uploadId: string;
+	res?: any;
+}
+export interface ListPartsResult {
+	isTruncated: boolean;
+	nextPartNumberMarker: number;
+	parts: Part[];
+	res?: any;
+}
+export interface ListQuery {
+	"max-parts"?: number;
+	"part-number-marker"?: number;
+}
+export interface ListUploadsQuery {
+	prefix?: string;
+	marker?: string;
+	"max-uploads"?: number;
+	"upload-id-marker"?: string;
+}
+export interface ListUploadsResult {
+	uploads: UploadInfo[];
+	isTruncated: boolean;
+	nextKeyMarker?: string;
+	nextUploadIdMarker?: string;
+	res?: any;
+}
+export interface MultipartOptions {
+	timeout?: number;
+	headers?: Record<string, any>;
+}
+export interface MultipartUploadOptions extends MultipartOptions {
+	parallel?: number;
+	partSize?: number;
+	checkpoint?: Checkpoint;
+	progress?: (percentage: number, checkpoint: Checkpoint, res?: any) => void;
+	meta?: Record<string, any>;
+	mime?: string;
+}
+export interface ObjectCallback {
+	url: string;
+	host?: string;
+	body: string;
+	contentType?: string;
+	customValue?: object;
+	headers?: object;
+}
+export interface Options {
+	accessKeyId: string;
+	accessKeySecret: string;
+	stsToken?: string;
+	bucket?: string;
+	endpoint?: string;
+	region?: string;
+	internal?: boolean;
+	secure?: boolean;
+	timeout?: string | number;
+	cname?: boolean;
+	pathStyle?: boolean;
+}
+export interface Part {
+	PartNumber: number;
+	LastModified: string;
+	ETag: string;
+	Size: number;
+}
+export interface PartInfo {
+	number: number;
+	etag: string;
+}
+export interface Progress {
+	loaded: number;
+	total: number;
+	lengthComputable: boolean;
+}
+export interface PutOptions {
+	onprogress?: (e: Progress) => any;
+}
+export interface ResponseHeaderType {
+	"content-type"?: string;
+	"content-disposition"?: string;
+	"cache-control"?: string;
+	"content-encoding"?: string;
+	"content-language"?: string;
+}
+export interface SignatureUrlOptions {
+	expires?: number;
+	method?: HTTPMethods;
+	"Content-Type"?: string;
+	process?: string;
+	response?: ResponseHeaderType;
+	callback?: ObjectCallback;
+	[key: string]: any;
+}
+export interface SourceData {
+	sourceKey: string;
+	sourceBucket?: string;
+}
+export interface TransportOptions {
+	method: string;
+	headers: Record<string, string>;
+	data?: any;
+	timeout?: number;
+	/**
+	 * Total payload size in bytes; transports without native progress
+	 * events use it to fire 0%/100% synthetic events.
+	 */
+	total?: number;
+	/**
+	 * Upload progress. lengthComputable is false when the environment
+	 * cannot report intermediate progress (fetch, wx.request); such
+	 * adapters fire a 0% event before sending and a 100% event after.
+	 */
+	onprogress?: (e: Progress) => void;
+}
+export interface TransportResponse {
+	data: string;
+	headers: Record<string, string>;
+	status: number;
+	statusText: string;
+}
+export interface UploadInfo {
+	uploadId: string;
+	name: string;
+	initiated: string;
+}
+export interface UploadPartCopyOptions extends MultipartOptions {
+	headers?: Record<string, any>;
+}
+export interface UploadPartCopyResult {
+	etag: string;
+	lastModified: string;
+	res?: any;
+}
+export interface UploadPartResult {
+	name: string;
+	etag: string;
+	res?: any;
+}
+export type BlobLike = Blob | ArrayBuffer | Uint8Array;
+export type HTTPMethods = "GET" | "POST" | "DELETE" | "PUT";
+export type Transport = (url: string, options: TransportOptions) => Promise<TransportResponse>;
+
+export {};