Class B2Object

Handle to a specific file (by name) within a B2 bucket.

Provides file-scoped upload, download, and management operations. Obtained via Bucket.file.

Example

const obj = bucket.file('photos/2026/sunset.jpg')
await obj.upload({ source: new BufferSource(data) })
const result = await obj.download()

Index

Properties

fileName

Methods

createReadStream createWriteStream deleteVersion download downloadById getFileInfo head headById hide setLegalHold setRetention upload

Properties

`Readonly`fileName

fileName: string

The file name (path) within the bucket.

Methods

createReadStream

createReadStream(
    fileId: FileId,
    totalSize: number,
    options?: {
        concurrency?: number;
        rangeSize?: number;
        signal?: AbortSignal;
    },
): ReadableStream<Uint8Array<ArrayBufferLike>>
Creates a parallel-download ReadableStream that fetches the file in concurrent ranged chunks.
Parameters
- fileId: FileId
  The file version ID to download.
- totalSize: number
  Total file size in bytes (needed to compute range boundaries).
- Optionaloptions: { concurrency?: number; rangeSize?: number; signal?: AbortSignal }
  Concurrency, range size, and abort signal.
  - Optionalconcurrency?: number
    Number of concurrent range requests. Defaults to 4.
  - OptionalrangeSize?: number
    Size of each ranged GET request in bytes. Defaults to 8 MB.
  - Optionalsignal?: AbortSignal
    Abort signal for cancelling the download.
Returns ReadableStream<Uint8Array<ArrayBufferLike>>
A Web ReadableStream of file data in sequential order.
- Defined in object.ts:257

createWriteStream

createWriteStream(options?: B2ObjectWriteStreamOptions): UploadWriteHandle
Creates a Web WritableStream that uploads streamed data into this file using the multipart protocol. Pipe a ReadableStream<Uint8Array> into the returned writable and await done to get the final FileVersion.

Note: streaming uploads do not support resume because the size and per-part hashes are not known in advance. Use upload with a buffered source when resume is required.
Parameters
- Optionaloptions: B2ObjectWriteStreamOptions
  Streaming upload parameters (part size, concurrency, encryption).
Returns UploadWriteHandle
A handle with the writable sink and a completion promise.
- Defined in object.ts:289

deleteVersion

deleteVersion(fileId: FileId): Promise<void>
Permanently deletes a specific version of this file.
Parameters
- fileId: FileId
  The unique identifier of the file version to delete.
Returns Promise<void>
- Defined in object.ts:326

download

download(options?: DownloadCallOptions): Promise<DownloadResult>
Downloads this file by name. Pass method: 'HEAD' to fetch only the response headers (file metadata) without streaming the body.
Parameters
- Optionaloptions: DownloadCallOptions
  Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
Returns Promise<DownloadResult>
The download result with response headers and body stream.
- Defined in object.ts:189

downloadById

downloadById(
fileId: FileId,
options?: DownloadCallOptions,
): Promise<DownloadResult>
Downloads a specific version of this file by ID. Pass method: 'HEAD' to fetch only the response headers (file metadata) without streaming the body.
Parameters
- fileId: FileId
  The file version ID to download.
- Optionaloptions: DownloadCallOptions
  Optional method, range, SSE-C decryption, response-header overrides, and abort signal.
Returns Promise<DownloadResult>
The download result with response headers and body stream.
- Defined in object.ts:224

getFileInfo

getFileInfo(fileId: FileId): Promise<FileVersion>
Retrieves metadata for a specific file version.
Parameters
- fileId: FileId
  The file version ID to look up.
Returns Promise<FileVersion>
The file version metadata.
- Defined in object.ts:305

head

head(options?: HeadCallOptions): Promise<HeadResult>
Fetches response headers for this file via HTTP HEAD. Returns a body-less result so callers never have to drain the (logically empty) HEAD body themselves.
Parameters
- Optionaloptions: HeadCallOptions
  Optional range, SSE-C decryption, response-header overrides, and abort signal. Same shape as B2Object.download's options minus method (always HEAD) and onProgress (no body).
