ts-chan

Concurrency primitives for TypeScript and JavaScript.

Introduction

Concurrency in JavaScript, frankly, sucks.

This module is an effort to provide concurrency primitives for TypeScript/JavaScript that capture as much of the semantics of Go's channels as possible, while remaining idiomatic to the language.

I'll be iterating on this for a few weeks, in my spare time, with the goal of a production-ready module, which can be used any JS environment, including browsers.

There are many applications for concurrent programming, and (IMO) it's something that anyone writing software should have a basic understanding of. Concurrency is rarely trivial, it's often difficult to get right. By providing a simple API that mitigates common pitfalls, ts-chan aims to make concurrent programming more accessible to JavaScript developers.

Patterns are a broad topic, but I intend to document several, with a side-by-side comparison to vanilla JS. Additionally, you'll find that many of Go's concurrency patterns apply directly, excepting (for example) those that leverage multiple CPUs.

Usage

Installation

Install or import the NPM package ts-chan. Supported platforms include Node.js, Deno, and browsers.

The microtask queue: a footgun

This module takes steps to mitigate the risk of microtask cycles. They remain, however, a real concern for any JavaScript program, that involves communication between concurrent operations. Somewhat more insidious than plain call cycles, as they are not visible in the call stack, it's important to know that promises and async/await operate on the microtask queue, unless they wait on something that operates on the macrotask queue (e.g. IO, timers).

While queueMicrotask is not used by this module, MDN's Using microtasks in JavaScript with queueMicrotask() guide is both informative and relevant.

The mitigation strategy used by this module is for high-level async methods (including Chan.send, Chan.recv, and Select.wait) to use getYieldGeneration and yieldToMacrotaskQueue like:

const exampleHighLevelAsyncMethod = async () => {
  // ...
  const yieldGeneration = getYieldGeneration();
  const yieldPromise = yieldToMacrotaskQueue();
  try {
    // ...
    return await result;
  } finally {
    if (getYieldGeneration() === yieldGeneration) {
      await yieldPromise;
    }
  }
};

The above is a simple (albeit unoptimised) pattern which ensures that, so long as one side calls one of these methods, the event loop will not block. This solution does have some performance impact, and does not completely mitigate the risk, but seems a reasonable compromise.

Architecture

Protocol

To facilitate arbitrary implementations, this module defines a protocol for implementation of channels, modelled as Sender and Receiver. This protocol is styled after JavaScript's iteration protocols, though it differs in that the outer types, Sendable and Receivable (analogues to Iterable), are not intended to support statefulness independently of the channel (no return analogue).

This documentation is a work in progress, so, for now, it may be easiest to peruse src/protocol.ts.

Chan class

The Chan class is a reference implementation of the channel protocol. It has full support for the protocol, Go-like channel close semantics, and supports buffered channel semantics.

Unlike Go's channel, all sends and receives are processed in FIFO order, allowing it to function as a queue, if desired. Also provided are a number of convenience methods and properties, that are not part of the core protocol, but are useful for common use cases.

See the API documentation for more details.

Select class

The absence of an analogue to Go's select statement would limit the usefulness of channels, as the select statement is Go's key to implementing "reactive" software. The Select class provided by this module is intended to fill that gap, and is modelled after Go's select statement, particularly regarding the semantics of receiving and sending. This class utilizes the "channel protocol" (as defined by this module). AbortSignal is fully supported, and (can) function equivalently to including a case <-ctx.Done():, in Go. Promises are also supported, though they have no analogue, in Go.

Comparison to Go's select statement

Similarities

Random Selection: Just as Go's select statement picks one communicative operation using a uniform pseudo-random selection (if more than one is immediately available), the Select class does so too.
Blocking Behavior: In Go, if no communication can proceed and there's no default case, the select statement blocks. Similarly, the Select class's wait method will also block until a case is ready.
Default Case Equivalence: The poll method in the Select class serves a similar purpose as the default case in Go's select statement. If no case is ready, poll will return undefined, offering a non-blocking alternative.
Case Evaluation Order: (Optional, see below) The SelectFactory class may be used to evaluate senders, receivers, and values (to send), in source order, and is intended to be used within loops and similar. Use of this class may avoid unnecessary recreation of select cases, on each iteration, with the caveat that it does not (currently) support promises.

Differences

Return Value from wait and poll: The Select class's wait method returns a promise that resolves with the index of the next ready case. The poll method, on the other hand, returns the index directly or undefined. In contrast, Go's select statement does not return values in this manner. This is a mechanism used to provide type support.
Operation to "receive" value: Once a receive case is ready, in the Select class, the result must be explicitly retrieved using the recv method, which must be provided with the case which is ready. This contrasts with Go, where the received value is directly assigned in the case clause. Again, this is a part of the mechanism used to provide type support.
Limited default value support: Nil channels have not analogue in TS/JS. Additionally, while receiving a "default value" (on receive from a closed channel) is a supported part of the channel protocol, it's not required, and has no (type-based) mechanism to describe whether the channel supports it, or not.
Case Evaluation Order: This is an interesting topic, and I found that Go's behavior was not exactly what I expected. For simplicity, this functionality was omitted from Select, and is provided by SelectFactory, instead. For reference, from the Go spec:

For all the cases in the statement, the channel operands of receive operations and the channel and right-hand-side expressions of send statements are evaluated exactly once, in source order, upon entering the "select" statement. The result is a set of channels to receive from or send to, and the corresponding values to send. Any side effects in that evaluation will occur irrespective of which (if any) communication operation is selected to proceed. Expressions on the left-hand side of a RecvStmt with a short variable declaration or assignment are not yet evaluated.