streamkit-binary-stream 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StreamKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# @streamkit/binary-stream
+
+Transport-agnostic binary frame streaming layer for real-time applications.
+
+## What This Package Solves
+
+Real-time binary data (point clouds, video metadata, telemetry) arrives in arbitrary chunks from various sources:
+
+- WebRTC DataChannels
+- WebSockets
+- File readers
+- Serial ports
+- Sensor APIs
+
+This package reassembles those chunks into complete, framed messages with:
+
+- **Deterministic frame boundaries** via a simple header protocol
+- **Backpressure handling** to prevent unbounded memory growth
+- **Drop strategies** for real-time scenarios where latency matters more than completeness
+
+## Why It Exists
+
+Separating frame reassembly from transport and decoding enables:
+
+- **Transport flexibility**: Same framing logic for WebRTC, WebSocket, or any other source
+- **Decoder independence**: Frames can carry point clouds, video metadata, or any binary format
+- **Testability**: Pure synchronous logic, no mocking of network APIs
+
+## How It Fits with @streamkit/pointcloud
+
+```
+┌─────────────────────┐
+│   Transport Layer   │  ← WebRTC, WebSocket, File, etc.
+│   (your code)       │
+└──────────┬──────────┘
+           │ ArrayBuffer chunks
+           ▼
+┌─────────────────────┐
+│ @streamkit/         │  ← This package
+│ binary-stream       │
+└──────────┬──────────┘
+           │ BinaryFrame { id, timestamp, payload }
+           ▼
+┌─────────────────────┐
+│ @streamkit/         │  ← Point cloud decoding
+│ pointcloud          │
+└──────────┬──────────┘
+           │ PointCloudData
+           ▼
+┌─────────────────────┐
+│   Three.js Layer    │  ← Rendering
+└─────────────────────┘
+```
+
+## Installation
+
+```bash
+npm install @streamkit/binary-stream
+```
+
+## Quick Start
+
+```typescript
+import { createBinaryStream } from "@streamkit/binary-stream";
+
+const stream = createBinaryStream({
+  maxFrameSize: 2_000_000, // 2MB max per frame
+  maxBufferSize: 10_000_000, // 10MB buffer limit
+  dropStrategy: "oldest",
+  onFrame(frame) {
+    console.log("Frame received:", frame.id, frame.payload.byteLength);
+    // Pass to decoder, e.g., @streamkit/pointcloud
+  },
+});
+
+// Feed from ANY source
+dataChannel.onmessage = (e) => stream.push(e.data);
+// or
+socket.onmessage = (e) => stream.push(e.data);
+// or
+fileReader.onload = (e) => stream.push(e.target.result);
+```
+
+## Frame Protocol
+
+Frames use a simple binary header (little-endian):
+
+| Offset | Size | Type   | Description    |
+| ------ | ---- | ------ | -------------- |
+| 0      | 4    | uint32 | Payload length |
+| 4      | 4    | uint32 | Frame ID       |
+| 8      | N    | bytes  | Payload        |
+
+Total header size: **8 bytes**
+
+### Encoding Example (sender side)
+
+```typescript
+function encodeFrame(id: number, payload: ArrayBuffer): ArrayBuffer {
+  const header = new ArrayBuffer(8);
+  const view = new DataView(header);
+  view.setUint32(0, payload.byteLength, true); // little-endian
+  view.setUint32(4, id, true);
+
+  const frame = new Uint8Array(8 + payload.byteLength);
+  frame.set(new Uint8Array(header), 0);
+  frame.set(new Uint8Array(payload), 8);
+  return frame.buffer;
+}
+```
+
+## API Reference
+
+### `createBinaryStream(options)`
+
+Creates a binary frame stream processor.
+
+**Options:**
+
+| Option          | Type                           | Default    | Description                            |
+| --------------- | ------------------------------ | ---------- | -------------------------------------- |
+| `maxFrameSize`  | `number`                       | 10MB       | Maximum allowed frame payload size     |
+| `maxBufferSize` | `number`                       | 50MB       | Maximum buffered bytes before dropping |
+| `dropStrategy`  | `'oldest' \| 'newest'`         | `'oldest'` | Which data to drop on overflow         |
+| `onFrame`       | `(frame: BinaryFrame) => void` | required   | Frame completion callback              |
+
+**Returns:** `BinaryStream`
+
+### `BinaryStream`
+
+```typescript
+interface BinaryStream {
+  push(chunk: ArrayBuffer): void; // Feed data
+  reset(): void; // Clear buffers, reset state
+  dispose(): void; // Release resources
+}
+```
+
+### `BinaryFrame`
+
+```typescript
+interface BinaryFrame {
+  id: number; // Frame ID from header
+  timestamp: number; // Completion time (performance.now())
+  payload: ArrayBuffer; // Raw payload data
+}
+```
+
+## Drop Strategies
+
+### `'oldest'` (default)
+
+When buffer exceeds `maxBufferSize`:
+
+- Drops oldest buffered data
+- Resets parse state (may lose partial frame)
+- Best for: real-time streaming where latest data matters
+
+### `'newest'`
+
+When buffer exceeds `maxBufferSize`:
+
+- Rejects new incoming chunks
+- Preserves existing buffered data
+- Best for: scenarios where completing current frame is priority
+
+## Memory Management
+
+```typescript
+// Reset on connection loss
+stream.reset();
+
+// Full cleanup
+stream.dispose();
+```
+
+After `dispose()`, the stream cannot be reused.
+
+## Error Handling
+
+- **Oversized frames**: Logged and skipped (header consumed, payload discarded)
+- **Callback errors**: Logged but don't break the stream
+- **Use after dispose**: Throws error
+
+## TypeScript
+
+Full type exports:
+
+```typescript
+import type {
+  BinaryFrame,
+  BinaryStream,
+  BinaryStreamOptions,
+  DropStrategy,
+} from "@streamkit/binary-stream";
+
+import { FRAME_HEADER_SIZE } from "@streamkit/binary-stream";
+```
+
+## Design Constraints
+
+This package intentionally does NOT:
+
+- ❌ Perform any networking
+- ❌ Decode payload contents
+- ❌ Use async/await or Promises
+- ❌ Emit events or use Observables
+- ❌ Depend on Node.js or browser-specific APIs (except `performance.now()`)
+
+## License
+
+MIT

