plasmite 0.3.0 → 0.5.0

package/README.md

@@ -21,67 +21,71 @@ toolchain or compile step needed.
 ### Local pools (native, in-process)
 
 ```js
-const { Client, Durability } = require("plasmite");
+const { Client, Durability, ErrorKind, PlasmiteNativeError } = 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()));
+let pool;
+try {
+  pool = client.pool("events", 64 * 1024 * 1024);
+
+  const msg = pool.append({ kind: "signup", user: "alice" }, ["user-event"], Durability.Flush);
+  console.log(msg.seq, msg.tags, msg.data);
+  // => 1n [ 'user-event' ] { kind: 'signup', user: 'alice' }
+
+  const fetched = pool.get(msg.seq);
+  console.log(fetched.data.user);
+  // => "alice"
+
+  try {
+    client.openPool("missing");
+  } catch (err) {
+    if (err instanceof PlasmiteNativeError && err.kind === ErrorKind.NotFound) {
+      console.log("pool not found");
+    } else {
+      throw err;
+    }
+  }
+} finally {
+  if (pool) pool.close();
+  client.close();
 }
-stream.close();
-
-pool.close();
-client.close();
 ```
 
+## Troubleshooting
+
+- **Missing pool directory**: pool creation creates parent directories automatically. If you call `openPool(...)` on a missing pool, catch `ErrorKind.NotFound` or use `client.pool(...)` to create-or-open.
+- **Permission denied**: choose a writable pool directory (`new Client("/path/to/pools")`) and verify directory permissions/ownership. Errors include `err.path` when available.
+
 ### Remote pools (HTTP/JSON)
 
-Connect to a plasmite server (`npx plasmite serve` or `pls serve`) to read
+Connect to a Plasmite server (`npx plasmite serve` or `pls serve`) to read
 and write pools over the network.
 
 ```js
 const { RemoteClient } = require("plasmite");
 
-const client = new RemoteClient("http://127.0.0.1:9700");
-// With auth: new RemoteClient("http://...", { token: "secret" })
+(async () => {
+  const client = new RemoteClient("http://127.0.0.1:9700");
+  // With auth: new RemoteClient("http://...", { token: "secret" })
 
-const pool = await client.openPool("events");
+  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
+  // Append — accepts plain objects, serialized as JSON for you
+  const message = await pool.append(
+    { kind: "deploy", sha: "abc123" },
+    ["ops"],
+  );
+  console.log(message.seq); // => 1n
 
-// Read by sequence number
-const got = await pool.get(1);
-console.log(got.data); // => { kind: "deploy", sha: "abc123" }
+  // 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();
+  // Tail — live-stream new messages (JSONL under the hood)
+  for await (const msg of pool.tail({ sinceSeq: 0, tags: ["ops"], maxMessages: 1 })) {
+    console.log(msg.seq, msg.tags, msg.data);
+  }
+})();
 ```
 
 ## API
@@ -90,19 +94,34 @@ tail.cancel();
 
 | Class | Method | Description |
 |---|---|---|
-| `Client(dir)` | | Open a pool directory |
+| `Client(dir?)` | | Open a pool directory (`~/.plasmite/pools` by default) |
 | | `.createPool(name, sizeBytes)` | Create a new pool (returns `Pool`) |
 | | `.openPool(name)` | Open an existing pool (returns `Pool`) |
+| | `.pool(name, sizeBytes?)` | Open if present, else create |
 | | `.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` |
+| | `[Symbol.dispose]()` | Alias for `.close()` (used by explicit resource-management syntax when enabled) |
+| `Module` | `.parseMessage(value)` | Normalize a raw envelope or `Message` into a typed `Message` |
+| | `.replay(pool, opts?)` | Backward-compatible replay wrapper (delegates to `pool.replay`) |
+| `Pool` | `.appendJson(payload, tags, durability)` | Append JSON payload (Buffer or JSON-serializable value); returns message envelope as `Buffer` |
+| | `.append(data, tags?, durability?)` | Append any JSON-serializable value; returns typed `Message` |
+| | `.appendLite3(buf, durability?)` | Append raw bytes (lite3 framing); returns sequence `bigint` |
+| | `.get(seq)` | Get message by sequence number; returns typed `Message` |
 | | `.getJson(seq)` | Get message by sequence number; returns `Buffer` |
 | | `.getLite3(seq)` | Get lite3 frame by sequence number |
+| | `.tail(opts?)` | Async generator of typed `Message` values with optional tag filter |
+| | `.replay(opts?)` | Async generator of typed `Message` values with speed/timing controls |
 | | `.openStream(sinceSeq?, max?, timeoutMs?)` | Open a message stream |
 | | `.openLite3Stream(sinceSeq?, max?, timeoutMs?)` | Open a lite3 frame stream |
 | | `.close()` | Close the pool |
+| | `[Symbol.dispose]()` | Alias for `.close()` (used by explicit resource-management syntax when enabled) |
 | `Stream` | `.nextJson()` | Next message as `Buffer`, or `null` at end |
+| | `[Symbol.iterator]()` | Iterate synchronously via `for...of` |
 | | `.close()` | Close the stream |
+| | `[Symbol.dispose]()` | Alias for `.close()` |
+| `Lite3Stream` | `.next()` | Next lite3 frame, or `null` at end |
+| | `[Symbol.iterator]()` | Iterate synchronously via `for...of` |
+| | `.close()` | Close the stream |
+| | `[Symbol.dispose]()` | Alias for `.close()` |
 
 **Durability** controls fsync behavior:
 - `Durability.Fast` — buffered writes (higher throughput)
@@ -123,19 +142,17 @@ Sequence numbers accept `number` or `bigint`.
 | | `.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(opts?)` | Live-tail typed messages (`AsyncGenerator<Message>`) |
 
 ### Tail options
 
 ```js
-await pool.tail({
+const options = {
   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)
-});
+};
 ```
 
 ### Error handling
@@ -144,10 +161,10 @@ Local operations throw `PlasmiteNativeError` with structured fields:
 
 ```js
 try {
-  pool.getJson(999n);
+  pool.get(999n);
 } catch (err) {
   if (err instanceof PlasmiteNativeError) {
-    console.log(err.kind);   // "NotFound"
+    console.log(err.kind === ErrorKind.NotFound); // true
     console.log(err.seq);    // 999
   }
 }
@@ -162,7 +179,7 @@ The package includes the `plasmite` CLI:
 
 ```bash
 npx plasmite --version
-npx plasmite serve ./data --port 9700
+npx plasmite --dir ./data serve --bind 127.0.0.1:9700
 ```
 
 ## TypeScript
@@ -174,11 +191,29 @@ needed.
 import { Client, Durability, Pool, RemoteClient } from "plasmite";
 ```
 
+For repo development, `npm test` runs:
+- native rebuild
+- `npm run check:type-surface` (runtime export ↔ `types.d.ts` drift check)
+- `node --test test/*.test.js` (includes conformance tests)
+
+Run the conformance runner directly:
+
+```bash
+cd bindings/node
+npm run build
+PLASMITE_LIB_DIR="$(pwd)/../../target/debug" \
+PLASMITE_BIN="$(pwd)/../../target/debug/plasmite" \
+node cmd/plasmite-conformance.js ../../conformance/sample-v0.json
+```
+
 ## Platform support
 
-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.
+Pre-built binaries are included for:
+- Linux: `x64`, `arm64`
+- macOS: `x64`, `arm64`
+- Windows: `x64`
+
+If your platform/architecture is not listed, install the SDK (`libplasmite`) and build from source.
 
 ## License