Every public method of RadonStorage, its options and return type, plus configuration, upload input, URL options, list options, and the result shapes — exhaustively.

The complete public surface of @radonsdk/storage. Import the client and any types you need:

import { RadonStorage, createStorage } from "@radonsdk/storage";

Constructor

new RadonStorage(config: RadonStorageConfig)

Create a client. createStorage(config) is an equivalent factory. Providers are lazy-loaded on first use; the constructor only validates config shape (it throws InvalidConfigError if providers is empty or a failover/defaultProvider slug isn't configured).

RadonStorageConfig

providersPartial<Record<string, ProviderOptions>>required

Which providers to enable, keyed by slug (s3, r2, local, supabase, …). The value is that provider's options; use {} to rely entirely on RADON_<SLUG>_* env vars. At least one is required.

mode"test" | "live"default: "test"

Hints sandbox vs. production to providers that distinguish them. Most object stores ignore it.

defaultProviderstring

The provider used when a call names none. Defaults to the sole configured provider, the head of the failover chain, or throws if several are configured without one.

failoverstring[]Pro

An ordered chain of provider slugs; operations try each until one succeeds. Each slug must also be in providers. Pro feature.

licenseKeystring

Radon Pro license key. Required for any Pro provider or feature. Falls back to RADON_LICENSE_KEY.

licenseLicenseConfig

Advanced license config: { key?, verifyUrl?, watermark?, fetch? }.

fetchtypeof fetch

Injectable fetch (proxies, instrumentation, tests). Defaults to global fetch.

now() => Date

Injectable clock (deterministic SigV4 timestamps in tests). Defaults to () => new Date().

ProviderOptions

Every field is optional — credentials default to RADON_<SLUG>_* env vars. Unknown keys are ignored (or read by that specific adapter).

bucketstring

The bucket / container / storage-zone name.

regionstring

Region, for region-scoped providers (the S3 family).

endpointstring

Custom endpoint / base URL override (S3-compatible or self-hosted stores).

publicUrlstring

Base URL for building public object URLs (a CDN domain, custom domain, …).

Provider-specific keys (accessKeyId, secretAccessKey, accountId, serviceKey, namespace, tokenKey, resourceType, …) also go here — see Providers.

Lifecycle

storage.init(): Promise<void>

Verify the Pro license (if required), then eagerly load and initialize every configured provider. Call at boot to fail fast. Throws LicenseRequiredError if a Pro provider/feature is configured without a key, or LicenseInvalidError if verification fails (fail-closed). Free-only setups may skip it.

storage.provider(slug?: string): Promise<StorageProvider>

Lazy-load, construct, and cache a configured provider by slug (default when omitted). Throws ProviderNotConfiguredError if it wasn't enabled, or LicenseRequiredError if it's Pro and the license hasn't been verified.

storage.native(slug?: string): Promise<unknown>

The provider's underlying native client — its low-level signer/HTTP client and resolved endpoint config — for anything the unified API doesn't cover. Shape is per-provider (the S3 family returns { provider, settings, signer, http, objectUrl }).

Getters

configuredProvidersstring[]

Slugs of every configured provider (lowercased).

defaultProviderstring

The provider used when a call names none. Throws if ambiguous.

isLicensedboolean

Whether a valid Pro license was confirmed in init().

Core operations

Every operation accepts an optional trailing OperationOptions — { provider?: string } — to target one provider for that call.

storage.upload(input: UploadInput, options?): Promise<UploadResult>

Store an object from bytes/stream/text (body) or a local file (path). Fails over across the chain when one is configured.

storage.download(key: string, options?): Promise<Buffer>

Download an object's bytes into memory. Throws ObjectNotFoundError if absent.

storage.delete(key: string, options?): Promise<void>

Delete an object by key. A no-op (not an error) if the key doesn't exist.

storage.exists(key: string, options?): Promise<boolean>

Whether an object exists at key. Never throws for a missing object.

storage.getMetadata(key: string, options?): Promise<ObjectMetadata>

Fetch an object's metadata. Throws ObjectNotFoundError if absent.

storage.getUrl(key: string, options?: GetUrlOptions & OperationOptions): Promise<string>

Build a public or signed URL for key. Uses the primary provider only — never fails over. May resolve synchronously or asynchronously depending on the provider (typed as a Promise).

storage.list(prefix?: string, options?: ListOptions & OperationOptions): Promise<ListResult>

List objects under prefix, paginated. Uses the primary provider only — never fails over.

storage.copy(sourceKey: string, destKey: string, options?): Promise<UploadResult>

Copy an object server-side (no byte round-trip). Throws UnsupportedOperationError on providers without a copy API.

Resumable / multipart (Pro)

All five require a verified license (await storage.init()), even on a free provider — chunked upload is itself a Pro feature.

storage.uploadResumable(input: UploadInput, options?: ResumableUploadOptions): Promise<UploadResult>Pro

Upload a large object in parts, aborting on failure. Objects smaller than one partSize fall back to a single upload(). Options extend OperationOptions with partSize (bytes, default 8 MiB / 8388608).

storage.createMultipartUpload(key: string, options?: MultipartUploadOptions & OperationOptions): Promise<MultipartUpload>

Pro

Begin a multipart upload; returns a handle to feed the other multipart calls.

storage.uploadPart(upload: MultipartUpload, partNumber: number, body: UploadBody): Promise<UploadedPart>Pro

Upload one part (1-based partNumber). The returned part is collected for completion.

storage.completeMultipartUpload(upload: MultipartUpload, parts: UploadedPart[]): Promise<UploadResult>Pro

Complete a multipart upload, assembling its parts (Radon orders them by partNumber).

storage.abortMultipartUpload(upload: MultipartUpload): Promise<void>Pro

Abort a multipart upload, discarding uploaded parts. A no-op on Azure (blocks are auto-collected).

Input & option types

UploadInput

keystringrequired

Destination object key. Leading slashes are trimmed.

bodyBuffer | Uint8Array | Readable | string

In-memory bytes, a Node stream, or UTF-8 text. Mutually exclusive with path.

pathstring

A local filesystem path to upload from. Mutually exclusive with body.

contentTypestring

MIME type. Inferred from the key/path extension when omitted.

contentLengthnumber

Byte length when known ahead of time (lets streaming uploads set Content-Length).

cacheControlstring

Cache-Control header stored with the object.

contentDispositionstring

Content-Disposition header stored with the object.

acl"private" | "public-read"default: "private"

Canned visibility. Providers map it to their nearest equivalent.

metadataRecord<string, string>

Arbitrary user metadata persisted with the object.

providerOptionsRecord<string, unknown>

Escape hatch for provider-specific request fields. Ties the call to one provider.

GetUrlOptions

signedbooleandefault: false

Return a signed, time-limited URL for a private object. Providers without public URLs always sign.

expiresInnumberdefault: 3600

Signed-URL lifetime in seconds. Ignored for public URLs. The S3 family caps this at 604800 (7 days).

method"GET" | "PUT"default: "GET"

The HTTP method the signed URL authorizes. PUT mints a presigned upload URL and implies signed: true.

downloadboolean | string

Force a download. true uses the object's own filename; a string sets a custom one (via response-content-disposition).

responseContentTypestring

Override the response Content-Type on the signed URL, where supported.

providerOptionsRecord<string, unknown>

Provider-specific escape hatch merged into URL generation.

ListOptions

limitnumber

Max objects per page. Providers cap this (S3 at 1000).

cursorstring

Continuation token from a previous ListResult.cursor.

delimiterstring

Group keys up to this character into prefixes ("folders") instead of returning every key.

ResumableUploadOptions

partSizenumberdefault: 8388608

Bytes per part (default 8 MiB). S3-family stores require non-final parts to be at least 5 MiB.

providerstring

Target a specific provider (from OperationOptions).

MultipartUploadOptions

contentType, cacheControl, contentDisposition, acl, metadata, and providerOptions — the same subset of UploadInput that applies when starting a multipart upload.

Result types

UploadResult

keystring

The stored object key.

providerstring

Which provider stored it.

sizenumber | undefined

Bytes stored, when reported.

etagstring | undefined

The entity tag.

contentTypestring | undefined

The stored content type.

versionIdstring | undefined

Version id, on versioned buckets.

urlstring | undefined

A public URL when determinable without signing.

metadataRecord<string, string>

User metadata, echoed back.

rawunknown

The untouched provider response.

ObjectMetadata

keystring

sizenumber

Size in bytes.

contentTypestring | undefined

etagstring | undefined

lastModifiedDate | undefined

cacheControlstring | undefined

contentDispositionstring | undefined

versionIdstring | undefined

metadataRecord<string, string>

User metadata.

rawunknown

The untouched provider response.

ListResult

objectsObjectSummary[]

The objects in this page.

prefixesstring[]

Common prefixes ("folders"), when a delimiter was passed.

cursorstring | undefined

Continuation token; pass back as options.cursor.

hasMoreboolean

Whether more objects exist beyond this page.

ObjectSummary

keystring

sizenumber

etagstring | undefined

lastModifiedDate | undefined

MultipartUpload

keystring

The object key being assembled.

uploadIdstring

The provider's upload id for this session.

providerstring

Which provider owns the session.

rawunknown | undefined

Provider-specific state carried between calls.

UploadedPart

partNumbernumber

1-based part number.

etagstring

The part's entity tag, required to complete.

sizenumber | undefined

Size of this part in bytes.

Tier introspection

FREE_PROVIDERSReadonlySet<string>

The free provider slugs: s3, r2, local.

isProProvider(slug: string) => boolean

Whether a slug is Pro-gated (anything not in FREE_PROVIDERS).

PRO_FEATURES{ resumable: string; failover: string }

The Pro-only feature identifiers: "resumable-upload" and "multi-provider-failover".

Extending Radon

For a bring-your-own provider (Pro-gated), implement the StorageProvider interface — or extend BaseProvider, or S3CompatibleProvider for an S3-compatible store — and register it:

import { S3CompatibleProvider, registerProvider } from "@radonsdk/storage";

class MyS3Provider extends S3CompatibleProvider {
  readonly name = "my-s3";
  protected readonly defaultRegion = "us-east-1";
  protected endpointFor({ region, bucket, customEndpoint }) {
    return { baseUrl: `${customEndpoint}/${bucket}`, region };
  }
}

registerProvider("my-s3", async () => MyS3Provider);

Also exported for building against raw provider APIs: SigV4Signer, HttpClient, the signature helpers (hmac, sha256Hex, safeEqual), XML readers (xmlText, xmlBlocks), registerProvider / hasProvider / knownProviders, LicenseClient, and runFailover. All types are exported.

API reference

Constructor

RadonStorageConfig

ProviderOptions

Lifecycle

Getters

Core operations

Resumable / multipart (Pro)

Input & option types

UploadInput

GetUrlOptions

ListOptions

ResumableUploadOptions

MultipartUploadOptions

Result types

UploadResult

ObjectMetadata

ListResult

ObjectSummary

MultipartUpload

UploadedPart

Tier introspection

Extending Radon

On this page