Class SendTransfer

A file transfer in the sending direction.

Announces the file to the receiver with an offer control message, then — once accepted — reads the source in SendTransferParams.chunkSize chunks and streams them as framed binary messages across one or more data channels. Chunks are striped round-robin across the channels, backpressure is applied via each channel's bufferedAmount (see the high/low water marks), and when checksums are enabled a SHA-256 digest is computed over the file and sent so the receiver can verify integrity. Supports pause/resume and cancellation, and honours a receiver's resume request by resending only the chunks it is missing.

Remarks

Instances are created and started by FileTransferManager.sendFile; construct via the manager rather than directly.

Example

const transfer = manager.sendFile(peerId, file)
transfer.on('progress', (p) => console.log(`${Math.round(p.ratio * 100)}%`))
transfer.on('complete', () => console.log('sent'))
transfer.on('error', (err) => console.error(err.code, err.message))

Hierarchy (View Summary)

Transfer
- SendTransfer

Index

Constructors

constructor

new SendTransfer(params: SendTransferParams): SendTransfer
Parameters
- params: SendTransferParams
  Fully-resolved send parameters; see SendTransferParams.
Returns SendTransfer
Overrides Transfer.constructor
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:92

Properties

`Protected`_state

_state: TransferState = TransferState.Idle

Current lifecycle state.

`Protected`_transferredBytes

_transferredBytes: number = 0

Bytes transferred so far.

`Protected`_transferredChunks

_transferredChunks: number = 0

Chunks transferred so far.

`Protected` `Readonly`chunkSize

chunkSize: number

Payload bytes per chunk.

`Readonly`direction

direction: "send" = TransferDirection.Send

Always TransferDirection.Send.

`Readonly`id

id: string

Unique identifier shared by both peers for this transfer.

`Readonly`metadata

metadata: FileMetadata

Name, MIME type, and size of the file being transferred.

`Readonly`peerId

peerId: string

Identifier of the remote peer participating in this transfer.

`Protected` `Readonly`totalChunks

totalChunks: number

Total number of chunks the file is divided into.

Accessors

channelCount

get channelCount(): number
Number of parallel data channels this transfer streams over.

Returns number
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:117

interrupted

get interrupted(): boolean
Whether this transfer is paused awaiting a SendTransfer.reoffer after a channel drop.

Returns boolean
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:122

isTerminal

get isTerminal(): boolean
true once the transfer has reached a terminal state (completed, failed, or cancelled).

Returns boolean
Inherited from Transfer.isTerminal
- Defined in packages/sdk/src/filetransfer/Transfer.ts:107

state

get state(): TransferState
The current lifecycle state of the transfer.

Returns TransferState
Inherited from Transfer.state
- Defined in packages/sdk/src/filetransfer/Transfer.ts:102

Methods

`Protected`_notifyRemoteFailure

_notifyRemoteFailure(error: FileTransferError): void
Hook invoked by Transfer.fail when a local failure must be signalled to the remote peer. Overridden by the concrete subclasses to send a cancel over the control channel; a no-op by default.
Parameters
- error: FileTransferError
Returns void
Overrides Transfer._notifyRemoteFailure
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:171

`Protected`_onTerminal

_onTerminal(): void
Hook invoked once when the transfer first reaches a terminal state (completed/failed/cancelled). Subclasses override it to release resources — close per-transfer data channels, drain any suspended workers, clear timers.

Returns void
Overrides Transfer._onTerminal
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:175

cancel

cancel(reason?: string): void
Cancels the transfer, sending a cancel control message to the receiver and closing the source. No-op if the transfer is already terminal.
Parameters
- Optionalreason: string
  Optional reason; when provided, surfaced via TransferEvent.Error.
Returns void
Overrides Transfer.cancel
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:328

emit

emit<K extends keyof TransferEvents>(
event: K,
...args: TransferEvents[K],
): boolean
Synchronously invokes every listener registered for event, in registration order.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to emit.
- ...args: TransferEvents[K]
  The argument tuple to pass to each listener, matching Events[event].
Returns boolean
true if at least one listener was invoked, false if there were none.

Remarks
The listener list is snapshotted before dispatch, so mutations made by handlers take effect only on subsequent emissions. Listeners are isolated: if one throws, the remaining listeners still run and the error is surfaced via console.error rather than swallowed silently (consistent with LocalMessageBus).
Inherited from Transfer.emit
- Defined in packages/core/src/EventEmitter.ts:95

`Protected`emitProgress

emitProgress(): void
Emits a TransferEvent.Progress event with the current snapshot.

Returns void
Inherited from Transfer.emitProgress
- Defined in packages/sdk/src/filetransfer/Transfer.ts:136

`Protected`fail

fail(error: FileTransferError, notifyRemote?: boolean): FileTransferError
Transitions the transfer to TransferState.Failed and emits TransferEvent.Error. No-op if the transfer is already terminal.
Parameters
- error: FileTransferError
  The error describing the failure.
- notifyRemote: boolean = false
Returns FileTransferError
The same error, for convenient throw/return chaining.
Inherited from Transfer.fail
- Defined in packages/sdk/src/filetransfer/Transfer.ts:177

handleControl

handleControl(
    msg:
        | {
            checksum: boolean;
            chunkSize: number;
            mimeType: string;
            name: string;
            parallelChannels: number;
            size: number;
            totalChunks: number;
            transferId: string;
            type: "ft-offer";
            version?: number;
        }
        | { haveChunks?: number[]; transferId: string; type: "ft-accept" }
        | { reason?: string; transferId: string; type: "ft-reject" }
        | { haveChunks: number[]; transferId: string; type: "ft-resume-request" }
        | { digest?: string; transferId: string; type: "ft-sent" }
        | { transferId: string; type: "ft-complete" }
        | { transferId: string; type: "ft-checksum-mismatch" }
        | { reason?: string; transferId: string; type: "ft-cancel" }
        | { transferId: string; type: "ft-pause" }
        | { transferId: string; type: "ft-resume" },
): void
Processes an inbound control message from the receiver, driving the send state machine: accept/resume-request begin streaming (the latter resending only the receiver's missing chunks), reject/checksum-mismatch fail the transfer, complete finalizes it, and pause/resume/cancel are applied. Routed here by FileTransferManager.
Parameters
- msg:
      | {
          checksum: boolean;
          chunkSize: number;
          mimeType: string;
          name: string;
          parallelChannels: number;
          size: number;
          totalChunks: number;
          transferId: string;
          type: "ft-offer";
          version?: number;
      }
      | { haveChunks?: number[]; transferId: string; type: "ft-accept" }
      | { reason?: string; transferId: string; type: "ft-reject" }
      | { haveChunks: number[]; transferId: string; type: "ft-resume-request" }
      | { digest?: string; transferId: string; type: "ft-sent" }
      | { transferId: string; type: "ft-complete" }
      | { transferId: string; type: "ft-checksum-mismatch" }
      | { reason?: string; transferId: string; type: "ft-cancel" }
      | { transferId: string; type: "ft-pause" }
      | { transferId: string; type: "ft-resume" }
  The decoded control message.
  - {
        checksum: boolean;
        chunkSize: number;
        mimeType: string;
        name: string;
        parallelChannels: number;
        size: number;
        totalChunks: number;
        transferId: string;
        type: "ft-offer";
        version?: number;
    }
    checksum: boolean
    chunkSize: number
    mimeType: string
    name: string
    parallelChannels: number
    size: number
    totalChunks: number
    transferId: string
    type: "ft-offer"
    Optionalversion?: number
    Protocol version of the sender; see FT_PROTOCOL_VERSION. Optional for back-compat.
  - { haveChunks?: number[]; transferId: string; type: "ft-accept" }
  - { reason?: string; transferId: string; type: "ft-reject" }
  - { haveChunks: number[]; transferId: string; type: "ft-resume-request" }
  - { digest?: string; transferId: string; type: "ft-sent" }
  - { transferId: string; type: "ft-complete" }
  - { transferId: string; type: "ft-checksum-mismatch" }
  - { reason?: string; transferId: string; type: "ft-cancel" }
  - { transferId: string; type: "ft-pause" }
  - { transferId: string; type: "ft-resume" }
Returns void
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:254

listenerCount

listenerCount<K extends keyof TransferEvents>(event: K): number
Returns the number of listeners currently registered for event.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to count listeners for.
Returns number
The count of registered listeners (0 if none).
Inherited from Transfer.listenerCount
- Defined in packages/core/src/EventEmitter.ts:128

off

off<K extends keyof TransferEvents>(
event: K,
listener: (...args: TransferEvents[K]) => void,
): this
Removes a previously registered listener for event.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name the listener was registered for.
- listener: (...args: TransferEvents[K]) => void
  The exact function reference passed to on or once.
Returns this
This emitter, for chaining.

Remarks
If the listener is not currently registered, this is a no-op. Only the first matching registration is removed.
Inherited from Transfer.off
- Defined in packages/core/src/EventEmitter.ts:74

on

on<K extends keyof TransferEvents>(
event: K,
listener: (...args: TransferEvents[K]) => void,
): this
Registers a listener that is invoked every time event is emitted.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: TransferEvents[K]) => void
  Callback invoked with the event's argument tuple.
Returns this
This emitter, for chaining.
Inherited from Transfer.on
- Defined in packages/core/src/EventEmitter.ts:43

once

once<K extends keyof TransferEvents>(
event: K,
listener: (...args: TransferEvents[K]) => void,
): this
Registers a listener that is invoked at most once: it is removed automatically before being called the first time event is emitted.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: TransferEvents[K]) => void
  Callback invoked with the event's argument tuple on the next emission.
Returns this
This emitter, for chaining.

Remarks
Remove a pending one-time listener by passing the same function reference to off.
Inherited from Transfer.once
- Defined in packages/core/src/EventEmitter.ts:57

pause

pause(): void
Suspends streaming and notifies the receiver. No-op unless the transfer is TransferState.Active. In-flight chunk reads stop at the next pause gate.

Returns void
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:306

progress

progress(): TransferProgress
Returns a point-in-time TransferProgress snapshot.

Returns TransferProgress
Current byte/chunk counts and completion ratio (ratio is 0 for zero-byte files).
Inherited from Transfer.progress
- Defined in packages/sdk/src/filetransfer/Transfer.ts:123

removeAllListeners

removeAllListeners(event?: keyof TransferEvents): this
Removes listeners for a single event, or for all events.
Parameters
- Optionalevent: keyof TransferEvents
  The event name to clear; if omitted, listeners for every event are removed.
Returns this
This emitter, for chaining.
Inherited from Transfer.removeAllListeners
- Defined in packages/core/src/EventEmitter.ts:116

reoffer

reoffer(channels: RTCDataChannel[]): void
Re-announce this transfer on freshly reconnected data channels after an interrupt. The receiver responds with a resume request so only the chunks it is missing are resent. No-op unless the transfer was interrupted.
Parameters
- channels: RTCDataChannel[]
  The new binary data channels to stream over.
Returns void
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:133

resume

resume(): void
Resumes a paused transfer and notifies the receiver, releasing workers waiting at the pause gate. No-op unless the transfer is TransferState.Paused.

Returns void
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:316

start

start(): void
Begins the transfer by sending the offer control message to the receiver. Byte streaming starts only after the receiver accepts (or requests a resume). Idempotent once past TransferState.Idle. Called automatically by FileTransferManager.sendFile.

Returns void
- Defined in packages/sdk/src/filetransfer/SendTransfer.ts:203

`Protected`toTransferError

toTransferError(
    err: unknown,
    code: FileTransferErrorCode,
    message?: string,
): FileTransferError
Normalizes an unknown thrown value into a FileTransferError tagged with this transfer's id, passing through existing FileTransferErrors unchanged.
Parameters
- err: unknown
  The caught value.
- code: FileTransferErrorCode
  The FileTransferErrorCode to assign when wrapping.
- Optionalmessage: string
  Optional override message; otherwise derived from err.
Returns FileTransferError
A FileTransferError suitable for Transfer.fail.
Inherited from Transfer.toTransferError
- Defined in packages/sdk/src/filetransfer/Transfer.ts:205

`Protected`transitionTo

transitionTo(next: TransferState): boolean
Attempts a state transition, enforcing the legal-transition table.
Parameters
- next: TransferState
  The state to move to.
Returns boolean
true if the transition occurred (or was a no-op because already in next); false if the transfer is already terminal or the transition is illegal. Transitions to TransferState.Failed and TransferState.Cancelled are always permitted from any non-terminal state.
Inherited from Transfer.transitionTo
- Defined in packages/sdk/src/filetransfer/Transfer.ts:149

Class SendTransfer

Remarks

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns SendTransfer

Properties

Protected_state

Protected_transferredBytes

Protected_transferredChunks

Protected ReadonlychunkSize

Readonlydirection

Readonlyid

Readonlymetadata

ReadonlypeerId

Protected ReadonlytotalChunks

Accessors

channelCount

Returns number

interrupted

Returns boolean

isTerminal

Returns boolean

state

Returns TransferState

Methods

Protected_notifyRemoteFailure

Parameters

Returns void

Protected_onTerminal

Returns void

cancel

Parameters

Returns void

emit

Type Parameters

Parameters

Returns boolean

Remarks

ProtectedemitProgress

Returns void

Protectedfail

Parameters

Returns FileTransferError

handleControl

Parameters

checksum: boolean

chunkSize: number

mimeType: string

name: string

parallelChannels: number

size: number

totalChunks: number

transferId: string

type: "ft-offer"

Optionalversion?: number

Returns void

listenerCount

Type Parameters

Parameters

Returns number

off

Type Parameters

Parameters

Returns this

Remarks

on

Type Parameters

Parameters

Returns this

once

Type Parameters

Parameters

`Protected`_state

`Protected`_transferredBytes

`Protected`_transferredChunks

`Protected` `Readonly`chunkSize

`Readonly`direction

`Readonly`id

`Readonly`metadata

`Readonly`peerId

`Protected` `Readonly`totalChunks

`Protected`_notifyRemoteFailure

`Protected`_onTerminal

`Protected`emitProgress

`Protected`fail

`Optional`version?: number

`Protected`toTransferError

`Protected`transitionTo