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:238

createWriteStream

createWriteStream(
    options?: {
        concurrency?: number;
        contentType?: string;
        fileInfo?: Record<string, string>;
        onProgress?: ProgressListener;
        partSize?: number;
        serverSideEncryption?: EncryptionSetting;
        signal?: AbortSignal;
    },
): 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: {
      concurrency?: number;
      contentType?: string;
      fileInfo?: Record<string, string>;
      onProgress?: ProgressListener;
      partSize?: number;
      serverSideEncryption?: EncryptionSetting;
      signal?: AbortSignal;
  }
  Streaming upload parameters (part size, concurrency, encryption).
  - Optionalconcurrency?: number
    Maximum number of parts uploaded in parallel. Defaults to 4.
  - OptionalcontentType?: string
    MIME type. Defaults to b2/x-auto.
  - OptionalfileInfo?: Record<string, string>
    Custom key-value metadata stored with the file.
  - OptionalonProgress?: ProgressListener
    Callback invoked with upload progress events.
  - OptionalpartSize?: number
    Target part size in bytes. Defaults to the account's recommended part size.
  - OptionalserverSideEncryption?: EncryptionSetting
    Server-side encryption applied to each part.
  - Optionalsignal?: AbortSignal
    Abort signal that cancels the upload and the unfinished large file.
Returns UploadWriteHandle
A handle with the writable sink and a completion promise.
- Defined in object.ts:270

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:320

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:170

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:205

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:299

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:189

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:223

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:312

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:362

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:341

upload

upload(
    options: {
        concurrency?: number;
        contentType?: string;
        fileInfo?: Record<string, string>;
        fileRetention?: FileRetentionValue;
        lastModifiedMillis?: number;
        legalHold?: LegalHoldValue;
        onProgress?: ProgressListener;
        partSize?: number;
        resume?: boolean;
        resumeFileId?: LargeFileId;
        serverSideEncryption?: EncryptionSetting;
        signal?: AbortSignal;
        source: ContentSource;
    },
): Promise<FileVersion>
Uploads data to this file name. Automatically uses multipart upload for large files.
Parameters
- options: {
      concurrency?: number;
      contentType?: string;
      fileInfo?: Record<string, string>;
      fileRetention?: FileRetentionValue;
      lastModifiedMillis?: number;
      legalHold?: LegalHoldValue;
      onProgress?: ProgressListener;
      partSize?: number;
      resume?: boolean;
      resumeFileId?: LargeFileId;
      serverSideEncryption?: EncryptionSetting;
      signal?: AbortSignal;
      source: ContentSource;
  }
  Upload configuration including data source and optional settings.
  - Optionalconcurrency?: number
    Number of concurrent part uploads for large files.
  - OptionalcontentType?: string
    MIME type. Defaults to auto-detection by B2.
  - OptionalfileInfo?: Record<string, string>
    Custom key-value metadata stored with the file.
  - OptionalfileRetention?: FileRetentionValue
    File retention policy (requires file lock).
  - OptionallastModifiedMillis?: number
    Last-modified timestamp in milliseconds since epoch.
  - OptionallegalHold?: LegalHoldValue
    Legal hold status.
  - OptionalonProgress?: ProgressListener
    Callback invoked with upload progress events.
  - OptionalpartSize?: number
    Part size override for multipart uploads, in bytes.
  - Optionalresume?: boolean
    Resume an unfinished multipart upload for this file name when one exists. Only meaningful on the large-file path. Ignored on the small-file path.
  - OptionalresumeFileId?: LargeFileId
    Resume into a specific large-file ID, bypassing discovery. Overrides the resume discovery path.
  - OptionalserverSideEncryption?: EncryptionSetting
    Server-side encryption settings.
  - Optionalsignal?: AbortSignal
    Abort signal for cancelling the upload.
  - source: ContentSource
    Data source to upload.
Returns Promise<FileVersion>
Metadata for the uploaded file version.
- Defined in object.ts:108

Class B2Object

Example

Index

Properties

Methods

Properties

ReadonlyfileName

Methods

createReadStream

Parameters

Optionalconcurrency?: number

OptionalrangeSize?: number

Optionalsignal?: AbortSignal

Returns ReadableStream<Uint8Array<ArrayBufferLike>>

createWriteStream

Parameters

Optionalconcurrency?: number

OptionalcontentType?: string

OptionalfileInfo?: Record<string, string>

OptionalonProgress?: ProgressListener

OptionalpartSize?: number

OptionalserverSideEncryption?: EncryptionSetting

Optionalsignal?: AbortSignal

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

Optionalconcurrency?: number

OptionalcontentType?: string

OptionalfileInfo?: Record<string, string>

OptionalfileRetention?: FileRetentionValue

OptionallastModifiedMillis?: number

OptionallegalHold?: LegalHoldValue

OptionalonProgress?: ProgressListener

OptionalpartSize?: number

Optionalresume?: boolean

OptionalresumeFileId?: LargeFileId

OptionalserverSideEncryption?: EncryptionSetting

Optionalsignal?: AbortSignal

source: ContentSource

Returns Promise<FileVersion>

Settings

On This Page

`Readonly`fileName

`Optional`concurrency?: number

`Optional`rangeSize?: number

`Optional`signal?: AbortSignal

`Optional`concurrency?: number

`Optional`contentType?: string

`Optional`fileInfo?: Record<string, string>

`Optional`onProgress?: ProgressListener

`Optional`partSize?: number

`Optional`serverSideEncryption?: EncryptionSetting

`Optional`signal?: AbortSignal

`Optional`concurrency?: number

`Optional`contentType?: string

`Optional`fileInfo?: Record<string, string>

`Optional`fileRetention?: FileRetentionValue

`Optional`lastModifiedMillis?: number

`Optional`legalHold?: LegalHoldValue

`Optional`onProgress?: ProgressListener

`Optional`partSize?: number

`Optional`resume?: boolean

`Optional`resumeFileId?: LargeFileId

`Optional`serverSideEncryption?: EncryptionSetting

`Optional`signal?: AbortSignal