@grounds/stream

Streaming encode/decode utilities for Relish serialization.

Installation

npm install @grounds/stream

Usage

AsyncGenerator API

import { encodeIterable, decodeIterable } from "@grounds/stream";
import { TypeCode } from "@grounds/core";

// Encode values from async iterable
async function* values() {
  yield { type: TypeCode.String, value: "hello" };
  yield { type: TypeCode.U32, value: 42 };
}

for await (const result of encodeIterable(values())) {
  result.match(
    (bytes) => {
      // Send bytes (Uint8Array) to network/file
    },
    (err) => console.error("Encode failed:", err)
  );
}

// Decode from chunked input
async function* chunks() {
  yield await fetchNextChunk();
}

for await (const result of decodeIterable(chunks())) {
  result.match(
    (value) => console.log(value), // DecodedValue
    (err) => console.error("Decode failed:", err)
  );
}

Web Streams API

import { createEncoderStream, createDecoderStream } from "@grounds/stream";

// Encode: RelishValue -> Uint8Array
const encoded = valueStream.pipeThrough(createEncoderStream());

// Decode: Uint8Array -> RelishValue
const decoded = byteStream.pipeThrough(createDecoderStream());

Schema-aware streaming

import { createSchemaEncoderStream, createSchemaDecoderStream } from "@grounds/stream";
import { RStruct, RString, field } from "@grounds/schema";

const UserSchema = RStruct({
  name: field(0, RString()),
});

// Type-safe encode: User -> Uint8Array
const encoded = userStream.pipeThrough(createSchemaEncoderStream(UserSchema));

// Type-safe decode: Uint8Array -> User
const decoded = byteStream.pipeThrough(createSchemaDecoderStream(UserSchema));

Error handling

Streaming decoders detect incomplete data at end of stream:

for await (const result of decodeIterable(chunks())) {
  result.mapErr((error) => {
    if (error.code === "TRUNCATED_STREAM") {
      console.error("Incomplete value at end of input");
    }
  });
}

API reference

AsyncGenerator

• encodeIterable(values) - Yields Result<Uint8Array, EncodeError>
• decodeIterable(chunks) - Yields Result<DecodedValue, DecodeError>

Web Streams

• createEncoderStream() - TransformStream<RelishValue, Uint8Array>
• createDecoderStream() - TransformStream<Uint8Array, RelishValue>
• createSchemaEncoderStream(schema) - Type-safe encoder
• createSchemaDecoderStream(schema) - Type-safe decoder

License

Apache 2.0