boilstream-consumer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BoilStream
+
+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,92 @@
+# @boilstream/consumer
+
+Real-time Arrow data streaming for browsers and Node.js via Server-Sent Events (SSE).
+
+Connects to a [BoilStream](https://boilstream.com) SSE endpoint and delivers decoded [Apache Arrow](https://arrow.apache.org/) tables using [flechette](https://github.com/uwdata/flechette). Automatic reconnection with `Last-Event-ID` is handled by `EventSource`.
+
+## Install
+
+```bash
+npm install @boilstream/consumer
+```
+
+## Quick Start
+
+### Node.js
+
+```js
+import { BoilStreamConsumer } from "@boilstream/consumer";
+import EventSource from "eventsource";
+
+const consumer = new BoilStreamConsumer("https://host:8443/stream/<token>", {
+  onSchema: (schema) => console.log("Fields:", schema.fields.map(f => f.name)),
+  onBatch: (table, seq) => console.log(`Batch ${seq}: ${table.numRows} rows`),
+  onError: (err) => console.error(err),
+  EventSource, // required in Node.js
+});
+
+// Later: disconnect
+consumer.close();
+```
+
+### Browser
+
+```js
+import { BoilStreamConsumer } from "@boilstream/consumer";
+
+const consumer = new BoilStreamConsumer("https://host:8443/stream/<token>", {
+  onSchema: (schema) => console.log("Fields:", schema.fields.map(f => f.name)),
+  onBatch: (table, seq) => console.log(`Batch ${seq}: ${table.numRows} rows`),
+  onError: (err) => console.error(err),
+  // Native EventSource is used automatically in browsers
+});
+```
+
+See [`examples/browser-test.html`](examples/browser-test.html) for a standalone browser demo.
+
+## API
+
+### `new BoilStreamConsumer(url, options)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | SSE endpoint URL (`https://host/stream/<token>`) |
+| `options.onSchema` | `Function` | Called with flechette `Schema` on schema events |
+| `options.onBatch` | `Function` | Called with `(Table, batchSeq)` on batch events |
+| `options.onHeartbeat` | `Function` | Called on heartbeat events |
+| `options.onError` | `Function` | Called with error on connection/decode errors |
+| `options.EventSource` | `class` | EventSource implementation (required in Node.js) |
+
+### `consumer.schema`
+
+Current schema (`null` until first schema event).
+
+### `consumer.close()`
+
+Disconnect from the SSE stream.
+
+### `decodeArrowIPC(base64Data)`
+
+Low-level utility: decode a base64-encoded Arrow IPC stream into a flechette `Table`.
+
+```js
+import { decodeArrowIPC } from "@boilstream/consumer";
+const table = decodeArrowIPC(base64String);
+```
+
+## SSE Event Types
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `schema` | Base64 Arrow IPC | Table schema (sent on connect and schema changes) |
+| `batch` | Base64 Arrow IPC | Record batch with `lastEventId` for resume |
+| `heartbeat` | empty | Keep-alive signal |
+
+## Dependencies
+
+- [`@uwdata/flechette`](https://github.com/uwdata/flechette) — Arrow IPC decoding
+- [`eventsource`](https://github.com/EventSource/eventsource) — Node.js EventSource polyfill
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "boilstream-consumer",
+  "version": "0.1.0",
+  "description": "BoilStream SSE consumer SDK — real-time Arrow data streaming for browsers and Node.js",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node test/consumer.test.js",
+    "test:browser": "node test/browser.test.js"
+  },
+  "keywords": [
+    "boilstream",
+    "sse",
+    "arrow",
+    "streaming",
+    "real-time",
+    "apache-arrow",
+    "eventsource",
+    "ipc",
+    "flechette"
+  ],
+  "author": "BoilStream",
+  "license": "MIT",
+  "homepage": "https://github.com/dforsber/boilstream-consumer-js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dforsber/boilstream-consumer-js.git"
+  },
+  "dependencies": {
+    "@uwdata/flechette": "^2.2.0",
+    "eventsource": "^3.0.0"
+  },
+  "devDependencies": {
+    "playwright": "^1.50.0"
+  }
+}

package/src/consumer.js

