@stationeers-ic/ic-schema-encoder

Encoder and decoder intended for IC schema data using CompressionStream and Base64 encoding.

Features

• Compression: Uses deflate-raw compression for efficient data encoding
• Base64 Encoding: Automatic base64 encoding/decoding for safe transmission
• Stream Support: Works with ReadableStreams, TransformStreams, and single values
• Chunked Processing: Automatically chunks large inputs (>2048 bytes) for optimal performance
• Flexible API: Supports both streaming and single-value encoding/decoding
• Environment Agnostic: Works in browsers and Node.js (with polyfills if needed)

Installation

npm install @stationeers-ic/ic-schema-encoder

bun add @stationeers-ic/ic-schema-encoder

Usage

Basic Encoding/Decoding

import { encode, decode } from '@stationeers-ic/ic-schema-encoder';

// Encode a string
const encoded = await encode('Hello, World!');
console.log(encoded); // Base64-encoded compressed string

// Decode it back
const decoded = await decode(encoded);
console.log(decoded); // 'Hello, World!'

Working with Uint8Array

import { encode, decode } from '@stationeers-ic/ic-schema-encoder';

// Encode binary data
const data = new Uint8Array([72, 101, 108, 108, 111]);
const encoded = await encode(data);

// Decode back to string
const decoded = await decode(encoded);
console.log(decoded); // 'Hello'

Stream Processing

Create a Transform Stream

import { encode, decode } from '@stationeers-ic/ic-schema-encoder';

// Create an encoding transform stream
const encodeTransform = encode();

// Create a decoding transform stream
const decodeTransform = decode();

// Use with pipes
sourceStream
  .pipeThrough(encodeTransform)
  .pipeThrough(decodeTransform)
  .pipeTo(destinationStream);

Process a ReadableStream

import { encode, decode } from '@stationeers-ic/ic-schema-encoder';

// Encode a readable stream
const readableStream = new ReadableStream({
  start(controller) {
    controller.enqueue('chunk 1');
    controller.enqueue('chunk 2');
    controller.close();
  }
});

const encodedStream = encode(readableStream);

// Read from the encoded stream
const reader = encodedStream.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(value); // Base64-encoded compressed chunks
}

Custom Compression/Decompression Streams (Node.js)

For Node.js environments, you can provide custom stream implementations:

import { encode, decode } from '@stationeers-ic/ic-schema-encoder';
import { CompressionStream, DecompressionStream } from 'node:stream/web';

// Encode with custom CompressionStream
const encoded = await encode('Hello, Node.js!', CompressionStream);

// Decode with custom DecompressionStream
const decoded = await decode(encoded, DecompressionStream);
console.log(decoded); // 'Hello, Node.js!'

API Reference

encode(data?, compressionStream?)

Encodes and compresses input data.

Overloads:

1. encode(stream: ReadableStream<string | Uint8Array>, compressionStream?): ReadableStream<string>

   • Encodes a readable stream into a stream of compressed base64 strings

2. encode(data?: null, compressionStream?): TransformStream<string | Uint8Array, string>

   • Creates a transform stream for encoding data (pass null or omit the first argument)

3. encode(data: string | Uint8Array, compressionStream?): Promise<string>

   • Encodes a single string or Uint8Array into a compressed base64 string

Parameters:

• stream / data - Input data (ReadableStream, null/undefined for TransformStream, or string/Uint8Array for single value encoding)
• compressionStream - (Optional) Custom CompressionStream class

Returns: ReadableStream<string>, TransformStream<string | Uint8Array, string>, or Promise<string>

Throws: Error if CompressionStream is not available and not provided

decode(data?, decompressionStream?)

Decodes and decompresses input data.

Overloads:

1. decode(stream: ReadableStream<string | Uint8Array>, decompressionStream?): ReadableStream<string>

   • Decodes a readable stream of compressed data into plain text

2. decode(data?: null, decompressionStream?): TransformStream<string | Uint8Array, string>

   • Creates a transform stream for decoding data (pass null or omit the first argument)

3. decode(data: string | Uint8Array, decompressionStream?): Promise<string>

   • Decodes a single base64 string or Uint8Array into plain text

Parameters:

• stream / data - Input data (ReadableStream, null/undefined for TransformStream, or string/Uint8Array for single value decoding)
• decompressionStream - (Optional) Custom DecompressionStream class

Returns: ReadableStream<string>, TransformStream<string | Uint8Array, string>, or Promise<string>

Throws: Error if DecompressionStream is not available and not provided

Browser Compatibility

The library uses the Web Streams API and Compression Streams API, which are available in:

• Chrome/Edge 103+
• Firefox 113+
• Safari 16.4+
• Opera 89+

Mobile:

• All iOS browsers 16.4+
• Chrome 103+
• Samsung Internet 20+
• Opera Mobile 80+
• Firefox 143+

When supported, the global CompressionStream and DecompressionStream are used by default.

For older browsers or Node.js < 17, you may need to provide polyfills.

Node.js Support

For Node.js, import the compression streams from node:stream/web:

import { CompressionStream, DecompressionStream } from 'node:stream/web';
import { encode, decode } from '@stationeers-ic/ic-schema-encoder';

const encoded = await encode('data', CompressionStream);
const decoded = await decode(encoded, DecompressionStream);

License

See LICENSE file for details.

Repository

GitHub

Issues

Report issues at GitHub Issues