TransformStream

The TransformStream interface of the Streams API represents a set of transformable data.

Constructor

TransformStream()
Creates and returns a transform stream object from the given handlers.

Properties

TransformStream.readable Read only
The readable end of a TransformStream.
TransformStream.writable Read only
The writable end of a TransformStream.

Methods

None

Examples

Anything-to-uint8array stream

In the following example, a transform stream passes through all chunks it receives as Uint8Array values.

const transformContent = {
  start() {}, // required.
  async transform(chunk, controller) {
    chunk = await chunk
    switch (typeof chunk) {
      case 'object':
        // just say the stream is done I guess
        if (chunk === null) controller.terminate()
        else if (ArrayBuffer.isView(chunk))
          controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength))
        else if (Array.isArray(chunk) && chunk.every(value => typeof value === 'number'))
          controller.enqueue(new Uint8Array(chunk))
        else if ('function' === typeof chunk.valueOf && chunk.valueOf() !== chunk)
          this.transform(chunk.valueOf(), controller) // hack
        else if ('toJSON' in chunk) this.transform(JSON.stringify(chunk), controller)
        break
      case 'symbol':
        controller.error("Cannot send a symbol as a chunk part")
        break
      case 'undefined':
        controller.error("Cannot send undefined as a chunk part")
      default:
        controller.enqueue(this.textencoder.encode(String(chunk)))
        break
  },
  flush() { /* do any destructor work here */ }
}

class AnyToU8Stream extends TransformStream {
  constructor() {
    super({...transformContent, textencoder: new TextEncoder()})
  }
}

Polyfilling TextEncoderStream and TextDecoderStream

Note that this is deprecated by the native constructors. This is intended as a polyfill for unsupported platforms.

const tes = {
  start(){this.encoder = new TextEncoder()},
  transform(chunk, controller) {
    controller.enqueue(this.encoder.encode(chunk))
  }
}
let _jstes_wm = new WeakMap(); /* info holder */
class JSTextEncoderStream extends TransformStream {
  constructor() {
    let t = {...tes}

    super(t)
    _jstes_wm.set(this, t)
  }
  get encoding() {return _jstes_wm.get(this).encoder.encoding}
}

Similarly, TextDecoderStream can be written as such:

const tes = {
  start(){
    this.decoder = new TextDecoder(this.encoding, this.options)
  },
  transform(chunk, controller) {
    controller.enqueue(this.decoder.decode(chunk))
  }
}
let _jstds_wm = new WeakMap(); /* info holder */
class JSTextDecoderStream extends TransformStream {
  constructor(encoding = 'utf-8', {...options} = {}) {
    let t = {...tds, encoding, options}

    super(t)
    _jstes_wm.set(this, t)
  }
  get encoding() {return _jstds_wm.get(this).decoder.encoding}
  get fatal() {return _jstds_wm.get(this).decoder.fatal}
  get ignoreBOM() {return _jstds_wm.get(this).decoder.ignoreBOM}
}

Chaining multiple ReadableStreams together

This is a useful one, where multiple streams can be conjoined. Examples include building a PWA with progressive loading and progressive streaming.

let responses = [ /* conjoined response tree */ ]
let {readable, writable} = new TransformStream

responses.reduce(
  (a, res, i, arr) => a.then(() => res.pipeTo(writable, {preventClose: (i+1) !== arr.length})),
  Promise.resolve()
)

Note that this is not resilient to other influences.

Specifications

Specification Status Comment
Streams
The definition of 'TransformStream' in that specification.
Living Standard Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
TransformStream
Non-standard
Chrome Full support 67Edge No support NoFirefox No support NoIE No support NoOpera Full support 54Safari No support NoWebView Android Full support 67Chrome Android Full support 67Firefox Android No support NoOpera Android Full support 48Safari iOS No support NoSamsung Internet Android Full support 9.0
TransformStream() constructor
Non-standard
Chrome Full support 67Edge No support NoFirefox No support NoIE No support NoOpera Full support 54Safari No support NoWebView Android Full support 67Chrome Android Full support 67Firefox Android No support NoOpera Android Full support 48Safari iOS No support NoSamsung Internet Android Full support 9.0
readable
Non-standard
Chrome Full support 67Edge No support NoFirefox No support NoIE No support NoOpera Full support 54Safari No support NoWebView Android Full support 67Chrome Android Full support 67Firefox Android No support NoOpera Android Full support 48Safari iOS No support NoSamsung Internet Android Full support 9.0
writable
Non-standard
Chrome Full support 67Edge No support NoFirefox No support NoIE No support NoOpera Full support 54Safari No support NoWebView Android Full support 67Chrome Android Full support 67Firefox Android No support NoOpera Android Full support 48Safari iOS No support NoSamsung Internet Android Full support 9.0

Legend

Full support  
Full support
No support  
No support
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.

See Also