sikiopipe 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# SikioPipe
+
+![NPM Version](https://img.shields.io/npm/v/sikiopipe?style=flat-square&color=blue) ![License](https://img.shields.io/github/license/leiko57/SikioPipe?style=flat-square) ![TypeScript](https://img.shields.io/badge/built_with-TypeScript-3178c6?style=flat-square) ![Targets](https://img.shields.io/badge/targets-web%20workers%20%7C%20worker_threads-purple?style=flat-square) ![Size](https://img.shields.io/bundlephobia/minzip/sikiopipe?style=flat-square&label=minzipped)
+
+Zero‑copy‑ish IPC & RPC between Web Workers and Node.js `worker_threads` with a SharedArrayBuffer + Atomics fast path and `postMessage` fallback.
+
+## Features
+
+- **SAB + Atomics fast path**: Uses SharedArrayBuffer-backed SPSC rings with a pooled block allocator when eligible.
+- **Fallback transport**: Falls back to `postMessage` when SAB isn’t available or allowed.
+- **Channels**: Send raw `Uint8Array` frames, with borrowed receives for low-copy hot paths.
+- **RPC**: Type-safe-ish remote proxies (`rpc(conn).wrap<T>()`) with a tiny server (`rpc(conn).expose(...)`).
+- **Streaming RPC**: `AsyncIterable<Uint8Array>` arguments and return values are streamed with backpressure.
+- **Configurable**: `mode`, `blockSize`, `blockCount`, handshake timeout, ping intervals.
+
+## Installation
+
+```bash
+npm i sikiopipe
+```
+
+or
+
+```bash
+pnpm add sikiopipe
+```
+
+or
+
+```bash
+yarn add sikiopipe
+```
+
+## Quick Start
+
+### Node.js (`worker_threads`)
+
+`main.ts`
+
+```ts
+import { spawnWorker, rpc } from "sikiopipe/node";
+
+type Api = {
+  add(a: number, b: number): number;
+};
+
+const conn = await spawnWorker(new URL("./worker.js", import.meta.url));
+const api = rpc(conn).wrap<Api>();
+
+console.log(await api.add(1, 2));
+
+conn.close();
+await conn.terminate();
+```
+
+`worker.js`
+
+```ts
+import { acceptConnection, rpc } from "sikiopipe/node";
+
+const conn = await acceptConnection();
+rpc(conn).expose({
+  add(a: number, b: number) {
+    return a + b;
+  },
+});
+```
+
+### Browser (Web Workers)
+
+`main.ts`
+
+```ts
+import { getSabEligibility, rpc, spawnWorker } from "sikiopipe/browser";
+
+console.log(getSabEligibility());
+
+type Api = {
+  ping(): string;
+};
+
+const conn = await spawnWorker(new URL("./worker.js", import.meta.url));
+const api = rpc(conn).wrap<Api>();
+
+console.log(await api.ping());
+
+conn.close();
+await conn.terminate();
+```
+
+`worker.js`
+
+```ts
+import { acceptConnection, rpc } from "sikiopipe/browser";
+
+const conn = await acceptConnection();
+rpc(conn).expose({
+  ping() {
+    return "pong";
+  },
+});
+```
+
+## Transports
+
+| Mode | Behavior | Notes |
+|------|----------|-------|
+| `auto` | Selects SAB when eligible, otherwise `postMessage` | Default |
+| `sab` | Forces SAB transport | In browsers requires COOP/COEP (cross-origin isolation) |
+| `postMessage` | Forces `postMessage` transport | Always available |
+
+## Zero-copy-ish data path
+
+Borrowed receive (avoid per-message `slice()` allocations):
+
+```ts
+import { channel } from "sikiopipe";
+
+const ch = channel(conn);
+
+for await (const chunk of ch.recvBorrowed()) {
+  try {
+    onBytes(chunk.bytes);
+  } finally {
+    chunk.release();
+  }
+}
+```
+
+Transfer-backed send (only on `postMessage` transport):
+
+```ts
+import { channel, createTransferPayload } from "sikiopipe";
+
+const ch = channel(conn);
+
+const data = new Uint8Array([1, 2, 3]);
+const { payload } = createTransferPayload(data.byteLength);
+payload.set(data);
+
+await ch.sendTransfer(payload);
+```
+
+## Building from Source
+
+```bash
+npm install
+npm run build
+```
+
+## Contributing
+
+Found a bug or have a feature request? Open an [Issue](https://github.com/leiko57/SikioPipe/issues/new).
+PRs are welcome!
+
+## License
+
+This project is licensed under AGPLv3 (`AGPL-3.0-only`).
+
+

package/dist/channel/channel.d.ts

@@ -0,0 +1,27 @@
+import type { Connection } from "../endpoint/connection.js";
+export type BorrowedChunk = {
+    readonly bytes: Uint8Array;
+    release(): void;
+};
+export type TransferPayload = {
+    readonly buffer: ArrayBuffer;
+    readonly payload: Uint8Array;
+};
+export type ChannelOptions = {};
+export type Channel = {
+    send(bytes: Uint8Array, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    sendTransfer(bytes: Uint8Array, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    recv(opts?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array>;
+    recvBorrowed(opts?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<BorrowedChunk>;
+};
+export declare function createTransferPayload(byteLength: number): TransferPayload;
+export declare function channel(_conn: Connection, _opts?: ChannelOptions): Channel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/channel/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAI5D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,EAAE,CAAC;AAEhC,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACjE,YAAY,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;CAC7E,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAKzE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,GAAE,cAAmB,GAAG,OAAO,CAqD9E"}

package/dist/channel/channel.js

@@ -0,0 +1,63 @@
+import { HEADER_BYTES } from "../protocol/header.js";
+import { MessageKind } from "../protocol/kinds.js";
+export function createTransferPayload(byteLength) {
+    if (!Number.isInteger(byteLength) || byteLength < 0)
+        throw new RangeError("Invalid byteLength");
+    const buffer = new ArrayBuffer(HEADER_BYTES + byteLength);
+    const payload = new Uint8Array(buffer, HEADER_BYTES, byteLength);
+    return { buffer, payload };
+}
+export function channel(_conn, _opts = {}) {
+    return {
+        async send(bytes, opts) {
+            await _conn.router.send({
+                kind: MessageKind.Data,
+                id: 0,
+                streamId: 0,
+                flags: 0,
+                aux: 0,
+                payload: bytes,
+            }, opts);
+        },
+        async sendTransfer(bytes, opts) {
+            const transport = _conn.transport;
+            if (typeof transport.sendTransfer !== "function")
+                throw new Error("sendTransfer is not supported");
+            if (!(bytes.buffer instanceof ArrayBuffer))
+                throw new RangeError("Transfer payload must use ArrayBuffer");
+            if (bytes.byteOffset !== HEADER_BYTES)
+                throw new RangeError("Invalid transfer payload offset");
+            if (bytes.byteLength > transport.payloadCapacity)
+                throw new RangeError("Frame too large");
+            if (bytes.buffer.byteLength < HEADER_BYTES + bytes.byteLength)
+                throw new RangeError("Invalid transfer buffer");
+            await transport.sendTransfer({
+                kind: MessageKind.Data,
+                id: 0,
+                streamId: 0,
+                flags: 0,
+                aux: 0,
+                payload: bytes,
+            }, bytes.buffer, opts);
+        },
+        async *recv(opts) {
+            for await (const frame of _conn.router.recv(MessageKind.Data, opts)) {
+                try {
+                    yield frame.payload.slice();
+                }
+                finally {
+                    frame.release();
+                }
+            }
+        },
+        async *recvBorrowed(opts) {
+            for await (const frame of _conn.router.recv(MessageKind.Data, opts)) {
+                yield {
+                    bytes: frame.payload,
+                    release: frame.release,
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=channel.js.map

package/dist/channel/channel.js.map

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

package/dist/endpoint/connection.d.ts

@@ -0,0 +1,42 @@
+import { type Transport, type TransportKind } from "../transport/createTransport.js";
+import { FrameRouter } from "./router.js";
+export type ConnectOptions = {
+    mode?: "auto" | "sab" | "postMessage";
+    blockSize?: number;
+    blockCount?: number;
+    handshakeTimeoutMs?: number;
+    pingIntervalMs?: number;
+    pingTimeoutMs?: number;
+};
+export type Connection = {
+    readonly role: "client" | "server";
+    readonly transportKind: TransportKind;
+    readonly transport: Transport;
+    readonly router: FrameRouter;
+    close(reason?: string): void;
+};
+export declare function isNodeLike(): boolean;
+export declare function isBrowser(): boolean;
+type WorkerLike = {
+    postMessage(value: unknown, transfer?: readonly unknown[]): void;
+    addEventListener?: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void;
+    removeEventListener?: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions) => void;
+    on?: (event: "message", listener: (value: unknown) => void) => void;
+    off?: (event: "message", listener: (value: unknown) => void) => void;
+};
+type PortLike = {
+    postMessage(value: unknown, transfer?: readonly unknown[]): void;
+    start?: () => void;
+    close?: () => void;
+    ref?: () => void;
+    unref?: () => void;
+    addEventListener?: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => void;
+    removeEventListener?: (type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions) => void;
+    on?: (event: "message", listener: (value: unknown) => void) => void;
+    off?: (event: "message", listener: (value: unknown) => void) => void;
+};
+export declare function connectToWorkerLike(worker: WorkerLike, opts: ConnectOptions): Promise<Connection>;
+export declare function acceptConnection(opts?: ConnectOptions): Promise<Connection>;
+export declare function connect(port: PortLike, opts?: ConnectOptions): Promise<Connection>;
+export {};
+//# sourceMappingURL=connection.d.ts.map

package/dist/endpoint/connection.d.ts.map

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