tiny-oss

A tiny object storage SDK focused on uploading: Aliyun OSS, Tencent Cloud COS, Huawei Cloud OBS, Volcano Engine TOS, AWS S3 (plus S3-compatible stores) and Azure Blob Storage under one core API; runs in browsers, Node.js, Service Workers and WeChat mini programs; extensible with custom providers. About 10kb (min+gzipped) for the full entry — tree-shaking drops the operations you don't import, so a bundle that only calls put is smaller.

Upgrading from 0.x? See the upgrade guide.

Installation

pnpm

pnpm add tiny-oss

Npm

npm install tiny-oss

Yarn

yarn add tiny-oss

Usage

Every operation is a standalone function taking the client options as the first argument. Import only what you use and bundlers tree-shake the rest, so a bundle that only calls put does not carry the multipart code.

Basic

import { put } from 'tiny-oss';

const blob = new Blob(['hello world'], { type: 'text/plain' });

// Upload
put(
  {
    accessKeyId: 'your accessKeyId',
    accessKeySecret: 'your accessKeySecret',
    // Recommend to use the stsToken option in browser
    stsToken: 'security token',
    region: 'oss-cn-beijing',
    bucket: 'your bucket'
  },
  'hello-world',
  blob
);

Available functions: put, putSymlink, signatureUrl, initMultipartUpload, uploadPart, completeMultipartUpload, abortMultipartUpload, listParts, listUploads, uploadPartCopy, multipartUpload, bindOptions.

Types are available via named imports: import { put, type Options, type BlobLike, type PutOptions, type Progress, type SignatureUrlOptions } from 'tiny-oss'.

Binding options once

To avoid passing the credentials on every call, bind them once with bindOptions. It only references the operation you give it, so tree shaking is unaffected:

import { put, bindOptions } from 'tiny-oss';

const upload = bindOptions(put, {
  accessKeyId: 'your accessKeyId',
  accessKeySecret: 'your accessKeySecret',
  stsToken: 'security token',
  region: 'oss-cn-beijing',
  bucket: 'your bucket'
});

upload('hello-world', new Blob(['hello world'], { type: 'text/plain' }));

Upload progress

You can specify the last parameter to monitor the upload progress data:

put(
  options,
  'hello-world',
  blob,
  {
    onprogress (e) {
      console.log('total: ', e.total, ', uploaded: ', e.loaded);
    }
  }
);

multipartUpload reports progress in fractions of parts, not bytes: its progress option fires after each part finishes with percentage = parts done ÷ total parts. Full option list and callback semantics in the multipartUpload API section below.

More options or methods see API.

Upload callback

Some providers can call back your server after an object is stored, then relay the callback response back to the client. A direct upload (bytes never pass through your server) can still be validated, recorded and acted upon by your backend.

Provider	put / multipartUpload	Transport
Aliyun OSS	✅ `callback` (fired on complete)	`x-oss-callback` / `x-oss-callback-var` headers, base64 JSON — ali-oss compatible
Huawei OBS	✅ `callback` (fired on complete)	`x-obs-callback` header, base64 JSON — esdk-obs-browserjs compatible; `customValue` is not supported
Tencent COS	via `headers` only	official SDK passes the callback header value through verbatim, so pass `headers` such as `{ 'x-cos-callback': '…' }` yourself; the value format is defined by the COS server API
Volcano Engine TOS	via `headers` only	pass `headers` such as `{ 'x-tos-callback': '…' }` (and `x-tos-callback-var`); the value format is defined by the TOS server API
AWS S3 / Azure Blob	❌	no callback API

import { put } from 'tiny-oss';

put(options, 'avatar.jpg', blob, {
  callback: {
    url: 'https://api.example.com/oss-callback', // issued by your server
    body: 'bucket=$(bucket)&object=$(object)&etag=$(etag)&uid=$(x:uid)',
    customValue: { uid: currentUser.id }, // OSS only: $(x:uid) in the body
  },
});

Notes:

The callback URL is your server's endpoint — in direct-upload setups the callback is normally issued by your backend together with the signed credentials, so clients never choose it.
With a callback, the upload response body is the callback server's reply (res.data), not the usual empty body/XML. On multipartUpload the complete response is then not the CompleteMultipartUpload XML, so the returned etag is empty.
Passing callback to a provider without a callback API rejects at runtime instead of silently doing nothing. Signed URLs (signatureUrl) do not carry callbacks.

