Skip to content
foc Filecoin Onchain Cloud Documentation

StorageManagerUploadOptions

Defined in: packages/synapse-sdk/src/storage/manager.ts:114

Upload options for StorageManager.upload()

Extends CreateContextsOptions to inherit multi-copy provider selection. Adds upload-specific options: explicit contexts, pre-calculated PieceCID, and abort signal.

Usage patterns:

  1. With explicit contexts: { contexts } - uses the given contexts directly
  2. Auto-create contexts: { providerIds?, dataSetIds?, copies? } - creates/reuses contexts
  3. Use default contexts: no options - uses cached default contexts (2 copies)

Extends

Section titled “Extends”

Properties

Section titled “Properties”

callbacks?

Section titled “callbacks?”

optional callbacks?: Partial<CombinedCallbacks>

Defined in: packages/synapse-sdk/src/storage/manager.ts:119

Callbacks for both context creation and upload lifecycle

Overrides

Section titled “Overrides”

CreateContextsOptions.callbacks

contexts?

Section titled “contexts?”

optional contexts?: StorageContext[]

Defined in: packages/synapse-sdk/src/storage/manager.ts:116

Pre-created contexts to use. If provided, other selection options are invalid.

copies?

Section titled “copies?”

optional copies?: number

Defined in: packages/synapse-sdk/src/types.ts:361

Number of storage copies to create (optional, defaults to 2)

Inherited from

Section titled “Inherited from”

CreateContextsOptions.copies

dataSetIds?

Section titled “dataSetIds?”

optional dataSetIds?: bigint[]

Defined in: packages/synapse-sdk/src/types.ts:371

Specific data set IDs to target. Each must be an active data set owned by the caller. Mutually exclusive with providerIds.

Use this only when resuming into a known data set from a prior operation. For first-time uploads to specific providers, use providerIds instead, the SDK handles data set creation automatically.

Inherited from

Section titled “Inherited from”

CreateContextsOptions.dataSetIds

excludeProviderIds?

Section titled “excludeProviderIds?”

optional excludeProviderIds?: bigint[]

Defined in: packages/synapse-sdk/src/types.ts:389

Do not select any of these providers

Inherited from

Section titled “Inherited from”

CreateContextsOptions.excludeProviderIds

metadata?

Section titled “metadata?”

optional metadata?: Record<string, string>

Defined in: packages/synapse-sdk/src/types.ts:342

Custom metadata for data sets (key-value pairs). Used to match existing data sets during provider selection.

Inherited from

Section titled “Inherited from”

CreateContextsOptions.metadata

pieceCid?

Section titled “pieceCid?”

optional pieceCid?: PieceCID

Defined in: packages/synapse-sdk/src/storage/manager.ts:122

Optional pre-calculated PieceCID to skip CommP calculation (verified by server)

pieceMetadata?

Section titled “pieceMetadata?”

optional pieceMetadata?: Record<string, string>

Defined in: packages/synapse-sdk/src/storage/manager.ts:128

Custom metadata for pieces being uploaded (key-value pairs)

providerIds?

Section titled “providerIds?”

optional providerIds?: bigint[]

Defined in: packages/synapse-sdk/src/types.ts:386

Specific provider IDs to upload to. The SDK resolves or creates data sets on each provider automatically. Mutually exclusive with dataSetIds.

This is the recommended way to target specific providers. Do not call createContext() to resolve data sets first, pass provider IDs here and the SDK handles the rest.

Example

Section titled “Example”

Upload to two specific providers

await synapse.storage.upload(data, { providerIds: [4n, 9n] })

Inherited from

Section titled “Inherited from”

CreateContextsOptions.providerIds

signal?

Section titled “signal?”

optional signal?: AbortSignal

Defined in: packages/synapse-sdk/src/storage/manager.ts:125

Optional AbortSignal to cancel the upload

withCDN?

Section titled “withCDN?”

optional withCDN?: boolean

Defined in: packages/synapse-sdk/src/types.ts:336

Whether to enable CDN services

Inherited from

Section titled “Inherited from”

CreateContextsOptions.withCDN