package/dist/binaryStream.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @streamkit/binary-stream - Binary Stream Implementation
+ *
+ * Transport-agnostic binary frame reassembly with backpressure support.
+ */
+import type { BinaryStream, BinaryStreamOptions } from "./types.js";
+/**
+ * Creates a transport-agnostic binary stream for frame reassembly.
+ *
+ * The stream accepts arbitrary binary chunks and reassembles them into
+ * complete frames based on a simple header protocol:
+ * - 4 bytes: payload length (uint32 LE)
+ * - 4 bytes: frame ID (uint32 LE)
+ * - N bytes: payload
+ *
+ * @param options - Stream configuration
+ * @returns BinaryStream controller
+ *
+ * @example
+ * ```typescript
+ * const stream = createBinaryStream({
+ *   maxFrameSize: 2_000_000,
+ *   dropStrategy: 'oldest',
+ *   onFrame(frame) {
+ *     console.log('Frame:', frame.id, frame.payload.byteLength);
+ *   }
+ * });
+ *
+ * // Feed from any source
+ * stream.push(chunk1);
+ * stream.push(chunk2);
+ * ```
+ */
+export declare function createBinaryStream(options: BinaryStreamOptions): BinaryStream;
+//# sourceMappingURL=binaryStream.d.ts.map

package/dist/binaryStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binaryStream.d.ts","sourceRoot":"","sources":["../src/binaryStream.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAEV,YAAY,EACZ,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AAmCpB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA2J7E"}

package/dist/binaryStream.js