@@ -0,0 +1,107 @@
+/**
+ * BoilStream SSE Consumer — real-time Arrow data streaming.
+ *
+ * Connects to a BoilStream SSE endpoint and decodes Arrow IPC events
+ * using flechette. Works in browsers (native EventSource) and Node.js
+ * (pass the `eventsource` polyfill).
+ *
+ * Reconnection with Last-Event-ID is handled automatically by EventSource.
+ *
+ * @example
+ * import { BoilStreamConsumer } from "@boilstream/consumer";
+ * import EventSource from "eventsource"; // Node.js only
+ *
+ * const consumer = new BoilStreamConsumer("https://host:8443/stream/{token}", {
+ *   onSchema: (schema) => console.log("Schema:", schema),
+ *   onBatch: (table, batchSeq) => console.log(`Batch ${batchSeq}: ${table.numRows} rows`),
+ *   onHeartbeat: () => {},
+ *   onError: (err) => console.error(err),
+ *   EventSource, // pass polyfill for Node.js; omit in browsers
+ * });
+ *
+ * // Later: disconnect
+ * consumer.close();
+ */
+
+import { decodeArrowIPC } from "./decoder.js";
+
+export class BoilStreamConsumer {
+  #url;
+  #callbacks;
+  #EventSourceImpl;
+  #es;
+  #schema;
+
+  /**
+   * @param {string} url - SSE endpoint URL (e.g. "https://host/stream/{token}")
+   * @param {Object} options
+   * @param {Function} [options.onSchema] - Called with flechette schema on schema events
+   * @param {Function} [options.onBatch] - Called with (flechette Table, batchSeq) on batch events
+   * @param {Function} [options.onHeartbeat] - Called on heartbeat events
+   * @param {Function} [options.onError] - Called with error on connection/decode errors
+   * @param {typeof EventSource} [options.EventSource] - EventSource implementation (required in Node.js)
+   */
+  constructor(url, options = {}) {
+    this.#url = url;
+    this.#callbacks = {
+      onSchema: options.onSchema,
+      onBatch: options.onBatch,
+      onHeartbeat: options.onHeartbeat,
+      onError: options.onError,
+    };
+    this.#EventSourceImpl = options.EventSource || globalThis.EventSource;
+    this.#schema = null;
+
+    if (!this.#EventSourceImpl) {
+      throw new Error(
+        "EventSource is not available. In Node.js, install and pass the `eventsource` package.",
+      );
+    }
+
+    this.#connect();
+  }
+
+  /** Current schema (null until first schema event). */
+  get schema() {
+    return this.#schema;
+  }
+
+  #connect() {
+    this.#es = new this.#EventSourceImpl(this.#url);
+
+    this.#es.addEventListener("schema", (event) => {
+      try {
+        const table = decodeArrowIPC(event.data);
+        this.#schema = table.schema;
+        this.#callbacks.onSchema?.(table.schema);
+      } catch (err) {
+        this.#callbacks.onError?.(err);
+      }
+    });
+
+    this.#es.addEventListener("batch", (event) => {
+      try {
+        const batchSeq = Number(event.lastEventId);
+        const table = decodeArrowIPC(event.data);
+        this.#callbacks.onBatch?.(table, batchSeq);
+      } catch (err) {
+        this.#callbacks.onError?.(err);
+      }
+    });
+
+    this.#es.addEventListener("heartbeat", () => {
+      this.#callbacks.onHeartbeat?.();
+    });
+
+    this.#es.onerror = (err) => {
+      this.#callbacks.onError?.(err);
+      // EventSource auto-reconnects with Last-Event-ID — no manual logic needed
+    };
+  }
+
+  /** Disconnect from the SSE stream. */
+  close() {
+    this.#es?.close();
+    this.#es = null;
+  }
+}

package/src/decoder.js

@@ -0,0 +1,20 @@
+/**
+ * Arrow IPC decoder — base64 SSE data to flechette Table.
+ *
+ * Works in both Node.js and browsers.
+ */
+
+import { tableFromIPC } from "@uwdata/flechette";
+
+/**
+ * Decode base64-encoded Arrow IPC stream into a flechette Table.
+ * @param {string} base64Data - Base64-encoded Arrow IPC stream bytes
+ * @returns {import("@uwdata/flechette").Table} Decoded Arrow table
+ */
+export function decodeArrowIPC(base64Data) {
+  const bytes =
+    typeof Buffer !== "undefined"
+      ? new Uint8Array(Buffer.from(base64Data, "base64"))
+      : Uint8Array.from(atob(base64Data), (c) => c.charCodeAt(0));
+  return tableFromIPC(bytes);
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { BoilStreamConsumer } from "./consumer.js";
+export { decodeArrowIPC } from "./decoder.js";