npm package: @stationeers-ic/ic-schema-encoder
Description: Encoder and decoder indendet for IC schema data using CompressionStream and Base64 encoding.
Latest version: 0.1.0

# @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

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

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

## Usage

### Basic Encoding/Decoding

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```typescript
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`:

```typescript
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](LICENSE) file for details.

## Repository

[GitHub](https://github.com/Stationeers-ic/ic-schema-encoder)

## Issues

Report issues at [GitHub Issues](https://github.com/Stationeers-ic/ic-schema-encoder/issues)