plasmite 0.1.8

package/README.md

@@ -0,0 +1,92 @@
+# Plasmite Node Bindings (v0)
+
+These bindings wrap the `libplasmite` C ABI via a N-API addon.
+
+## Installation
+
+Install from npm (canonical package name):
+
+```bash
+npm install plasmite
+```
+
+Published package artifacts bundle:
+- `index.node` N-API addon
+- `libplasmite.(dylib|so)` beside the addon
+- `plasmite` CLI binary exposed as `npx plasmite`
+
+For development/testing from this repo, see Build & Test below.
+
+## Build Requirements
+
+- Node 20+
+- Rust toolchain (for building the addon)
+- `libplasmite` built from this repo (`cargo build -p plasmite`)
+
+## Build & Test
+
+From the repo root:
+
+```bash
+cargo build -p plasmite
+```
+
+Canonical repo-root command:
+
+```bash
+just bindings-node-test
+```
+
+Equivalent manual command (from `bindings/node`):
+
+```bash
+PLASMITE_LIB_DIR="$(pwd)/../../target/debug" npm test
+```
+
+Pack/install smoke (ensures bundled assets work without env vars):
+
+```bash
+./scripts/node_pack_smoke.sh
+```
+
+## Usage
+
+```js
+const { Client, Durability } = require("plasmite")
+
+const client = new Client("./data")
+const pool = client.createPool("docs", 64 * 1024 * 1024)
+const payload = Buffer.from(JSON.stringify({ kind: "note", text: "hi" }))
+const message = pool.appendJson(payload, ["note"], Durability.Fast)
+console.log(message.toString("utf8"))
+
+const frame = pool.getLite3(BigInt(1))
+console.log(frame.payload.length)
+
+pool.close()
+client.close()
+```
+
+Local binding failures throw `PlasmiteNativeError` with structured metadata fields (`kind`, `path`, `seq`, `offset`) when available.
+
+## Remote Client (HTTP/JSON)
+
+```js
+const { RemoteClient } = require("plasmite")
+
+const client = new RemoteClient("http://127.0.0.1:9700")
+const pool = await client.openPool("docs")
+const message = await pool.append({ kind: "note", text: "hi" }, ["note"])
+console.log(message.seq, message.data)
+
+const tail = await pool.tail({
+  sinceSeq: message.seq,
+  tags: ["note"],
+  maxMessages: 1,
+  timeoutMs: 500,
+})
+console.log(await tail.next())
+tail.cancel()
+```
+
+`tail({ tags: [...] })` performs exact tag matching and composes with other filters via AND semantics.

