plasmite 0.1.8 → 0.1.13

package/README.md

@@ -1,92 +1,198 @@
-# Plasmite Node Bindings (v0)
+# plasmite
 
-These bindings wrap the `libplasmite` C ABI via a N-API addon.
+Persistent JSON message queues for Node.js. No broker, no daemon — just files on disk.
 
-## Installation
+Plasmite gives you fast, crash-safe, disk-backed ring buffers ("pools") that
+multiple processes can read and write concurrently. Use it for IPC, event
+sourcing, job queues, or anywhere you'd reach for Redis but don't want to run
+a server.
 
-Install from npm (canonical package name):
+## Install
 
 ```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`
+Requires Node 20+. The package ships pre-built native binaries — no Rust
+toolchain or compile step needed.
 
-For development/testing from this repo, see Build & Test below.
+## Quick start
 
-## Build Requirements
+### Local pools (native, in-process)
 
-- Node 20+
-- Rust toolchain (for building the addon)
-- `libplasmite` built from this repo (`cargo build -p plasmite`)
+```js
+const { Client, Durability } = require("plasmite");
+
+// Open a client pointed at a directory (created if it doesn't exist)
+const client = new Client("./data");
+
+// Create a 64 MB pool called "events"
+const pool = client.createPool("events", 64 * 1024 * 1024);
+
+// Append a JSON message with tags
+pool.appendJson(
+  Buffer.from(JSON.stringify({ kind: "signup", user: "alice" })),
+  ["user-event"],
+  Durability.Flush,
+);
+
+// Read it back by sequence number
+const msg = pool.getJson(1n);
+console.log(JSON.parse(msg.toString()));
+// => { kind: "signup", user: "alice" }
+
+// Stream messages as they arrive
+const stream = pool.openStream();
+let frame;
+while ((frame = stream.nextJson()) !== null) {
+  console.log(JSON.parse(frame.toString()));
+}
+stream.close();
+
+pool.close();
+client.close();
+```
 
-## Build & Test
+### Remote pools (HTTP/JSON)
 
-From the repo root:
+Connect to a plasmite server (`npx plasmite serve` or `pls serve`) to read
+and write pools over the network.
 
-```bash
-cargo build -p plasmite
+```js
+const { RemoteClient } = require("plasmite");
+
+const client = new RemoteClient("http://127.0.0.1:9700");
+// With auth: new RemoteClient("http://...", { token: "secret" })
+
+const pool = await client.openPool("events");
+
+// Append — accepts plain objects, serialized as JSON for you
+const message = await pool.append(
+  { kind: "deploy", sha: "abc123" },
+  ["ops"],
+);
+console.log(message.seq); // => 1
+
+// Read by sequence number
+const got = await pool.get(1);
+console.log(got.data); // => { kind: "deploy", sha: "abc123" }
+
+// Tail — live-stream new messages (JSONL under the hood)
+const tail = await pool.tail({ sinceSeq: 0, tags: ["ops"] });
+const next = await tail.next(); // resolves on next matching message
+console.log(next);
+tail.cancel();
 ```
 
-Canonical repo-root command:
+## API
+
+### Local client
+
+| Class | Method | Description |
+|---|---|---|
+| `Client(dir)` | | Open a pool directory |
+| | `.createPool(name, sizeBytes)` | Create a new pool (returns `Pool`) |
+| | `.openPool(name)` | Open an existing pool (returns `Pool`) |
+| | `.close()` | Release resources |
+| `Pool` | `.appendJson(buf, tags, durability)` | Append a JSON message; returns the stored envelope as `Buffer` |
+| | `.appendLite3(buf, durability)` | Append raw bytes (lite3 framing); returns sequence `bigint` |
+| | `.getJson(seq)` | Get message by sequence number; returns `Buffer` |
+| | `.getLite3(seq)` | Get lite3 frame by sequence number |
+| | `.openStream(sinceSeq?, max?, timeoutMs?)` | Open a message stream |
+| | `.openLite3Stream(sinceSeq?, max?, timeoutMs?)` | Open a lite3 frame stream |
+| | `.close()` | Close the pool |
+| `Stream` | `.nextJson()` | Next message as `Buffer`, or `null` at end |
+| | `.close()` | Close the stream |
+
+**Durability** controls fsync behavior:
+- `Durability.Fast` — buffered writes (higher throughput)
+- `Durability.Flush` — fsync after write (crash-safe)
+
+Sequence numbers accept `number` or `bigint`.
+
+### Remote client
+
+| Class | Method | Description |
+|---|---|---|
+| `RemoteClient(url, opts?)` | | Connect to a plasmite server |
+| | `.withToken(token)` | Set bearer token (returns `this`) |
+| | `.createPool(name, sizeBytes)` | Create a pool on the server |
+| | `.openPool(name)` | Open a remote pool (returns `RemotePool`) |
+| | `.poolInfo(name)` | Get pool metadata |
+| | `.listPools()` | List all pools |
+| | `.deletePool(name)` | Delete a pool |
+| `RemotePool` | `.append(data, tags?, durability?)` | Append a message (data is any JSON-serializable value) |
+| | `.get(seq)` | Get a message by sequence number |
+| | `.tail(opts?)` | Live-tail messages (returns `RemoteTail`) |
+| `RemoteTail` | `.next()` | Await next message (resolves to message or `null`) |
+| | `.cancel()` | Stop the tail stream |
+
+### Tail options
 
-```bash
-just bindings-node-test
+```js
+await pool.tail({
+  sinceSeq: 0,         // start after this sequence number
+  maxMessages: 100,    // stop after N messages
+  timeoutMs: 5000,     // stop after N ms of inactivity
+  tags: ["signup"],    // filter by exact tag match (AND across tags)
+});
 ```
 