Protocol

The Protocol interface (tiny-oss/protocol):

field	meaning
`request(options, params)`	Sign and send one request through the configured transport; resolve `{ data, headers, status, statusText }`
`signUrl(options, objectName, urlOptions)`	Build a signed download URL
`metaPrefix`	Object metadata header prefix, e.g. `'x-my-meta-'`
`copySourceHeader` / `copySourceRangeHeader`	Header names for `uploadPartCopy`
`listUploadsMarkerKey`	Query key for the list-uploads marker (`'marker'` OSS-style, `'key-marker'` S3-style)
`supportsSymlink`	Whether `putSymlink` is exported (`false` when the provider has no symlink API)
`symlinkHeaders`	Optional: serialize the `putSymlink` target into headers (defaults to OSS's `x-oss-symlink-target` with an encodeURI'd target)

request receives { verb, objectName, contentMd5, headers, subResource, data, timeout, onprogress }; subResource is the query-parameter map the operations build ({ uploads: '' }, { partNumber, uploadId }, …) — the request implementation decides which of them participate in the signature.

The shared helpers normalizeOptions, resolveTimeout and dataSize (also exported from tiny-oss/protocol) cover option defaults, timeout and payload sizing for the request implementation. Because each entry is a separate build, a custom provider never inflates the OSS bundle — import it from its own file.

Compatibility

It should work in most browsers, as well as Node.js, Service Workers and WeChat mini programs (see Non-browser environments).

This package depends on some Web APIs, such as Blob, Uint8Array, Promise. In browsers it uses XMLHttpRequest for network requests; other environments inject their own transport (see below).

Non-browser environments

The network layer is injectable. Browsers use XMLHttpRequest by default; Service Workers and WeChat mini programs have ready-made adapters:

// Service Worker (or Node.js)
import { setTransport, fetchTransport } from 'tiny-oss';
setTransport(fetchTransport);

// WeChat mini program
import { setTransport, wxRequestTransport } from 'tiny-oss';
setTransport(wxRequestTransport);

