CappedDelimiterStream

import { CappedDelimiterStream } from "jsr:@ende/streams/unstable-capped-delimiter-stream";

class ยท experimental

class CappedDelimiterStream implements TransformStream<Uint8Array, CappedDelimiterEntry>

CappedDelimiterStream is a TransformStream that splits a ReadableStream<Uint8Array> by a provided delimiter, returning CappedDelimiterEntry objects. Each entry's match property indicates whether the corresponding value ended with the delimiter. The class also requires a limit property to specify the max length that each entry can be, which can be preferable if your delimiter is unlikely to appear often.

Remarks

This TransformStream is useful over DelimiterStream when you need to split on a delimiter that is expected to occur rarely and want to protect against unbounded buffering. Setting a limit prevents the stream from growing its internal buffer indefinitely. When the buffer reaches the specified limit the stream will emit a CappedDelimiterEntry with { match: false } and continue. When the delimiter appears, the following entry will have { match: true }.

This pattern is handy for protocols or file formats that use an infrequent separator, like NUL, record separator, or a multi-byte boundary, while otherwise streaming arbitrarily large payloads. It lets consumers process intermediate chunks instead of waiting for the entire message or risking excessive memory usage.

Example

import { assertEquals } from "@ende/assert";
import {
  CappedDelimiterStream,
} from "@ende/streams/unstable-capped-delimiter-stream";

const encoder = new TextEncoder();

const readable = ReadableStream.from(["foo;beeps;;bar;;"])
  .pipeThrough(new TextEncoderStream())
  .pipeThrough(
    new CappedDelimiterStream({
      delimiter: encoder.encode(";"),
      limit: 4,
    }),
  );

assertEquals(
  await Array.fromAsync(readable),
  [
    { match: true, value: encoder.encode("foo") },
    { match: false, value: encoder.encode("beep") },
    { match: true, value: encoder.encode("s") },
    { match: true, value: encoder.encode("") },
    { match: true, value: encoder.encode("bar") },
    { match: true, value: encoder.encode("") },
  ],
);

Constructors

constructor

new CappedDelimiterStream(options: CappedDelimiterOptions)

Constructs a new instance.

options: CappedDelimiterOptions

The options for the stream.

Methods

readable

get readable(): ReadableStream<CappedDelimiterEntry>

The ReadableStream.

Returns

ReadableStream

Example: Usage

import { assertEquals } from "@ende/assert";
import {
  CappedDelimiterStream,
} from "@ende/streams/unstable-capped-delimiter-stream";

const encoder = new TextEncoder();

const readable = ReadableStream.from(["foo;beeps;;bar;;"])
  .pipeThrough(new TextEncoderStream())
  .pipeThrough(
    new CappedDelimiterStream({
      delimiter: encoder.encode(";"),
      limit: 4,
    }),
  );

assertEquals(
  await Array.fromAsync(readable),
  [
    { match: true, value: encoder.encode("foo") },
    { match: false, value: encoder.encode("beep") },
    { match: true, value: encoder.encode("s") },
    { match: true, value: encoder.encode("") },
    { match: true, value: encoder.encode("bar") },
    { match: true, value: encoder.encode("") },
  ],
);

writable

get writable(): WritableStream<Uint8Array>

The WritableStream.

Returns

WritableStream

Example: Usage

import { assertEquals } from "@ende/assert";
import {
  CappedDelimiterStream,
} from "@ende/streams/unstable-capped-delimiter-stream";

const encoder = new TextEncoder();

const readable = ReadableStream.from(["foo;beeps;;bar;;"])
  .pipeThrough(new TextEncoderStream())
  .pipeThrough(
    new CappedDelimiterStream({
      delimiter: encoder.encode(";"),
      limit: 4,
    }),
  );

assertEquals(
  await Array.fromAsync(readable),
  [
    { match: true, value: encoder.encode("foo") },
    { match: false, value: encoder.encode("beep") },
    { match: true, value: encoder.encode("s") },
    { match: true, value: encoder.encode("") },
    { match: true, value: encoder.encode("bar") },
    { match: true, value: encoder.encode("") },
  ],
);

Source