-Equivalent manual command (from `bindings/node`):
+### Error handling
 
-```bash
-PLASMITE_LIB_DIR="$(pwd)/../../target/debug" npm test
+Local operations throw `PlasmiteNativeError` with structured fields:
+
+```js
+try {
+  pool.getJson(999n);
+} catch (err) {
+  if (err instanceof PlasmiteNativeError) {
+    console.log(err.kind);   // "NotFound"
+    console.log(err.seq);    // 999
+  }
+}
 ```
 
-Pack/install smoke (ensures bundled assets work without env vars):
+Remote operations throw `RemoteError` with `status`, `kind`, and optional
+`hint`.
+
+### CLI
+
+The package includes the `plasmite` CLI:
 
 ```bash
-./scripts/node_pack_smoke.sh
+npx plasmite --version
+npx plasmite serve ./data --port 9700
 ```
 
-## Usage
+## TypeScript
 
-```js
-const { Client, Durability } = require("plasmite")
+Type declarations ship with the package (`types.d.ts`). No `@types/` install
+needed.
 
-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"))
+```ts
+import { Client, Durability, Pool, RemoteClient } from "plasmite";
+```
 
-const frame = pool.getLite3(BigInt(1))
-console.log(frame.payload.length)
+## Platform support
 
-pool.close()
-client.close()
-```
+Pre-built binaries are included for Linux x86_64. macOS and Windows users
+should install via Homebrew (`brew install sandover/tap/plasmite`) or build
+from source.
 
-Local binding failures throw `PlasmiteNativeError` with structured metadata fields (`kind`, `path`, `seq`, `offset`) when available.
+## Contributing
 
-## Remote Client (HTTP/JSON)
+Development requires a Rust toolchain to build the native addon:
 
-```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()
+```bash
+# From the repo root
+cargo build -p plasmite
+cd bindings/node && PLASMITE_LIB_DIR=../../target/debug npm test
 ```
 