package/bin/plasmite.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/*
+Purpose: Provide an npm bin entrypoint that runs the bundled plasmite CLI.
+Key Exports: CLI entrypoint only.
+Role: Ensure `npx plasmite` works from npm-installed package artifacts.
+Invariants: Uses packaged binary first, then falls back to PATH.
+Invariants: Forwards argv verbatim and propagates child exit status.
+Notes: Prints a concise error when no CLI binary is available.
+*/
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const bundled = path.join(packageRoot, "plasmite");
+const target = fs.existsSync(bundled) ? bundled : "plasmite";
+
+const result = spawnSync(target, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+  console.error(`plasmite: failed to execute ${target}: ${result.error.message}`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/index.d.ts

@@ -0,0 +1,48 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export const enum Durability {
+  Fast = 0,
+  Flush = 1
+}
+export const enum ErrorKind {
+  Internal = 1,
+  Usage = 2,
+  NotFound = 3,
+  AlreadyExists = 4,
+  Busy = 5,
+  Permission = 6,
+  Corrupt = 7,
+  Io = 8
+}
+export interface Lite3Frame {
+  seq: bigint
+  timestampNs: bigint
+  flags: number
+  payload: Buffer
+}
+export declare class Client {
+  constructor(poolDir: string)
+  createPool(poolRef: string, sizeBytes: number | bigint): Pool
+  openPool(poolRef: string): Pool
+  close(): void
+}
+export declare class Pool {
+  appendJson(payload: Buffer, tags: Array<string>, durability: Durability): Buffer
+  appendLite3(payload: Buffer, durability: Durability): bigint
+  getJson(seq: number | bigint): Buffer
+  getLite3(seq: number | bigint): Lite3Frame
+  openStream(sinceSeq?: number | bigint | undefined | null, maxMessages?: number | bigint | undefined | null, timeoutMs?: number | bigint | undefined | null): Stream
+  openLite3Stream(sinceSeq?: number | bigint | undefined | null, maxMessages?: number | bigint | undefined | null, timeoutMs?: number | bigint | undefined | null): Lite3Stream
+  close(): void
+}
+export declare class Stream {
+  nextJson(): Buffer | null
+  close(): void
+}
+export declare class Lite3Stream {
+  next(): Lite3Frame | null
+  close(): void
+}

package/index.js

@@ -0,0 +1,233 @@
+/*
+Purpose: JavaScript entry point for the Plasmite Node binding.
+Key Exports: Client, Pool, Stream, Durability, ErrorKind, replay.
+Role: Thin wrapper around the native N-API addon.
+Invariants: Exports align with native symbols and v0 API semantics.
+Notes: Requires libplasmite to be discoverable at runtime.
+*/
+
+const native = require("./index.node");
+const { RemoteClient, RemoteError, RemotePool, RemoteTail } = require("./remote");
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+class PlasmiteNativeError extends Error {
+  constructor(message, details = {}, cause = undefined) {
+    super(message);
+    this.name = "PlasmiteNativeError";
+    this.kind = details.kind;
+    this.path = details.path;
+    this.seq = details.seq;
+    this.offset = details.offset;
+    this.cause = cause;
+  }
+}
+
+function parseNativeError(err) {
+  if (!(err instanceof Error) || typeof err.message !== "string") {
+    return null;
+  }
+  const prefix = "plasmite error:";
+  if (!err.message.startsWith(prefix)) {
+    return null;
+  }
+  const parts = err.message
+    .slice(prefix.length)
+    .split(";")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) {
+    return null;
+  }
+  const details = {};
+  for (const part of parts) {
+    const [key, ...valueParts] = part.split("=");
+    if (!key || valueParts.length === 0) {
+      continue;
+    }
+    const value = valueParts.join("=");
+    if (key === "seq" || key === "offset") {
+      const parsed = Number(value);
+      details[key] = Number.isFinite(parsed) ? parsed : undefined;
+      continue;
+    }
+    details[key] = value;
+  }
+  return new PlasmiteNativeError(err.message, details, err);
+}
+
+function wrapNativeError(err) {
+  return parseNativeError(err) ?? err;
+}
+
+class Client {
+  constructor(poolDir) {
+    this._inner = new native.Client(poolDir);
+  }
+
+  createPool(poolRef, sizeBytes) {
+    try {
+      return new Pool(this._inner.createPool(poolRef, sizeBytes));
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  openPool(poolRef) {
+    try {
+      return new Pool(this._inner.openPool(poolRef));
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  close() {
+    this._inner.close();
+  }
+}
+
+class Pool {
+  constructor(inner) {
+    this._inner = inner;
+  }
+
+  appendJson(payload, tags, durability) {
+    try {
+      return this._inner.appendJson(payload, tags, durability);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  appendLite3(payload, durability) {
+    try {
+      return this._inner.appendLite3(payload, durability);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  getJson(seq) {
+    try {
+      return this._inner.getJson(seq);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  getLite3(seq) {
+    try {
+      return this._inner.getLite3(seq);
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  openStream(sinceSeq, maxMessages, timeoutMs) {
+    try {
+      return new Stream(this._inner.openStream(sinceSeq, maxMessages, timeoutMs));
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  openLite3Stream(sinceSeq, maxMessages, timeoutMs) {
+    try {
+      return new Lite3Stream(
+        this._inner.openLite3Stream(sinceSeq, maxMessages, timeoutMs),
+      );
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  close() {
+    this._inner.close();
+  }
+}
+
+class Stream {
+  constructor(inner) {
+    this._inner = inner;
+  }
+
+  nextJson() {
+    try {
+      return this._inner.nextJson();
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  close() {
+    this._inner.close();
+  }
+}
+
+class Lite3Stream {
+  constructor(inner) {
+    this._inner = inner;
+  }
+
+  next() {
+    try {
+      return this._inner.next();
+    } catch (err) {
+      throw wrapNativeError(err);
+    }
+  }
+
+  close() {
+    this._inner.close();
+  }
+}
+
+async function* replay(pool, options = {}) {
+  const { speed = 1.0, sinceSeq, maxMessages, timeoutMs } = options;
+  const stream = pool.openStream(
+    sinceSeq ?? null,
+    maxMessages ?? null,
+    timeoutMs ?? null,
+  );
+
+  const messages = [];
+  try {
+    let msg;
+    while ((msg = stream.nextJson()) !== null) {
+      messages.push(msg);
+    }
+  } finally {
+    stream.close();
+  }
+
+  let prevMs = null;
+  for (const msg of messages) {
+    const parsed = JSON.parse(msg);
+    const curMs = new Date(parsed.time).getTime();
+
+    if (prevMs !== null && speed > 0) {
+      const delay = (curMs - prevMs) / speed;
+      if (delay > 0) {
+        await sleep(delay);
+      }
+    }
+
+    prevMs = curMs;
+    yield msg;
+  }
+}
+
+module.exports = {
+  Client,
+  Pool,
+  Stream,
+  Lite3Stream,
+  Durability: native.Durability,
+  ErrorKind: native.ErrorKind,
+  PlasmiteNativeError,
+  RemoteClient,
+  RemoteError,
+  RemotePool,
+  RemoteTail,
+  replay,
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "plasmite",
+  "version": "0.1.8",
+  "description": "Persistent JSON message queues for Node.js - native bindings for local and remote IPC",
+  "license": "MIT",
+  "main": "index.js",
+  "types": "types.d.ts",
+  "bin": {
+    "plasmite": "bin/plasmite.js"
+  },
+  "files": [
+    "index.js",
+    "index.node",
+    "index.d.ts",
+    "types.d.ts",
+    "remote.js",
+    "bin/plasmite.js",
+    "libplasmite.dylib",
+    "libplasmite.so",
+    "plasmite"
+  ],
+  "keywords": [
+    "ipc",
+    "queue",
+    "json",
+    "messaging",
+    "pubsub",
+    "napi",
+    "native"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sandover/plasmite.git",
+    "directory": "bindings/node"
+  },
+  "scripts": {
+    "prepare-native": "node scripts/prepare_native_assets.js",
+    "build": "napi build --cargo-cwd native",
+    "test": "npm run build && node --test test/*.test.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "npm run build && npm run prepare-native",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0",
+    "@types/node": "^25.2.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/remote.js

@@ -0,0 +1,242 @@
+/*
+Purpose: Provide an HTTP/JSON RemoteClient for the Node binding.
+Key Exports: RemoteClient, RemotePool, RemoteTail, RemoteError.
+Role: JS-side remote access that mirrors the v0 server protocol.
+Invariants: Uses JSON request/response envelopes from spec/remote/v0.
+Invariants: Base URL must be http(s) without a path.
+Invariants: Tail streams are JSONL and can be canceled.
+*/
+
+const { Readable } = require("node:stream");
+const readline = require("node:readline");
+
+class RemoteError extends Error {
+  constructor(payload, status) {
+    const error = payload && payload.error ? payload.error : payload;
+    const message = error && error.message ? error.message : `Remote error ${status}`;
+    super(message);
+    this.name = "RemoteError";
+    this.status = status;
+    this.kind = error && error.kind ? error.kind : "Io";
+    this.hint = error && error.hint ? error.hint : undefined;
+    this.path = error && error.path ? error.path : undefined;
+    this.seq = error && error.seq ? error.seq : undefined;
+    this.offset = error && error.offset ? error.offset : undefined;
+  }
+}
+
+class RemoteClient {
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = normalizeBaseUrl(baseUrl);
+    this.token = options.token || null;
+  }
+
+  withToken(token) {
+    this.token = token;
+    return this;
+  }
+
+  async createPool(pool, sizeBytes) {
+    const payload = { pool, size_bytes: Number(sizeBytes) };
+    const url = buildUrl(this.baseUrl, ["v0", "pools"]);
+    const data = await this._requestJson("POST", url, payload);
+    return data.pool;
+  }
+
+  async openPool(pool) {
+    const payload = { pool };
+    const url = buildUrl(this.baseUrl, ["v0", "pools", "open"]);
+    await this._requestJson("POST", url, payload);
+    return new RemotePool(this, pool);
+  }
+
+  async poolInfo(pool) {
+    const url = buildUrl(this.baseUrl, ["v0", "pools", pool, "info"]);
+    const data = await this._requestJson("GET", url, null);
+    return data.pool;
+  }
+
+  async listPools() {
+    const url = buildUrl(this.baseUrl, ["v0", "pools"]);
+    const data = await this._requestJson("GET", url, null);
+    return data.pools;
+  }
+
+  async deletePool(pool) {
+    const url = buildUrl(this.baseUrl, ["v0", "pools", pool]);
+    await this._requestJson("DELETE", url, null);
+  }
+
+  async _requestJson(method, url, body) {
+    const headers = { Accept: "application/json" };
+    if (this.token) {
+      headers.Authorization = `Bearer ${this.token}`;
+    }
+    let payload;
+    if (method !== "GET" && method !== "DELETE") {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+
+    const response = await fetch(url.toString(), {
+      method,
+      headers,
+      body: payload,
+    });
+
+    if (!response.ok) {
+      throw await parseRemoteError(response);
+    }
+
+    if (response.status === 204) {
+      return null;
+    }
+    return response.json();
+  }
+
+  async _requestStream(url, controller) {
+    const headers = { Accept: "application/json" };
+    if (this.token) {
+      headers.Authorization = `Bearer ${this.token}`;
+    }
+
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      headers,
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw await parseRemoteError(response);
+    }
+
+    return response;
+  }
+}
+
+class RemotePool {
+  constructor(client, pool) {
+    this.client = client;
+    this.pool = pool;
+  }
+
+  poolRef() {
+    return this.pool;
+  }
+
+  async append(data, tags = [], durability = "fast") {
+    const payload = { data, tags, durability };
+    const url = buildUrl(this.client.baseUrl, ["v0", "pools", this.pool, "append"]);
+    const response = await this.client._requestJson("POST", url, payload);
+    return response.message;
+  }
+
+  async get(seq) {
+    const url = buildUrl(this.client.baseUrl, [
+      "v0",
+      "pools",
+      this.pool,
+      "messages",
+      String(seq),
+    ]);
+    const response = await this.client._requestJson("GET", url, null);
+    return response.message;
+  }
+
+  async tail(options = {}) {
+    const url = buildUrl(this.client.baseUrl, ["v0", "pools", this.pool, "tail"]);
+    if (options.sinceSeq !== undefined) {
+      url.searchParams.set("since_seq", String(options.sinceSeq));
+    }
+    if (options.maxMessages !== undefined) {
+      url.searchParams.set("max", String(options.maxMessages));
+    }
+    if (options.timeoutMs !== undefined) {
+      url.searchParams.set("timeout_ms", String(options.timeoutMs));
+    }
+    if (options.tags !== undefined) {
+      const tags = Array.isArray(options.tags) ? options.tags : [options.tags];
+      for (const tag of tags) {
+        url.searchParams.append("tag", String(tag));
+      }
+    }
+
+    const controller = new AbortController();
+    const response = await this.client._requestStream(url, controller);
+    return new RemoteTail(response, controller);
+  }
+}
+
+class RemoteTail {
+  constructor(response, controller) {
+    if (!response.body) {
+      throw new Error("remote tail response has no body");
+    }
+    this.controller = controller;
+    const stream = Readable.fromWeb(response.body);
+    this.reader = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    this.iterator = this.reader[Symbol.asyncIterator]();
+    this.done = false;
+  }
+
+  async next() {
+    if (this.done) {
+      return null;
+    }
+    const { value, done } = await this.iterator.next();
+    if (done) {
+      this.done = true;
+      return null;
+    }
+    if (!value || !value.trim()) {
+      return this.next();
+    }
+    return JSON.parse(value);
+  }
+
+  cancel() {
+    if (this.done) {
+      return;
+    }
+    this.done = true;
+    this.controller.abort();
+    this.reader.close();
+  }
+}
+
+function normalizeBaseUrl(raw) {
+  const url = new URL(raw);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("remote base URL must use http or https");
+  }
+  if (url.pathname && url.pathname !== "/") {
+    throw new Error("remote base URL must not include a path");
+  }
+  url.pathname = "/";
+  url.search = "";
+  url.hash = "";
+  return url;
+}
+
+function buildUrl(baseUrl, segments) {
+  const url = new URL(baseUrl.toString());
+  url.pathname = `/${segments.map((segment) => encodeURIComponent(segment)).join("/")}`;
+  return url;
+}
+
+async function parseRemoteError(response) {
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch (err) {
+    payload = null;
+  }
+  return new RemoteError(payload, response.status);
+}
+
+module.exports = {
+  RemoteClient,
+  RemotePool,
+  RemoteTail,
+  RemoteError,
+};

package/types.d.ts

@@ -0,0 +1,158 @@
+/*
+Purpose: Stable TypeScript declarations for the public Node bindings API.
+Key Exports: Client, Pool, Stream, Lite3Stream, replay, and remote client types.
+Role: Preserve complete JS + native type surface independently of generated files.
+Invariants: Public runtime exports from index.js are represented here.
+Invariants: Numeric sequence fields accept number or bigint input.
+Notes: Kept separate from NAPI-generated index.d.ts to avoid regeneration loss.
+*/
+
+export const enum Durability {
+  Fast = 0,
+  Flush = 1,
+}
+
+export const enum ErrorKind {
+  Internal = 1,
+  Usage = 2,
+  NotFound = 3,
+  AlreadyExists = 4,
+  Busy = 5,
+  Permission = 6,
+  Corrupt = 7,
+  Io = 8,
+}
+
+export interface Lite3Frame {
+  seq: bigint
+  timestampNs: bigint
+  flags: number
+  payload: Buffer
+}
+
+export class PlasmiteNativeError extends Error {
+  kind?: string
+  path?: string
+  seq?: number
+  offset?: number
+  cause?: unknown
+}
+
+export class Client {
+  constructor(poolDir: string)
+  createPool(poolRef: string, sizeBytes: number | bigint): Pool
+  openPool(poolRef: string): Pool
+  close(): void
+}
+
+export class Pool {
+  appendJson(payload: Buffer, tags: string[], durability: Durability): Buffer
+  appendLite3(payload: Buffer, durability: Durability): bigint
+  getJson(seq: number | bigint): Buffer
+  getLite3(seq: number | bigint): Lite3Frame
+  openStream(
+    sinceSeq?: number | bigint | null,
+    maxMessages?: number | bigint | null,
+    timeoutMs?: number | bigint | null,
+  ): Stream
+  openLite3Stream(
+    sinceSeq?: number | bigint | null,
+    maxMessages?: number | bigint | null,
+    timeoutMs?: number | bigint | null,
+  ): Lite3Stream
+  close(): void
+}
+
+export class Stream {
+  nextJson(): Buffer | null
+  close(): void
+}
+
+export class Lite3Stream {
+  next(): Lite3Frame | null
+  close(): void
+}
+
+export interface ReplayOptions {
+  speed?: number
+  sinceSeq?: number | bigint
+  maxMessages?: number | bigint
+  timeoutMs?: number | bigint
+}
+
+export function replay(
+  pool: Pool,
+  options?: ReplayOptions,
+): AsyncGenerator<Buffer, void, unknown>
+
+export interface RemoteClientOptions {
+  token?: string
+}
+
+export interface RemotePoolInfo {
+  pool: string
+  path: string
+  file_size: number
+  ring_size: number
+  bounds: {
+    oldest_seq: number | null
+    newest_seq: number | null
+  }
+  write_cursor: number
+  index_inline: boolean
+}
+
+export interface RemoteMessage {
+  seq: number
+  time: string
+  data: unknown
+  meta?: {
+    tags?: string[]
+  }
+}
+
+export interface RemoteTailOptions {
+  sinceSeq?: number | bigint
+  maxMessages?: number | bigint
+  timeoutMs?: number
+}
+
+export class RemoteError extends Error {
+  status: number
+  kind: string
+  hint?: string
+  path?: string
+  seq?: number
+  offset?: number
+}
+
+export class RemoteClient {
+  constructor(baseUrl: string, options?: RemoteClientOptions)
+  baseUrl: URL
+  token: string | null
+  withToken(token: string): RemoteClient
+  createPool(pool: string, sizeBytes: number | bigint): Promise<string>
+  openPool(pool: string): Promise<RemotePool>
+  poolInfo(pool: string): Promise<RemotePoolInfo>
+  listPools(): Promise<string[]>
+  deletePool(pool: string): Promise<void>
+}
+
+export class RemotePool {
+  constructor(client: RemoteClient, pool: string)
+  client: RemoteClient
+  pool: string
+  poolRef(): string
+  append(
+    data: unknown,
+    tags?: string[],
+    durability?: "fast" | "flush",
+  ): Promise<RemoteMessage>
+  get(seq: number | bigint): Promise<RemoteMessage>
+  tail(options?: RemoteTailOptions): Promise<RemoteTail>
+}
+
+export class RemoteTail {
+  next(): Promise<RemoteMessage | null>
+  cancel(): void
+}