@@ -0,0 +1,180 @@
+/**
+ * @streamkit/binary-stream - Binary Stream Implementation
+ *
+ * Transport-agnostic binary frame reassembly with backpressure support.
+ */
+import { BufferQueue } from "./bufferQueue.js";
+import { FRAME_HEADER_SIZE } from "./types.js";
+/** Default maximum frame size: 10MB */
+const DEFAULT_MAX_FRAME_SIZE = 10 * 1024 * 1024;
+/** Default maximum buffer size: 50MB */
+const DEFAULT_MAX_BUFFER_SIZE = 50 * 1024 * 1024;
+/** Default drop strategy */
+const DEFAULT_DROP_STRATEGY = "oldest";
+/**
+ * Reads a uint32 from a Uint8Array at offset (little-endian).
+ */
+function readUint32LE(data, offset) {
+    return ((data[offset] |
+        (data[offset + 1] << 8) |
+        (data[offset + 2] << 16) |
+        (data[offset + 3] << 24)) >>>
+        0); // >>> 0 ensures unsigned
+}
+/**
+ * Creates a transport-agnostic binary stream for frame reassembly.
+ *
+ * The stream accepts arbitrary binary chunks and reassembles them into
+ * complete frames based on a simple header protocol:
+ * - 4 bytes: payload length (uint32 LE)
+ * - 4 bytes: frame ID (uint32 LE)
+ * - N bytes: payload
+ *
+ * @param options - Stream configuration
+ * @returns BinaryStream controller
+ *
+ * @example
+ * ```typescript
+ * const stream = createBinaryStream({
+ *   maxFrameSize: 2_000_000,
+ *   dropStrategy: 'oldest',
+ *   onFrame(frame) {
+ *     console.log('Frame:', frame.id, frame.payload.byteLength);
+ *   }
+ * });
+ *
+ * // Feed from any source
+ * stream.push(chunk1);
+ * stream.push(chunk2);
+ * ```
+ */
+export function createBinaryStream(options) {
+    const { maxFrameSize = DEFAULT_MAX_FRAME_SIZE, maxBufferSize = DEFAULT_MAX_BUFFER_SIZE, dropStrategy = DEFAULT_DROP_STRATEGY, onFrame, } = options;
+    // Validate options
+    if (typeof onFrame !== "function") {
+        throw new Error("BinaryStream: onFrame callback is required");
+    }
+    if (maxFrameSize <= 0) {
+        throw new Error("BinaryStream: maxFrameSize must be positive");
+    }
+    if (maxBufferSize < maxFrameSize) {
+        throw new Error("BinaryStream: maxBufferSize must be >= maxFrameSize");
+    }
+    // Internal state
+    const queue = new BufferQueue();
+    let parseState = { expectedLength: -1, frameId: 0 };
+    let disposed = false;
+    let droppedFrames = 0;
+    /**
+     * Validates stream is not disposed.
+     */
+    function assertNotDisposed() {
+        if (disposed) {
+            throw new Error("BinaryStream has been disposed");
+        }
+    }
+    /**
+     * Applies backpressure by dropping frames according to strategy.
+     */
+    function applyBackpressure() {
+        if (queue.byteLength <= maxBufferSize)
+            return;
+        const overflow = queue.byteLength - maxBufferSize;
+        if (dropStrategy === "oldest") {
+            // Drop oldest buffered data
+            // Reset parse state since we're corrupting the stream
+            const dropped = queue.dropOldest(overflow);
+            if (dropped > 0) {
+                parseState = { expectedLength: -1, frameId: 0 };
+                droppedFrames++;
+            }
+        }
+        // 'newest' strategy: handled in push() by rejecting new chunks
+    }
+    /**
+     * Attempts to parse complete frames from the buffer.
+     */
+    function processFrames() {
+        while (!disposed) {
+            // State: waiting for header
+            if (parseState.expectedLength === -1) {
+                if (!queue.hasBytes(FRAME_HEADER_SIZE)) {
+                    break; // Need more data
+                }
+                const header = queue.peek(FRAME_HEADER_SIZE);
+                if (!header)
+                    break;
+                const payloadLength = readUint32LE(header, 0);
+                const frameId = readUint32LE(header, 4);
+                // Validate frame size
+                if (payloadLength > maxFrameSize) {
+                    // Frame too large - skip header and try to resync
+                    queue.skip(FRAME_HEADER_SIZE);
+                    console.warn(`BinaryStream: Frame ${frameId} exceeds maxFrameSize (${payloadLength} > ${maxFrameSize}), skipping`);
+                    continue;
+                }
+                // Consume header and update state
+                queue.skip(FRAME_HEADER_SIZE);
+                parseState = { expectedLength: payloadLength, frameId };
+            }
+            // State: waiting for payload
+            if (parseState.expectedLength >= 0) {
+                if (!queue.hasBytes(parseState.expectedLength)) {
+                    break; // Need more data
+                }
+                // Read complete payload
+                const payload = queue.read(parseState.expectedLength);
+                if (!payload)
+                    break; // Should not happen
+                // Emit frame
+                const frame = {
+                    id: parseState.frameId,
+                    timestamp: performance.now(),
+                    payload,
+                };
+                // Reset parse state for next frame
+                parseState = { expectedLength: -1, frameId: 0 };
+                // Invoke callback (synchronously)
+                try {
+                    onFrame(frame);
+                }
+                catch (err) {
+                    console.error("BinaryStream: onFrame callback threw:", err);
+                }
+            }
+        }
+    }
+    return {
+        push(chunk) {
+            assertNotDisposed();
+            if (chunk.byteLength === 0)
+                return;
+            // 'newest' drop strategy: reject if adding would exceed buffer
+            if (dropStrategy === "newest") {
+                if (queue.byteLength + chunk.byteLength > maxBufferSize) {
+                    droppedFrames++;
+                    return; // Drop this chunk
+                }
+            }
+            // Add chunk to queue
+            queue.push(chunk);
+            // Apply backpressure for 'oldest' strategy
+            applyBackpressure();
+            // Process any complete frames
+            processFrames();
+        },
+        reset() {
+            assertNotDisposed();
+            queue.clear();
+            parseState = { expectedLength: -1, frameId: 0 };
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            queue.clear();
+            parseState = { expectedLength: -1, frameId: 0 };
+        },
+    };
+}
+//# sourceMappingURL=binaryStream.js.map