The input data types are environment agnostic: Blob, ArrayBuffer, Uint8Array and plain strings are all accepted (mini programs don't have Blob, so pass ArrayBuffer).

WeChat mini program upload

import { put, multipartUpload } from 'tiny-oss';

const arrayBuffer = getFileArrayBuffer(); // e.g. from FileSystemManager.readFile

put(options, 'photo.jpg', arrayBuffer);
multipartUpload(options, 'video.mp4', arrayBuffer, { partSize: 1024 * 1024 });

Custom transport

For other environments, pass your own function to setTransport. It receives (url, { method, headers, data, timeout, onprogress, total }) and must resolve with { data, headers, status, statusText }, rejecting on failure:

setTransport(async (url, { method, headers, data, timeout }) => {
  // adapt to your platform's request API
});

Progress events

onprogress receives { loaded, total, lengthComputable }. Browsers report real upload progress (lengthComputable: true). fetch and wx.request cannot report intermediate progress, so those adapters fire a 0% event before sending and a 100% event after, with lengthComputable: false — use them to toggle a loading state, not to render a percentage.

Providers

AWS S3

The same operations are available for AWS S3 through a dedicated entry point (tiny-oss/aws). Each entry is self-contained: importing only what you use keeps the OSS bundle free of COS/OBS/S3 signing code and vice versa.

import { put, multipartUpload, signatureUrl } from 'tiny-oss/aws';

put(
  {
    accessKeyId: 'your Access Key ID',
    accessKeySecret: 'your Secret Access Key',
    // Recommend to use the stsToken option in browser
    stsToken: 'security token',
    region: 'us-west-2',
    bucket: 'your-bucket'
  },
  'hello-world',
  blob
);

The AWS entry exports everything the OSS entry does except putSymlink (S3 has no symlink API). Options:

option	type	description
`accessKeyId`	`string`	AWS Access Key ID
`accessKeySecret`	`string`	AWS Secret Access Key
`stsToken`	`string`	temporary-credential SessionToken (`x-amz-security-token`)
`region`	`string`	e.g. `us-east-1`, `ap-southeast-1`
`bucket`	`string`	plain bucket name
`endpoint`	`string`	custom endpoint, no protocol prefix (the `secure` option selects it)
`secure`	`boolean`	use HTTPS (`true`) or HTTP (`false`), default `true`
`timeout`	`string \| number`	instance-level timeout for all operations, default 60s

Notes:

Browser uploads to S3 require the bucket's CORS rule to allow your origin and expose the ETag response header for multipart uploads; temporary credentials (STS) are recommended over permanent keys.
The signer implements SigV4 with UNSIGNED-PAYLOAD (the official SDK disables body signing for S3), so it is byte-identical to aws-sdk v2.
Signatures are time-sensitive; a skewed client clock yields 403 RequestTimeTooSkewed.

S3-compatible stores (MinIO, Cloudflare R2, Google Cloud Storage, …)

S3-compatible stores speak SigV4, so the tiny-oss/aws entry works with zero extra code — just point the endpoint at the store and enable pathStyle (these stores address buckets in the URL path, like the official SDK's forcePathStyle):

import { put, signatureUrl, multipartUpload } from 'tiny-oss/aws';

// MinIO
await put(
  {
    accessKeyId: 'minioadmin',
    accessKeySecret: 'minioadmin',
    region: 'us-east-1',
    bucket: 'my-bucket',
    endpoint: 'minio.example.com', // no protocol prefix
    secure: false, // local MinIO usually serves plain HTTP
    pathStyle: true,
  },
  'hello-world',
  blob
);

// Cloudflare R2 — region is always 'auto'
await put(
  {
    accessKeyId: 'your R2 Access Key ID',
    accessKeySecret: 'your R2 Secret Access Key',
    region: 'auto',
    bucket: 'my-bucket',
    endpoint: '<accountid>.r2.cloudflarestorage.com',
    pathStyle: true,
  },
  'hello-world',
  blob
);

// Google Cloud Storage — XML API's AWS SigV4-compatible mode.
// Create an HMAC key in the Cloud Console first; region is 'auto'.
await put(
  {
    accessKeyId: 'your GCS HMAC access id',
    accessKeySecret: 'your GCS HMAC secret',
    region: 'auto',
    bucket: 'my-bucket',
    endpoint: 'storage.googleapis.com',
    pathStyle: true,
  },
  'hello-world',
  blob
);

The endpoint must not carry a protocol (http:///https://) — the secure option selects it. Every operation (put, multipart, list, copy, signed URLs) works unchanged against these stores.

Not every store speaks S3: Azure Blob Storage uses its own SharedKey signing and a different multipart model (block blobs), so it is not covered by the AWS entry.

Tencent Cloud COS

The same operations are available for Tencent Cloud COS through a separate entry point. The OSS entry never references COS code and vice versa, so importing only what you use keeps the OSS bundle free of COS signing code (and the other way around).

import { put, multipartUpload, signatureUrl } from 'tiny-oss/cos';

put(
  {
    accessKeyId: 'your SecretId',
    accessKeySecret: 'your SecretKey',
    // Recommend to use the stsToken option in browser
    stsToken: 'security token',
    region: 'ap-guangzhou',
    bucket: 'your-bucket-1250000000' // COS bucket names include the APPID suffix
  },
  'hello-world',
  blob
);

The COS entry exports everything the OSS entry does except putSymlink (COS has no symlink API). Options:

option	type	description
`accessKeyId`	`string`	Tencent SecretId
`accessKeySecret`	`string`	Tencent SecretKey
`stsToken`	`string`	temporary-credential SecurityToken (`x-cos-security-token`)
`region`	`string`	e.g. `ap-guangzhou`
`bucket`	`string`	must include the APPID suffix, e.g. `examplebucket-1250000000`
`endpoint`	`string`	custom endpoint, no protocol prefix (the `secure` option selects it)
`secure`	`boolean`	use HTTPS (`true`) or HTTP (`false`), default `true`
`timeout`	`string \| number`	instance-level timeout for all operations, default 60s

Notes:

Like OSS, browser uploads to COS require a CORS rule on the bucket, and temporary credentials (CAM STS) are recommended over permanent keys.
Set the bucket CORS rule to expose the ETag response header for multipart uploads.
COS signatures are time-sensitive; a skewed client clock yields 403 RequestTimeTooSkewed.

Huawei Cloud OBS

The same operations are also available for Huawei Cloud OBS through a dedicated entry point (tiny-oss/obs). Each entry is self-contained: importing only what you use keeps the OSS bundle free of COS/OBS signing code and vice versa.

import { put, multipartUpload, signatureUrl } from 'tiny-oss/obs';

put(
  {
    accessKeyId: 'your Access Key Id',
    accessKeySecret: 'your Secret Access Key',
    // Recommend to use the stsToken option in browser
    stsToken: 'security token',
    region: 'cn-north-4',
    bucket: 'your-bucket' // OBS bucket names carry no suffix
  },
  'hello-world',
  blob
);

The OBS entry exports everything the OSS entry does except putSymlink (OBS has no symlink API). Options:

option	type	description
`accessKeyId`	`string`	Huawei Cloud Access Key Id
`accessKeySecret`	`string`	Huawei Cloud Secret Access Key
`stsToken`	`string`	temporary-credential SecurityToken (`x-obs-security-token`)
`region`	`string`	e.g. `cn-north-4`, `cn-east-3`
`bucket`	`string`	plain bucket name (no APPID suffix)
`endpoint`	`string`	custom endpoint, no protocol prefix (the `secure` option selects it)
`secure`	`boolean`	use HTTPS (`true`) or HTTP (`false`), default `true`
`timeout`	`string \| number`	instance-level timeout for all operations, default 60s

Notes:

Browser uploads to OBS require the bucket's CORS rule to allow your origin and expose the ETag response header for multipart uploads; temporary credentials (IAM agency) are recommended over permanent keys.
OBS signatures are time-sensitive (the x-obs-date header); a skewed client clock yields 403 RequestTimeTooSkewed.
The OBS signer uses the OBS "obs" signature scheme, matching the official esdk-obs-browserjs byte for byte.
OBS endpoints only serve HTTPS, so the SDK defaults secure to true; keep the default unless you connect to a custom HTTP endpoint.

Volcano Engine TOS

The same operations are also available for Volcano Engine Torch Object Storage (TOS) through a dedicated entry point (tiny-oss/tos). Each entry is self-contained: importing only what you use keeps the OSS bundle free of COS/OBS/TOS signing code and vice versa.

import { put, multipartUpload, signatureUrl } from 'tiny-oss/tos';

put(
  {
    accessKeyId: 'your Access Key ID',
    accessKeySecret: 'your Secret Access Key',
    // Recommend to use the stsToken option in browser
    stsToken: 'security token',
    region: 'cn-beijing',
    bucket: 'your-bucket'
  },
  'hello-world',
  blob
);

The TOS entry exports everything the OSS entry does, including putSymlink (TOS has a symlink API). Options:

option	type	description
`accessKeyId`	`string`	Volcano Engine Access Key ID
`accessKeySecret`	`string`	Volcano Engine Secret Access Key
`stsToken`	`string`	temporary-credential SecurityToken (`x-tos-security-token`)
`region`	`string`	e.g. `cn-beijing`, `ap-southeast-1`; always required — the TOS4 credential scope embeds it
`bucket`	`string`	plain bucket name
`endpoint`	`string`	endpoint domain the bucket is prefixed to (`<bucket>.<endpoint>`), e.g. `tos-cn-beijing.volces.com`; unlike the other entries it is not the full host, because TOS only supports virtual-hosted addressing
`internal`	`boolean`	use the Volcengine internal network domain (`tos-<region>.ivolces.com`), default `false`
`secure`	`boolean`	use HTTPS (`true`) or HTTP (`false`), default `true`
`timeout`	`string \| number`	instance-level timeout for all operations, default 60s

Notes:

The signer implements TOS4-HMAC-SHA256 (service tos, host + x-tos-* signed headers, UNSIGNED-PAYLOAD body), byte-identical to @volcengine/tos-sdk; test/tos-oracle.node.ts pins it.
TOS native endpoints are virtual-hosted only and reject path-style addressing, so there is no pathStyle option. TOS's S3-compatible endpoints (tos-s3-<region>.volces.com) need AWS Signature V4 with virtual-hosted addressing, which this package does not implement — use the native endpoints above.
signatureUrl returns a TOS4-HMAC-SHA256 query-signed URL (X-Tos-* parameters, TTL X-Tos-Expires). The credential scope uses region; the official JS SDK's getPreSignedUrl substitutes the endpoint there, which disagrees with the official Go SDK.
Callbacks: pass x-tos-callback / x-tos-callback-var through headers (like COS); the structured callback option is OSS/OBS-only.
Browser uploads to TOS require the bucket's CORS rule to allow your origin and expose the ETag response header for multipart uploads; temporary credentials (STS) are recommended over permanent keys.

Azure Blob Storage

Azure Blob Storage speaks neither SigV4 nor any of the other schemes above: it uses its own SharedKey authorization and a different multipart model (block blobs). A dedicated entry point (tiny-oss/azure) implements both, so the API stays the same:

import { put, multipartUpload, signatureUrl } from 'tiny-oss/azure';

put(
  {
    accessKeyId: 'your storage account name',
    accessKeySecret: 'your base64 account key',
    bucket: 'your-container'
  },
  'hello-world',
  blob
);

The Azure entry exports put, signatureUrl, initMultipartUpload, uploadPart, completeMultipartUpload, multipartUpload and bindOptions. Options:

option	type	description
`accessKeyId`	`string`	storage account name
`accessKeySecret`	`string`	the base64 account key (used after base64-decoding, per SharedKey)
`bucket`	`string`	container name
`region`	`string`	not used (no region concept in the Blob service)
`stsToken`	`string`	not used (use a SAS or stored access policy instead)
`endpoint`	`string`	custom endpoint, no protocol prefix
`secure`	`boolean`	use HTTPS (`true`) or HTTP (`false`), default `true`
`timeout`	`string \| number`	instance-level timeout for all operations, default 60s

Notes:

Every request carries x-ms-date and x-ms-version; the StringToSign is the 12-field SharedKey format with canonicalized x-ms-* headers and the canonicalized resource, verified byte-for-byte against @azure/storage-common and the MSDN example.
signatureUrl returns a service SAS (sv=2020-12-06, sr=b), byte-identical to @azure/storage-blob's generateBlobSASQueryParameters. It is valid immediately; method: 'PUT' grants write.
multipartUpload uses Azure's block-blob model: parallel Put Block (?comp=block&blockid=<base64>) calls followed by a single Put Block List (?comp=blocklist). There is no server-side upload session, so abortMultipartUpload, listParts, listUploads and uploadPartCopy are intentionally absent.
Metadata passed to multipartUpload is applied on the final Put Block List, which is where Azure sets blob metadata.
Browser uploads require the container's CORS rule to allow your origin and expose the ETag response header for multipartUpload.
Use the shared-key (or SAS) flow only over HTTPS; the account key is a root credential — for anything user-facing prefer a server-generated SAS.

Extension

Every operation is a factory over a Protocol — the extension point. A provider only has to implement two functions (request, signUrl) and fill in five constants; all operations (put, multipart, list, copy, …) then work unchanged. The built-in providers are the reference recipes: src/cos/, src/obs/, src/tos/, src/aws/ (S3-shaped, each with its own signer) and src/azure/ (non-S3-shaped — see the Protocol section for the interface).

Composing a custom provider

import {
  createPut,
  createInitMultipartUpload,
  createUploadPart,
  createCompleteMultipartUpload,
  createMultipartUpload,
  createListUploads,
  type Protocol,
} from 'tiny-oss/protocol';

const myProtocol = {
  request(options, params) {
    // 1. build the URL: host + '/' + objectName + sub-resource query
    // 2. sign: compute your Authorization header from verb/date/headers/query
    // 3. return getTransport()(url, { method, headers, data, timeout });
    //    (import { getTransport } from 'tiny-oss')
  },
  signUrl(options, objectName, urlOptions) { /* signed URL string */ },
  metaPrefix: 'x-my-meta-',
  copySourceHeader: 'x-my-copy-source',
  copySourceRangeHeader: 'x-my-copy-source-range',
  listUploadsMarkerKey: 'marker',
  supportsSymlink: false,
};

const put = createPut(myProtocol);
const initMultipartUpload = createInitMultipartUpload(myProtocol);
const uploadPart = createUploadPart(myProtocol);
const completeMultipartUpload = createCompleteMultipartUpload(myProtocol);
const multipartUpload = createMultipartUpload(myProtocol, {
  initMultipartUpload,
  uploadPart,
  completeMultipartUpload,
});

export { put, multipartUpload, signatureUrl: myProtocol.signUrl };

Contributing a provider to the repo

Follow the src/aws/ layout: src/<provider>/{signature,host,request,signatureUrl,index}.ts, then add an entry to tsup.config.ts (the one build emits both the .es.js bundle and the matching .es.d.ts) and a package.json exports entry. Signing must match the official SDK — the tests in test/cos-signature.spec.ts, test/obs-signature.spec.ts and test/aws-signature.spec.ts pin each signer against its official SDK as an oracle (test/tos-oracle.node.ts, run by pnpm test:tos-oracle, does the same for TOS against @volcengine/tos-sdk).

If the target storage's multipart API is not S3-shaped (e.g. Azure's block blobs), don't force it through createInitMultipartUpload/createUploadPart/createCompleteMultipartUpload: write provider-specific primitives with the same signatures and inject them via createMultipartUpload (see src/azure/multipart.ts). Operations that have no counterpart — like listUploads for Azure — are simply omitted from the entry.

API

options

The first argument of every operation. Only accessKeyId and accessKeySecret are required; the rest are optional:

interface Options {
  accessKeyId: string;        // Aliyun AccessKeyId
  accessKeySecret: string;    // Aliyun AccessKeySecret
  stsToken?: string;          // temporary credentials (recommended in browser)
  bucket?: string;            // the bucket to access
  endpoint?: string;          // the region domain; takes priority over region
  region?: string;            // the bucket's data region; required unless endpoint is set
  internal?: boolean;         // access OSS over Aliyun's internal network, default is false
  secure?: boolean;           // use HTTPS (true) or HTTP (false), default is true
  timeout?: string | number;  // instance-level timeout for all operations, default is 60s
  cname?: boolean;            // use a custom domain name
  pathStyle?: boolean;        // S3-style path addressing (bucket in the URL path); required for S3-compatible endpoints such as MinIO and Cloudflare R2
}

put(options, objectName, blob, putOptions)

Upload the blob.

put(
  options: Options,
  objectName: string,
  blob: BlobLike | string, // BlobLike = Blob | ArrayBuffer | Uint8Array
  putOptions?: PutOptions  // { onprogress?: (e: Progress) => any }
): Promise<any>

Arguments

options: Options — the client options, see above.
objectName: string — the object name.
blob: BlobLike | string — the object to be uploaded (BlobLike = Blob | ArrayBuffer | Uint8Array).
putOptions?: PutOptions — optional upload options.
- onprogress?: (e: Progress) => any — the upload progress event listener receiving a progress event object as a parameter.

Return

Promise<any>

multipartUpload(options, objectName, blob, multipartOptions)

Upload a large blob in parts with bounded parallelism, retries and optional resume support. It splits the blob into parts of partSize bytes, uploads them through the provider's multipart primitives and completes the upload server-side.

multipartUpload(
  options: Options,
  objectName: string,
  blob: BlobLike | string, // BlobLike = Blob | ArrayBuffer | Uint8Array
  multipartOptions?: MultipartUploadOptions
): Promise<CompleteMultipartUploadResult>

Arguments

options: Options — the client options, see above.
objectName: string — the object name.
blob: BlobLike | string — the data to upload. Must be non-empty: an empty input throws. Mini programs pass an ArrayBuffer (no Blob there).
multipartOptions: MultipartUploadOptions — optional upload options:
- parallel?: number — how many parts upload concurrently, default 5.
- partSize?: number — part size in bytes, default 1MB (1024 * 1024). Values below 100KB are raised to the enforced 100KB minimum.
- checkpoint?: Checkpoint — resume state from an interrupted upload ({ file, name, uploadId, partSize, parts, doneParts }). It is honored only when the checkpoint's file size matches the current input; on resume, partSize is taken from the checkpoint so part ranges and the final part list stay consistent. Resuming skips the init call, so meta/mime/headers are not applied then (the server keeps the values from the original init — except Azure: its init is a local label with no request, so metadata is held only in memory and a resumed upload loses it once the page reloads).
- progress?: (percentage: number, checkpoint: Checkpoint, res?: any) => void — called after each part finishes; see semantics below.
- meta?: Record<string, any> — object metadata, attached as per-provider metadata headers on the init request (the Azure block-blob entry holds them and applies them on the final Put Block List — see the Azure notes).
- mime?: string — Content-Type for the object, set on the init request.
- headers?: Record<string, any> — extra headers for the init request.

progress semantics

Granularity is parts, not bytes: percentage is parts done ÷ total parts, so each callback advances by 1 / numParts. There is no byte-level progress inside a single part.
A failing part is retried once; progress fires only after the retry succeeds, once per part.
With a checkpoint, parts already listed in doneParts are skipped (not re-uploaded) but still count as done — the first callback already reflects the resumed portion.
The last callback reports 1 right before the upload is completed.

Return

Promise<CompleteMultipartUploadResult> — { name, etag, bucket?, res? }, the result of the completing call.

Resumable uploads (checkpoint)

Multipart uploads are resumable, but multipartUpload provides only the engine — it never persists state. Pass the same checkpoint back on a retry and it reuses the server-side session (uploadId), skips the parts already listed in doneParts, uploads only the gaps and completes as usual. Persisting the checkpoint, or dropping it when the file changes, is up to you: the progress callback hands you the up-to-date checkpoint after every part.

// Save the checkpoint as parts finish; keep `file` out of storage (a Blob
// cannot be serialized) and re-attach the current file when resuming.
function uploadWithResume(options, objectName, file) {
  const key = 'upload:' + objectName;
  const saved = JSON.parse(localStorage.getItem(key) || 'null');
  const checkpoint = saved && {
    file, // size must match the interrupted upload's file
    name: objectName,
    uploadId: saved.uploadId,
    partSize: saved.partSize,
    parts: [],
    doneParts: saved.doneParts,
  };
  return multipartUpload(options, objectName, file, {
    checkpoint,
    progress(percentage, cp) {
      localStorage.setItem(key, JSON.stringify({
        uploadId: cp.uploadId,
        partSize: cp.partSize,
        doneParts: cp.doneParts,
      }));
    },
  }).then((result) => {
    localStorage.removeItem(key);
    return result;
  });
}

Resume notes:

Resuming checks the file size only (checkpoint.file is compared by size). A different file with the same size is undetected — clear the saved checkpoint whenever the user picks another file.
partSize is taken from the checkpoint on resume; uploading with a different one would misalign part ranges and corrupt the final part list.
The server-side session is not kept forever: providers expire incomplete uploads on their own schedule, after which the saved uploadId is stale and the upload restarts from scratch.
Azure caveat: see the checkpoint argument above — its metadata lives in memory only, so a resumed upload loses it once the page reloads.

putSymlink(options, objectName, targetObjectName)

Create a symlink.

putSymlink(
  options: Options,
  objectName: string,
  targetObjectName: string
): Promise<any>

Arguments

options: Options — the client options, see above.
objectName: string — the symlink object name.
targetObjectName: string — the target object name.

Return

Promise<any>

signatureUrl(options, objectName, urlOptions)

Get a signature url to download the file.

signatureUrl(
  options: Options,
  objectName: string,
  urlOptions?: SignatureUrlOptions // { expires?: number; method?: HTTPMethods; response?: ResponseHeaderType }
): string

Arguments

options: Options — the client options, see above.
objectName: string — the object name.
urlOptions?: SignatureUrlOptions — optional signature options.
- expires?: number — the url expiry (unit: seconds), default is 1800.
- method?: HTTPMethods — the HTTP method, default is 'GET'.
- response?: ResponseHeaderType — response headers for download.

Return

string

LICENSE

MIT

Name		Name	Last commit message	Last commit date
.github		.github
.husky		.husky
docs/norms		docs/norms
example		example
scripts		scripts
skills		skills
src		src
test		test
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README_zh-CN.md		README_zh-CN.md
UPGRADING.md		UPGRADING.md
bump.config.ts		bump.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

tiny-oss

Table of Contents

Installation

Usage

Basic

Binding options once

Upload progress

Upload callback

Protocol

Compatibility

Non-browser environments

WeChat mini program upload

Custom transport

Progress events

Providers

AWS S3

S3-compatible stores (MinIO, Cloudflare R2, Google Cloud Storage, …)

Tencent Cloud COS

Huawei Cloud OBS

Volcano Engine TOS

Azure Blob Storage

Extension

Composing a custom provider

Contributing a provider to the repo

API

options

put(options, objectName, blob, putOptions)

Arguments

Return

multipartUpload(options, objectName, blob, multipartOptions)

Arguments

progress semantics

Return

Resumable uploads (checkpoint)

putSymlink(options, objectName, targetObjectName)

Arguments

Return

signatureUrl(options, objectName, urlOptions)

Arguments

Return

LICENSE

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages