Class Channel<T>

constructor

• new Channel<T extends NotUndefined>(capacity: number): Channel<T>

  Type Parameters

  • T extends NotUndefined

  Parameters

  • capacity: number

    Capacity of the channel buffer. Integer >= 0. If 0, the channel is unbuffered, meaning that each WritableChannel.write blocks until ReadableChannel.read and vice versa

  Returns Channel<T>

Readonlycapacity

closed

• get closed(): boolean

  Returns true after WritableChannel.close was called on the channel. See WritableChannel.close for the explanation of what are closed channels

  Returns boolean

readableWaitsCount

• get readableWaitsCount(): number

  Returns the number of currently blocked ReadableChannel.waitUntilReadable calls

  Returns number

writableWaitsCount

• get writableWaitsCount(): number

  Returns the number of currently blocked WritableChannel.waitUntilWritable calls

  Returns number

[asyncIterator]

• "[asyncIterator]"(): AsyncIterator<T, any, any>

  Returns AsyncIterator<T, any, any>

close

• close(): void

  Closes the channel. Closed channels cannot be written to. They can still be read from if there are values left in the buffer

  More precisely, after close:

  • Blocked calls to WritableChannel.write will unblock by throwing CannotWriteIntoClosedChannel

  • Future calls to WritableChannel.write will throw CannotWriteIntoClosedChannel immediately

  • Calls to ReadableChannel.read will consume the values left in the buffer before returning undefined

  Unlike in Go, this method is idempotent

  Returns void

raceRead

• raceRead(): Selectable<undefined | T>

  Like ReadableChannel.read, but can be used with select

  Returns Selectable<undefined | T>

raceWrite

• raceWrite(value: T): Selectable<void>

  Like WritableChannel.write, but can be used with select

  Parameters

  • value: T

  Returns Selectable<void>

read

• read(): Promise<undefined | T>

  Reads a value from the channel. If there are no values, blocks until there is

  If channel is buffered, takes next value from the buffer. This unblocks first of blocked WritableChannel.write calls if there are any

  If channel is unbuffered, simply unblocks the first of blocked WritableChannel.write

  If the channel is closed and has no values left in the buffer, returns undefined

  Concurrent calls are allowed - each read will get own value (no two reads will get the same value). If multiple calls are blocked, they will unblock one-by-one in unspecified order

  Note: each blocked call occupies memory, and there is no limit on how many calls there can be at once. Typically, programs have a fixed or a finite number of reads, so this should not be a problem

  Returns Promise<undefined | T>

tryRead

• tryRead(): undefined | T

  Non-blocking version of ReadableChannel.read. Unlike ReadableChannel.read, if channel has no values, returns undefined

  This means undefined is returned in two cases: (1) the channel is open but has no values, and the channel is closed and has no values. Use ReadableChannel.closed to tell those apart

  Returns undefined | T

tryWrite

• tryWrite(value: T): boolean

  Non-blocking version of WritableChannel.write. Returns true is the value was written into the channel. Returns false when WritableChannel.write would block. Throws if the channel is closed

  Parameters

  • value: T

  Returns boolean

waitUntilReadable

• waitUntilReadable<const R>(value: R, signal?: AbortSignal): Promise<R>

  Blocks until the channel is "readable", meaning that it either:

  • Has a value (value in the buffer or a blocked WritableChannel.write call)
  • Is closed

  Intuitively, a channel is "readable" when the next ReadableChannel.read call on it does not block (resolves immediately)

  Type Parameters

  • const R

  Parameters

  • value: R

    Specify a value to return once the wait unblocks

  • Optionalsignal: AbortSignal

    Use signal to cancel the wait. This frees up memory occupied by the wait. After cancelling, the wait will throw AbortedError

  Returns Promise<R>

waitUntilWritable

• waitUntilWritable<const R>(value: R, signal?: AbortSignal): Promise<R>

  Blocks until the channel is "writable", meaning that it either:

  • Is closed
  • Has a free space in the buffer
  • Has a blocked ReadableChannel.read call

  Intuitively, a channel is "writable" when the next WritableChannel.write call on it does not block (resolves or rejects immediately)

  Type Parameters

  • const R

  Parameters

  • value: R

    Specify a value to return once the wait unblocks

  • Optionalsignal: AbortSignal

    Use signal to cancel the wait. This frees up memory occupied by the wait. After cancelling, the wait will throw AbortedError

  Returns Promise<R>

write

• write(value: T): Promise<void>

  Writes value to the channel. If there is no free space in the channel, blocks until there is. This gives backpressure: if writer is faster than reader, the channel buffer will eventually fill up and the writer will start to block

  If channel is buffered, tries to write value in the buffer, and blocks if the buffer is full. If channel is unbuffered, waits for ReadableChannel.read call (resolved immediately if there is a blocked ReadableChannel.read call already)

  If the channel was closed before the call, or became closed while the call was blocked, throws CannotWriteIntoClosedChannel

  Order of values is guaranteed for sequential writes: after await ch.write(1); await ch.write(2), 1 is guaranteed to be read before 2. Order is not guaranteed for concurrent writes: after await Promise.race([ch.write(1), ch.write(2)]), 1 and 2 can appear in any order when reading

  Note: in current implementation, order of values is the same as order of calls to write(), so example above will always give 1, 2. This will change in future if worker_threads support will be implemented. It is not advisable to rely on this

  Parameters

  • value: T

  Returns Promise<void>