TransformStream

The TransformStream interface of Azion Runtime: its constructor, its readable and writable properties, and a transform stream that converts chunks to bytes.

Last updated

View as Markdown Agent setup

The TransformStream interface is part of the Streams API of Azion Runtime. It is a concrete implementation of the pipe chain transform stream concept: you pass it to the pipeThrough() method of a ReadableStream to convert a stream of data from one format into another. Use it to decode or encode video frames, decompress data, or convert a stream from XML to JSON. TransformStream is a transferable object. For more information, refer to TransformStream on MDN Web Docs.

Constructor

The TransformStream() constructor creates and returns a transform stream object:

new TransformStream()

The constructor takes an optional transformation object and optional queuing strategies for its streams. Without a transformation object, data passes through the stream unchanged.

The transformation object carries the transformation algorithm. Its transform(chunk, controller) method receives each chunk written to the stream, and controller.enqueue() passes a chunk to the readable side. A transformation object can also define start() and flush() methods, as the Example section shows.

For a queuing strategy, Azion Runtime defines CountQueuingStrategy but not ByteLengthQueuingStrategy: a reference to ByteLengthQueuingStrategy throws ReferenceError: ByteLengthQueuingStrategy is not defined.

Properties

A transform stream has two ends. Together they form the pair that pipeThrough() accepts:

PropertyTypeDescription
readableReadableStreamThe readable end of the transform stream. It returns the transformed chunks.
writableWritableStreamThe writable end of the transform stream. It receives the chunks to transform.

Example

This handler defines AnyToU8Stream, a transform stream that passes every chunk it receives through as a Uint8Array. It pipes a string, an array of numbers, and a Uint16Array through the stream, then returns the bytes of each output chunk:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 const transformContent = {
04 start() {}, // required.
05 async transform(chunk, controller) {
06 chunk = await chunk;
07 switch (typeof chunk) {
08 case 'object':
09 // just say the stream is done
10 if (chunk === null) {
11 controller.terminate();
12 } else if (ArrayBuffer.isView(chunk)) {
13 controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
14 } else if (
15 Array.isArray(chunk) &&
16 chunk.every((value) => typeof value === 'number')
17 ) {
18 controller.enqueue(new Uint8Array(chunk));
19 } else if (
20 typeof chunk.valueOf === 'function' &&
21 chunk.valueOf() !== chunk
22 ) {
23 this.transform(chunk.valueOf(), controller); // hack
24 } else if ('toJSON' in chunk) {
25 this.transform(JSON.stringify(chunk), controller);
26 }
27 break;
28 case 'symbol':
29 controller.error("Cannot send a symbol as a chunk part")
30 break
31 case 'undefined':
32 controller.error("Cannot send undefined as a chunk part")
33 break
34 default:
35 controller.enqueue(this.textencoder.encode(String(chunk)))
36 break
37 }
38 },
39 flush() { /* do any destructor work here */ }
40 }
41
42 class AnyToU8Stream extends TransformStream {
43 constructor() {
44 super({...transformContent, textencoder: new TextEncoder()})
45 }
46 }
47
48 const stream = new ReadableStream({
49 start(c) {
50 c.enqueue('hi');
51 c.enqueue([1, 2]);
52 c.enqueue(new Uint16Array([65]));
53 c.close();
54 },
55 }).pipeThrough(new AnyToU8Stream());
56
57 const chunks = [];
58 for await (const chunk of stream) chunks.push(Array.from(chunk));
59 return Response.json(chunks);
60 },
61};

The function returns these bytes for the three output chunks. The string 'hi' becomes its encoded bytes, the number array becomes a Uint8Array with the same values, and the Uint16Array comes out as the two bytes of its buffer:

JSON
01[
02 [
03 104,
04 105
05 ],
06 [
07 1,
08 2
09 ],
10 [
11 65,
12 0
13 ]
14]
ReadableStream

The stream whose pipeThrough() method sends data through a transform stream.

WritableStream

The stream type of the writable end, and how to write chunks to it.

Encoding

The TextEncoder that the example uses to turn strings into bytes.

Web APIs

The other Web APIs that Azion Runtime supports.