-`tail({ tags: [...] })` performs exact tag matching and composes with other filters via AND semantics.
+See the [main repo](https://github.com/sandover/plasmite) for full build
+instructions.
+
+## License
+
+MIT

package/bin/plasmite.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /*
-Purpose: Provide an npm bin entrypoint that runs the bundled plasmite CLI.
+Purpose: Provide an npm bin entrypoint that runs the packaged platform CLI binary.
 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: Resolves CLI from native/{platform}/ for supported platforms.
 Invariants: Forwards argv verbatim and propagates child exit status.
 Notes: Prints a concise error when no CLI binary is available.
 */
@@ -12,9 +12,32 @@ const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 
+const PLATFORM_DIRS = Object.freeze({
+  linux: Object.freeze({ x64: "linux-x64" }),
+  darwin: Object.freeze({ x64: "darwin-x64", arm64: "darwin-arm64" }),
+});
+
+function resolvePlatformDir() {
+  const byArch = PLATFORM_DIRS[process.platform];
+  if (!byArch) {
+    return null;
+  }
+  return byArch[process.arch] ?? null;
+}
+
 const packageRoot = path.resolve(__dirname, "..");
-const bundled = path.join(packageRoot, "plasmite");
-const target = fs.existsSync(bundled) ? bundled : "plasmite";
+const platformDir = resolvePlatformDir();
+const target = platformDir
+  ? path.join(packageRoot, "native", platformDir, "plasmite")
+  : null;
+
+if (!target || !fs.existsSync(target)) {
+  console.error(
+    `plasmite: native CLI is unavailable for ${process.platform}-${process.arch}. ` +
+      "This package supports remote-only mode without native binaries on unsupported platforms.",
+  );
+  process.exit(1);
+}
 
 const result = spawnSync(target, process.argv.slice(2), { stdio: "inherit" });
 if (result.error) {

package/index.js

@@ -6,10 +6,55 @@ 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));
+const path = require("node:path");
+
+const PLATFORM_DIRS = Object.freeze({
+  linux: Object.freeze({ x64: "linux-x64" }),
+  darwin: Object.freeze({ x64: "darwin-x64", arm64: "darwin-arm64" }),
+});
+
+function resolvePlatformDir() {
+  const byArch = PLATFORM_DIRS[process.platform];
+  if (!byArch) {
+    return null;
+  }
+  return byArch[process.arch] ?? null;
+}
+
+function resolveNativeAddonPath() {
+  const platformDir = resolvePlatformDir();
+  if (!platformDir) {
+    return null;
+  }
+  return path.join(__dirname, "native", platformDir, "index.node");
+}
+
+let native = null;
+let nativeLoadError = null;
+let nativeAddonPath = null;
+
+try {
+  nativeAddonPath = resolveNativeAddonPath();
+  if (nativeAddonPath) {
+    native = require(nativeAddonPath);
+  } else {
+    nativeLoadError = new Error(`unsupported platform: ${process.platform}-${process.arch}`);
+  }
+} catch (err) {
+  nativeLoadError = err;
+}
+
+function makeNativeUnavailableError() {
+  const reason = nativeLoadError instanceof Error ? nativeLoadError.message : "unknown load error";
+  return new Error(
+    `plasmite native addon is unavailable for ${process.platform}-${process.arch} (${reason}). ` +
+      `expected addon path: ${nativeAddonPath ?? "unsupported platform"}. ` +
+      "RemoteClient remains supported without native artifacts.",
+  );
+}
 
 class PlasmiteNativeError extends Error {
   constructor(message, details = {}, cause = undefined) {
@@ -62,6 +107,9 @@ function wrapNativeError(err) {
 
 class Client {
   constructor(poolDir) {
+    if (!native) {
+      throw makeNativeUnavailableError();
+    }
     this._inner = new native.Client(poolDir);
   }
 
@@ -88,6 +136,9 @@ class Client {
 
 class Pool {
   constructor(inner) {
+    if (!native) {
+      throw makeNativeUnavailableError();
+    }
     this._inner = inner;
   }
 
@@ -148,6 +199,9 @@ class Pool {
 
 class Stream {
   constructor(inner) {
+    if (!native) {
+      throw makeNativeUnavailableError();
+    }
     this._inner = inner;
   }
 
@@ -166,6 +220,9 @@ class Stream {
 
 class Lite3Stream {
   constructor(inner) {
+    if (!native) {
+      throw makeNativeUnavailableError();
+    }
     this._inner = inner;
   }
 
@@ -222,8 +279,8 @@ module.exports = {
   Pool,
   Stream,
   Lite3Stream,
-  Durability: native.Durability,
-  ErrorKind: native.ErrorKind,
+  Durability: native ? native.Durability : Object.freeze({}),
+  ErrorKind: native ? native.ErrorKind : Object.freeze({}),
   PlasmiteNativeError,
   RemoteClient,
   RemoteError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plasmite",
-  "version": "0.1.8",
+  "version": "0.1.13",
   "description": "Persistent JSON message queues for Node.js - native bindings for local and remote IPC",
   "license": "MIT",
   "main": "index.js",
@@ -10,14 +10,13 @@
   },
   "files": [
     "index.js",
-    "index.node",
     "index.d.ts",
     "types.d.ts",
     "remote.js",
     "bin/plasmite.js",
-    "libplasmite.dylib",
-    "libplasmite.so",
-    "plasmite"
+    "native/linux-x64/**",
+    "native/darwin-x64/**",
+    "native/darwin-arm64/**"
   ],
   "keywords": [
     "ipc",