Skip to content
foc Filecoin Onchain Cloud Documentation

StorageManagerUploadOptions

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

Upload options for StorageManager.upload() - the all-in-one upload method

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, callbacks?, metadata? } - uses the given contexts
  2. Auto-create contexts: { providerIds?, dataSetIds?, withCDN?, callbacks?, metadata? } - creates/reuses contexts
  3. Use default contexts: { callbacks?, metadata? } - uses cached default contexts

Example

Section titled “Example”
// Upload with specific providers
await storage.upload(data, { providerIds: [1n, 2n] })


// Upload with pre-created contexts
await storage.upload(data, { contexts: [ctx1, ctx2] })


// Upload with smart selection (default 2 copies)
await storage.upload(data)

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

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

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

count?

Section titled “count?”

optional count: number

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

Number of contexts to create.

  • When NEITHER dataSetIds nor providerIds are specified: controls smart selection
  • When explicit IDs are provided: if specified, must match the deduplicated array length

Default

Section titled “Default”
2 (only for smart selection)

Inherited from

Section titled “Inherited from”

CreateContextsOptions.count

dataSetIds?

Section titled “dataSetIds?”

optional dataSetIds: bigint[]

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

Specific data set IDs to use.

When provided:

  • Contexts are created for exactly these data sets (duplicates removed)
  • If count is specified, it must match the deduplicated length
  • Each data set must exist and belong to the current client
  • Each data set must belong to a unique provider (no duplicates)
  • Mutually exclusive with providerIds

Note: Bypasses smart selection. Endorsed provider prioritization and ordering logic are your responsibility when using explicit IDs.

Throws

Section titled “Throws”

If any data set does not exist or is not owned by client

Throws

Section titled “Throws”

If data sets resolve to duplicate providers

Throws

Section titled “Throws”

If combined with providerIds

Throws

Section titled “Throws”

If count does not match deduplicated array length

Inherited from

Section titled “Inherited from”

CreateContextsOptions.dataSetIds

excludeProviderIds?

Section titled “excludeProviderIds?”

optional excludeProviderIds: bigint[]

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

Internal

Provider IDs to exclude from smart selection.

Only applies when NEITHER dataSetIds nor providerIds are specified. Used internally by retry logic to avoid re-selecting failed providers.

Not recommended for general use

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

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

Inherited from

Section titled “Inherited from”

CreateContextsOptions.metadata

pieceCid?

Section titled “pieceCid?”

optional pieceCid: PieceLink

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

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

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

providerIds?

Section titled “providerIds?”

optional providerIds: bigint[]

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

Specific provider IDs to use.

When provided:

  • Contexts are created for exactly these providers (duplicates removed)
  • If count is specified, it must match the deduplicated length
  • Each provider must exist in the registry
  • Existing data sets matching metadata are reused when available
  • Mutually exclusive with dataSetIds

Note: Bypasses smart selection. Endorsed provider prioritization and ordering logic are your responsibility when using explicit IDs.

Throws

Section titled “Throws”

If any provider is not found in registry

Throws

Section titled “Throws”

If combined with dataSetIds

Throws

Section titled “Throws”

If count does not match deduplicated array length

Inherited from

Section titled “Inherited from”

CreateContextsOptions.providerIds

signal?

Section titled “signal?”

optional signal: AbortSignal

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

Optional AbortSignal to cancel the upload

withCDN?

Section titled “withCDN?”

optional withCDN: boolean

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

Whether to enable CDN services for the context

Inherited from

Section titled “Inherited from”

CreateContextsOptions.withCDN