package/dist/binaryStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binaryStream.js","sourceRoot":"","sources":["../src/binaryStream.ts"],"names":[],"mappings":"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"}

package/dist/bufferQueue.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @streamkit/binary-stream - Buffer Queue
+ *
+ * Efficient buffer management for chunk accumulation.
+ * Supports partial reads and memory-bounded operation.
+ */
+/**
+ * A queue that accumulates ArrayBuffer chunks and supports
+ * sequential reading of arbitrary byte lengths.
+ */
+export declare class BufferQueue {
+    private chunks;
+    private totalBytes;
+    private readOffset;
+    /**
+     * Current number of bytes available for reading.
+     */
+    get byteLength(): number;
+    /**
+     * Append a chunk to the queue.
+     * @param buffer - Data to append
+     */
+    push(buffer: ArrayBuffer): void;
+    /**
+     * Check if at least `length` bytes are available.
+     * @param length - Required byte count
+     */
+    hasBytes(length: number): boolean;
+    /**
+     * Peek at bytes without consuming them.
+     * @param length - Number of bytes to peek
+     * @returns Uint8Array view or null if insufficient data
+     */
+    peek(length: number): Uint8Array | null;
+    /**
+     * Read and consume bytes from the queue.
+     * @param length - Number of bytes to read
+     * @returns ArrayBuffer or null if insufficient data
+     */
+    read(length: number): ArrayBuffer | null;
+    /**
+     * Skip bytes without copying them.
+     * @param length - Number of bytes to skip
+     * @returns True if bytes were skipped, false if insufficient data
+     */
+    skip(length: number): boolean;
+    /**
+     * Drop all data from the oldest incomplete frame.
+     * Removes bytes until the queue is empty or below threshold.
+     * @param bytesToDrop - Minimum bytes to remove
+     * @returns Number of bytes actually dropped
+     */
+    dropOldest(bytesToDrop: number): number;
+    /**
+     * Clear all buffered data.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=bufferQueue.d.ts.map

package/dist/bufferQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferQueue.d.ts","sourceRoot":"","sources":["../src/bufferQueue.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;IAEvB;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAM/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IA2BvC;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IA8BxC;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAwB7B;;;;;OAKG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAQvC;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd"}

package/dist/bufferQueue.js

@@ -0,0 +1,143 @@
+/**
+ * @streamkit/binary-stream - Buffer Queue
+ *
+ * Efficient buffer management for chunk accumulation.
+ * Supports partial reads and memory-bounded operation.
+ */
+/**
+ * A queue that accumulates ArrayBuffer chunks and supports
+ * sequential reading of arbitrary byte lengths.
+ */
+export class BufferQueue {
+    constructor() {
+        this.chunks = [];
+        this.totalBytes = 0;
+        this.readOffset = 0; // Offset within first chunk
+    }
+    /**
+     * Current number of bytes available for reading.
+     */
+    get byteLength() {
+        return this.totalBytes;
+    }
+    /**
+     * Append a chunk to the queue.
+     * @param buffer - Data to append
+     */
+    push(buffer) {
+        if (buffer.byteLength === 0)
+            return;
+        this.chunks.push(new Uint8Array(buffer));
+        this.totalBytes += buffer.byteLength;
+    }
+    /**
+     * Check if at least `length` bytes are available.
+     * @param length - Required byte count
+     */
+    hasBytes(length) {
+        return this.totalBytes >= length;
+    }
+    /**
+     * Peek at bytes without consuming them.
+     * @param length - Number of bytes to peek
+     * @returns Uint8Array view or null if insufficient data
+     */
+    peek(length) {
+        if (!this.hasBytes(length))
+            return null;
+        const result = new Uint8Array(length);
+        let written = 0;
+        let chunkIndex = 0;
+        let offset = this.readOffset;
+        while (written < length && chunkIndex < this.chunks.length) {
+            const chunk = this.chunks[chunkIndex];
+            const available = chunk.length - offset;
+            const toCopy = Math.min(available, length - written);
+            result.set(chunk.subarray(offset, offset + toCopy), written);
+            written += toCopy;
+            if (offset + toCopy >= chunk.length) {
+                chunkIndex++;
+                offset = 0;
+            }
+            else {
+                offset += toCopy;
+            }
+        }
+        return result;
+    }
+    /**
+     * Read and consume bytes from the queue.
+     * @param length - Number of bytes to read
+     * @returns ArrayBuffer or null if insufficient data
+     */
+    read(length) {
+        if (!this.hasBytes(length))
+            return null;
+        const result = new Uint8Array(length);
+        let written = 0;
+        while (written < length) {
+            const chunk = this.chunks[0];
+            const available = chunk.length - this.readOffset;
+            const toCopy = Math.min(available, length - written);
+            result.set(chunk.subarray(this.readOffset, this.readOffset + toCopy), written);
+            written += toCopy;
+            this.totalBytes -= toCopy;
+            if (this.readOffset + toCopy >= chunk.length) {
+                // Consumed entire chunk, remove it
+                this.chunks.shift();
+                this.readOffset = 0;
+            }
+            else {
+                this.readOffset += toCopy;
+            }
+        }
+        return result.buffer;
+    }
+    /**
+     * Skip bytes without copying them.
+     * @param length - Number of bytes to skip
+     * @returns True if bytes were skipped, false if insufficient data
+     */
+    skip(length) {
+        if (!this.hasBytes(length))
+            return false;
+        let remaining = length;
+        while (remaining > 0) {
+            const chunk = this.chunks[0];
+            const available = chunk.length - this.readOffset;
+            const toSkip = Math.min(available, remaining);
+            remaining -= toSkip;
+            this.totalBytes -= toSkip;
+            if (this.readOffset + toSkip >= chunk.length) {
+                this.chunks.shift();
+                this.readOffset = 0;
+            }
+            else {
+                this.readOffset += toSkip;
+            }
+        }
+        return true;
+    }
+    /**
+     * Drop all data from the oldest incomplete frame.
+     * Removes bytes until the queue is empty or below threshold.
+     * @param bytesToDrop - Minimum bytes to remove
+     * @returns Number of bytes actually dropped
+     */
+    dropOldest(bytesToDrop) {
+        const toDrop = Math.min(bytesToDrop, this.totalBytes);
+        if (toDrop > 0) {
+            this.skip(toDrop);
+        }
+        return toDrop;
+    }
+    /**
+     * Clear all buffered data.
+     */
+    clear() {
+        this.chunks = [];
+        this.totalBytes = 0;
+        this.readOffset = 0;
+    }
+}
+//# sourceMappingURL=bufferQueue.js.map

package/dist/bufferQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferQueue.js","sourceRoot":"","sources":["../src/bufferQueue.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @streamkit/binary-stream
+ *
+ * Transport-agnostic binary frame streaming layer.
+ *
+ * This package provides:
+ * - Binary frame reassembly from arbitrary chunks
+ * - Backpressure with configurable drop strategies
+ * - Memory-bounded operation for real-time safety
+ *
+ * @packageDocumentation
+ */
+export type { BinaryFrame, BinaryStream, BinaryStreamOptions, DropStrategy, } from "./types.js";
+export { FRAME_HEADER_SIZE } from "./types.js";
+export { createBinaryStream } from "./binaryStream.js";
+export { BufferQueue } from "./bufferQueue.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,YAAY,EACV,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAM/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAMvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @streamkit/binary-stream
+ *
+ * Transport-agnostic binary frame streaming layer.
+ *
+ * This package provides:
+ * - Binary frame reassembly from arbitrary chunks
+ * - Backpressure with configurable drop strategies
+ * - Memory-bounded operation for real-time safety
+ *
+ * @packageDocumentation
+ */
+export { FRAME_HEADER_SIZE } from "./types.js";
+// =============================================================================
+// Stream Factory
+// =============================================================================
+export { createBinaryStream } from "./binaryStream.js";
+// =============================================================================
+// Utilities (internal, but exported for advanced use)
+// =============================================================================
+export { BufferQueue } from "./bufferQueue.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,gFAAgF;AAChF,sDAAsD;AACtD,gFAAgF;AAEhF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @streamkit/binary-stream - Type Definitions
+ *
+ * Core types for the binary frame streaming layer.
+ */
+/**
+ * A complete binary frame extracted from the stream.
+ */
+export interface BinaryFrame {
+    /** Unique frame identifier from the stream */
+    id: number;
+    /** Timestamp when frame was completed (performance.now()) */
+    timestamp: number;
+    /** Raw payload data */
+    payload: ArrayBuffer;
+}
+/**
+ * Drop strategy when buffer limits are exceeded.
+ */
+export type DropStrategy = "oldest" | "newest";
+/**
+ * Configuration options for creating a binary stream.
+ */
+export interface BinaryStreamOptions {
+    /** Maximum allowed frame size in bytes (default: 10MB) */
+    maxFrameSize?: number;
+    /** Maximum buffer size in bytes before applying drop strategy (default: 50MB) */
+    maxBufferSize?: number;
+    /** Strategy for dropping frames when buffer overflows (default: 'oldest') */
+    dropStrategy?: DropStrategy;
+    /** Callback invoked when a complete frame is ready */
+    onFrame: (frame: BinaryFrame) => void;
+}
+/**
+ * Binary stream controller interface.
+ */
+export interface BinaryStream {
+    /**
+     * Push a chunk of binary data into the stream.
+     * Chunks are accumulated and reassembled into complete frames.
+     * @param chunk - Raw binary data from any source
+     */
+    push(chunk: ArrayBuffer): void;
+    /**
+     * Reset the stream state, discarding all buffered data.
+     * Use after connection reset or stream discontinuity.
+     */
+    reset(): void;
+    /**
+     * Dispose the stream and release all resources.
+     * Stream cannot be used after disposal.
+     */
+    dispose(): void;
+}
+/**
+ * Frame header constants.
+ */
+export declare const FRAME_HEADER_SIZE = 8;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sDAAsD;IACtD,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAE/B;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * @streamkit/binary-stream - Type Definitions
+ *
+ * Core types for the binary frame streaming layer.
+ */
+/**
+ * Frame header constants.
+ */
+export const FRAME_HEADER_SIZE = 8; // 4 bytes length + 4 bytes id
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyDH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,CAAC,8BAA8B"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "streamkit-binary-stream",
+  "version": "0.2.0",
+  "description": "Transport-agnostic binary frame streaming layer for real-time applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "binary",
+    "stream",
+    "frame",
+    "buffer",
+    "real-time",
+    "streaming",
+    "arraybuffer",
+    "backpressure"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "rimraf": "^5.0.5",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}