Types - Upstash Documentation

The option and record types the rest of these docs refer to, and the upload phases named in error messages.

Size

maxSize: 4096       // 4,096 bytes
maxSize: "20MB"     // 20,000,000 bytes
maxSize: "32MiB"    // 33,554,432 bytes
multipart: "100MB"

A byte count, never a bit count. A bare number is bytes. String units ignore case, so MB and mb both mean megabytes.

Units	Base	Example
`B`, `KB`, `MB`, `GB`, `TB`	Decimal, powers of 1,000	`"32MB"` = 32,000,000 bytes
`KiB`, `MiB`, `GiB`, `TiB`	Binary, powers of 1,024	`"32MiB"` = 33,554,432 bytes

For a 32 MiB file limit, use "32MiB" or 33_554_432. A "32MB" limit is smaller and rejects that file. Existing decimal units keep their values. Bit units such as mbit and Mbps are not supported. An unparseable size throws a TypeError where the option is written, not per request. A limit you write by hand takes a Size: maxSize, multipart. A measurement you forward is a plain number of bytes: the size option on put, and every size the SDK returns. That mirrors File.size and Blob.size, so a value flows from one to the other without conversion. formatBytes, exported from all three entrypoints, always displays decimal byte units, including values supplied as MiB: formatBytes(2_400_000) is 2.4 MB.

Duration

expiresIn: 900       // 15 minutes
expiresIn: "15m"
olderThan: "7d"
cache: "1h"

A span of time. A bare number is seconds; a string takes a unit: ms, s, m, h, d, or a long form (sec, seconds, min, minutes, hr, hours, day, days). A string with no unit is seconds. An unparseable duration throws a TypeError naming the option.

CacheOption

cache: "immutable"
cache: "revalidate"
cache: "no-store"
cache: "15m"
cache: "public, max-age=60, s-maxage=31536000"

One of three words, a Duration, or a raw Cache-Control header. The header each one stores is on Caching.

Records

Four record shapes come back from the SDK. They nest.

Type	Fields	Returned by
`BlobObject`	`path`, `url?`, `versionedUrl?`, `size`, `etag`, `uploadedAt`	`list()`, `copy()`, `move()`, `updateJson()`
`CompletedBlob`	`BlobObject` plus `contentType`	`put()`, `onUploadComplete`, a finished browser upload
`BlobInfo`	`BlobObject` plus `contentType` and `metadata`	`info()`
`BlobDownload`	`BlobInfo` plus `body: ReadableStream<Uint8Array>`	`get()`

BlobObject fields:

Field	Type	Description
`path`	`string`	The object’s key.
`url`	`string \| undefined`	The public object URL. `undefined` on a private bucket.
`versionedUrl`	`string \| undefined`	`${url}?v=${etag}`, etag percent-encoded. `undefined` when `url` is.
`size`	`number`	Bytes.
`etag`	`string`	Storage’s etag, quoted: `"9f3c..."`.
`uploadedAt`	`Date`	Last modified.

Across the SDK, blob names a record, never the bytes. Bytes go in and come out as body.

Upload phases

A direct browser upload makes up to four kinds of request to your upload route. The names appear in error messages and across these docs.

Phase	When	What your route does
`begin`	First request, once	Checks constraints, runs `onBeforeUpload`, signs the first URL(s). Never retried.
`parts`	Multipart only, as needed	Signs the next batch of part URLs.
`end`	Once the bytes landed	Completes the upload, runs `onUploadComplete`. Retried by the browser on failure.
`cancel`	On `cancel()`	Aborts the multipart upload, or deletes the single-PUT object.

The PUTs that carry the bytes go to storage, never to your route. How signing works has the full handshake.

​Size

​Duration

​CacheOption

​Records

​Upload phases

Size

Duration

CacheOption

Records

Upload phases