Returns Promise<HeadResult>
Parsed download headers (content type, SHA-1, file info, etc.).
- Defined in object.ts:208

headById

headById(fileId: FileId, options?: HeadCallOptions): Promise<HeadResult>
Fetches response headers for a specific version of this file by ID via HTTP HEAD. Returns a body-less result so callers never have to drain the (logically empty) HEAD body themselves.
Parameters
- fileId: FileId
  The file version ID to inspect.
- Optionaloptions: HeadCallOptions
  Optional range, SSE-C decryption, response-header overrides, and abort signal.
Returns Promise<HeadResult>
Parsed download headers.
- Defined in object.ts:242

hide

hide(): Promise<FileVersion>
Hides this file by creating a hide marker at this file name.

Returns Promise<FileVersion>
Metadata for the newly created hide marker.
- Defined in object.ts:318

setLegalHold

setLegalHold(
fileId: FileId,
legalHold: LegalHoldValue,
): Promise<UpdateFileLegalHoldResponse>
Toggles the legal hold flag on a specific file version of this file.

Legal hold is independent of retention: a file can be on legal hold without any retention policy, and vice versa. The bucket must have Object Lock enabled, and any caller must hold the writeFileLegalHolds capability.
Parameters
- fileId: FileId
  The file version to apply the flag to.
- legalHold: LegalHoldValue
  'on' to apply the hold, 'off' to remove it.
Returns Promise<UpdateFileLegalHoldResponse>
Metadata for the updated file version.
- Defined in object.ts:368

setRetention

setRetention(
    fileId: FileId,
    retention: FileRetentionValue,
    options?: { bypassGovernance?: boolean },
): Promise<UpdateFileRetentionResponse>
Sets or updates the Object Lock retention policy on a specific file version of this file.

The bucket must have Object Lock enabled (fileLockEnabled: true at creation time). Governance-mode retention can be shortened or removed by passing bypassGovernance: true together with an application key that carries the bypassGovernance capability; compliance-mode retention cannot be shortened by anyone until the retainUntilTimestamp elapses.
Parameters
- fileId: FileId
  The file version to apply the policy to.
- retention: FileRetentionValue
  The retention policy to apply.
- Optionaloptions: { bypassGovernance?: boolean }
  Optional flag for shortening governance-mode retention.
Returns Promise<UpdateFileRetentionResponse>
Metadata for the updated file version.
- Defined in object.ts:347

upload

upload(options: HighLevelUploadOptions): Promise<FileVersion>
Uploads data to this file name. Automatically uses multipart upload for large files.
Parameters
- options: HighLevelUploadOptions
  Upload configuration including data source and optional settings.
Returns Promise<FileVersion>
Metadata for the uploaded file version.
- Defined in object.ts:143

Class B2Object

Example

Index

Properties

Methods

Properties

ReadonlyfileName

Methods

createReadStream

Parameters

Optionalconcurrency?: number

OptionalrangeSize?: number

Optionalsignal?: AbortSignal

Returns ReadableStream<Uint8Array<ArrayBufferLike>>

createWriteStream

Parameters

Returns UploadWriteHandle

deleteVersion

Parameters

Returns Promise<void>

download

Parameters

Returns Promise<DownloadResult>

downloadById

Parameters

Returns Promise<DownloadResult>

getFileInfo

Parameters

Returns Promise<FileVersion>

head

Parameters

Returns Promise<HeadResult>

headById

Parameters

Returns Promise<HeadResult>

hide

Returns Promise<FileVersion>

setLegalHold

Parameters

Returns Promise<UpdateFileLegalHoldResponse>

setRetention

Parameters

Returns Promise<UpdateFileRetentionResponse>

upload

Parameters

Returns Promise<FileVersion>

Settings

On This Page

`Readonly`fileName

`Optional`concurrency?: number

`Optional`rangeSize?: number

`Optional`signal?: AbortSignal