plasmite 0.2.0 → 0.5.0

package/index.js

@@ -1,15 +1,18 @@
 /*
 Purpose: JavaScript entry point for the Plasmite Node binding.
-Key Exports: Client, Pool, Stream, Durability, ErrorKind, replay.
+Key Exports: Client, Pool, Message, 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 { RemoteClient, RemoteError, RemotePool, RemoteTail } = require("./remote");
+const { RemoteClient, RemoteError, RemotePool } = require("./remote");
+const { Message, parseMessage } = require("./message");
+const { ERROR_KIND_VALUES, mapErrorKind } = require("./mappings");
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const path = require("node:path");
+const os = require("node:os");
 
 const PLATFORM_DIRS = Object.freeze({
   linux: Object.freeze({ x64: "linux-x64", arm64: "linux-arm64" }),
@@ -33,6 +36,9 @@ function resolveNativeAddonPath() {
   return path.join(__dirname, "native", platformDir, "index.node");
 }
 
+const DEFAULT_POOL_DIR = path.join(os.homedir(), ".plasmite", "pools");
+const DEFAULT_POOL_SIZE = 1024 * 1024;
+const DEFAULT_POOL_SIZE_BYTES = DEFAULT_POOL_SIZE;
 let native = null;
 let nativeLoadError = null;
 let nativeAddonPath = null;
@@ -48,6 +54,9 @@ try {
   nativeLoadError = err;
 }
 
+const Durability = native ? native.Durability : Object.freeze({ Fast: 0, Flush: 1 });
+const ErrorKind = native ? native.ErrorKind : ERROR_KIND_VALUES;
+
 function makeNativeUnavailableError() {
   const reason = nativeLoadError instanceof Error ? nativeLoadError.message : "unknown load error";
   return new Error(
@@ -97,8 +106,15 @@ function parseNativeError(err) {
       details[key] = Number.isFinite(parsed) ? parsed : undefined;
       continue;
     }
+    if (key === "kind") {
+      details.kind = mapErrorKind(value);
+      continue;
+    }
     details[key] = value;
   }
+  if (details.kind === undefined) {
+    details.kind = ErrorKind.Io;
+  }
   return new PlasmiteNativeError(err.message, details, err);
 }
 
@@ -106,15 +122,33 @@ function wrapNativeError(err) {
   return parseNativeError(err) ?? err;
 }
 
+function isNativeNotFoundError(err) {
+  if (!(err instanceof PlasmiteNativeError)) {
+    return false;
+  }
+  return err.kind === ErrorKind.NotFound;
+}
+
 class Client {
-  constructor(poolDir) {
+  /**
+   * Create a local client bound to a pool directory.
+   * @param {string} [poolDir]
+   * @returns {Client}
+   */
+  constructor(poolDir = DEFAULT_POOL_DIR) {
     if (!native) {
       throw makeNativeUnavailableError();
     }
     this._inner = new native.Client(poolDir);
   }
 
-  createPool(poolRef, sizeBytes) {
+  /**
+   * Create a new pool.
+   * @param {string} poolRef
+   * @param {number|bigint} [sizeBytes]
+   * @returns {Pool}
+   */
+  createPool(poolRef, sizeBytes = DEFAULT_POOL_SIZE_BYTES) {
     try {
       return new Pool(this._inner.createPool(poolRef, sizeBytes));
     } catch (err) {
@@ -122,6 +156,11 @@ class Client {
     }
   }
 
+  /**
+   * Open an existing pool.
+   * @param {string} poolRef
+   * @returns {Pool}
+   */
   openPool(poolRef) {
     try {
       return new Pool(this._inner.openPool(poolRef));
@@ -130,12 +169,41 @@ class Client {
     }
   }
 
+  /**
+   * Open a pool if it exists, otherwise create it.
+   * @param {string} poolRef
+   * @param {number|bigint} [sizeBytes]
+   * @returns {Pool}
+   */
+  pool(poolRef, sizeBytes = DEFAULT_POOL_SIZE_BYTES) {
+    try {
+      return this.openPool(poolRef);
+    } catch (err) {
+      if (isNativeNotFoundError(err)) {
+        return this.createPool(poolRef, sizeBytes);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Close the client handle.
+   * @returns {void}
+   */
   close() {
     this._inner.close();
   }
+
+  [Symbol.dispose]() {
+    this.close();
+  }
 }
 
 class Pool {
+  /**
+   * @param {object} inner
+   * @returns {Pool}
+   */
   constructor(inner) {
     if (!native) {
       throw makeNativeUnavailableError();
@@ -143,22 +211,54 @@ class Pool {
     this._inner = inner;
   }
 
+  /**
+   * Append JSON bytes and return raw message bytes.
+   * @param {unknown} payload
+   * @param {string[]} [tags]
+   * @param {number} [durability]
+   * @returns {Buffer}
+   */
   appendJson(payload, tags, durability) {
+    const input = Buffer.isBuffer(payload)
+      ? payload
+      : Buffer.from(JSON.stringify(payload));
     try {
-      return this._inner.appendJson(payload, tags, durability);
+      return this._inner.appendJson(input, tags ?? [], durability ?? Durability.Fast);
     } catch (err) {
       throw wrapNativeError(err);
     }
   }
 
+  /**
+   * Append payload and return parsed Message.
+   * @param {unknown} payload
+   * @param {string[]} [tags]
+   * @param {number} [durability]
+   * @returns {Message}
+   */
+  append(payload, tags, durability) {
+    return parseMessage(this.appendJson(payload, tags, durability));
+  }
+
+  /**
+   * Append a Lite3 frame payload.
+   * @param {Buffer} payload
+   * @param {number} [durability]
+   * @returns {bigint}
+   */
   appendLite3(payload, durability) {
     try {
-      return this._inner.appendLite3(payload, durability);
+      return this._inner.appendLite3(payload, durability ?? Durability.Fast);
     } catch (err) {
       throw wrapNativeError(err);
     }
   }
 
+  /**
+   * Get raw message bytes by sequence.
+   * @param {number|bigint} seq
+   * @returns {Buffer}
+   */
   getJson(seq) {
     try {
       return this._inner.getJson(seq);
@@ -167,14 +267,35 @@ class Pool {
     }
   }
 
+  /**
+   * Get parsed Message by sequence.
+   * @param {number|bigint} seq
+   * @returns {Message}
+   */
+  get(seq) {
+    return parseMessage(this.getJson(seq));
+  }
+
+  /**
+   * Get Lite3 frame by sequence.
+   * @param {number|bigint} seq
+   * @returns {import("./types").Lite3Frame}
+   */
   getLite3(seq) {
     try {
-      return this._inner.getLite3(seq);
+      return decorateLite3Frame(this._inner.getLite3(seq));
     } catch (err) {
       throw wrapNativeError(err);
     }
   }
 
+  /**
+   * Open a raw JSON stream.
+   * @param {number|bigint|null} sinceSeq
+   * @param {number|bigint|null} maxMessages
+   * @param {number|bigint|null} timeoutMs
+   * @returns {Stream}
+   */
   openStream(sinceSeq, maxMessages, timeoutMs) {
     try {
       return new Stream(this._inner.openStream(sinceSeq, maxMessages, timeoutMs));
@@ -183,6 +304,13 @@ class Pool {
     }
   }
 
+  /**
+   * Open a raw Lite3 stream.
+   * @param {number|bigint|null} sinceSeq
+   * @param {number|bigint|null} maxMessages
+   * @param {number|bigint|null} timeoutMs
+   * @returns {Lite3Stream}
+   */
   openLite3Stream(sinceSeq, maxMessages, timeoutMs) {
     try {
       return new Lite3Stream(
@@ -193,12 +321,217 @@ class Pool {
     }
   }
 
+  /**
+   * Tail parsed messages with optional filtering.
+   * @param {{sinceSeq?: number|bigint, maxMessages?: number|bigint, timeoutMs?: number|bigint, tags?: string[]}} [options]
+   * @returns {AsyncGenerator<Message, void, unknown>}
+   */
+  async *tail(options = {}) {
+    const { sinceSeq, maxMessages, timeoutMs, tags } = options;
+    const requiredTags = normalizeTagFilter(tags);
+    const limit = normalizeOptionalCount(maxMessages, "maxMessages");
+    const pollTimeoutMs = normalizePollingTimeout(timeoutMs);
+
+    let delivered = 0;
+    let cursor = sinceSeq ?? null;
+    while (true) {
+      if (limit !== null && delivered >= limit) {
+        return;
+      }
+
+      const remaining = limit === null ? null : limit - delivered;
+      const streamLimit = requiredTags.length && remaining !== null ? null : remaining;
+      const stream = this.openStream(cursor, streamLimit, pollTimeoutMs);
+      let sawRawMessage = false;
+      try {
+        for (const message of stream) {
+          sawRawMessage = true;
+          const parsed = parseMessage(message);
+          cursor = nextSinceSeq(parsed, cursor);
+          if (!messageHasTags(parsed, requiredTags)) {
+            continue;
+          }
+          delivered += 1;
+          yield parsed;
+          if (limit !== null && delivered >= limit) {
+            return;
+          }
+        }
+      } finally {
+        stream.close();
+      }
+      if (limit !== null && !sawRawMessage) {
+        return;
+      }
+      await sleep(0);
+    }
+  }
+
+  /**
+   * Replay parsed messages with original timing.
+   * @param {{speed?: number, sinceSeq?: number|bigint, maxMessages?: number|bigint, timeoutMs?: number|bigint, tags?: string[]}} [options]
+   * @returns {AsyncGenerator<Message, void, unknown>}
+   */
+  async *replay(options = {}) {
+    const { speed = 1.0, sinceSeq, maxMessages, timeoutMs, tags } = options;
+    if (speed <= 0) {
+      throw new Error("speed must be positive");
+    }
+
+    const requiredTags = normalizeTagFilter(tags);
+    const limit = normalizeOptionalCount(maxMessages, "maxMessages");
+    const pollTimeoutMs = normalizePollingTimeout(timeoutMs);
+    const streamLimit = requiredTags.length && limit !== null ? null : limit;
+    const stream = this.openStream(
+      sinceSeq ?? null,
+      streamLimit,
+      pollTimeoutMs,
+    );
+
+    const messages = [];
+    try {
+      for (const message of stream) {
+        const parsed = parseMessage(message);
+        if (!messageHasTags(parsed, requiredTags)) {
+          continue;
+        }
+        messages.push({
+          message: parsed,
+          timeMs: messageTimeMs(parsed),
+        });
+        if (limit !== null && messages.length >= limit) {
+          break;
+        }
+      }
+    } finally {
+      stream.close();
+    }
+
+    let prevMs = null;
+    for (const entry of messages) {
+      if (prevMs !== null && entry.timeMs !== null && speed > 0) {
+        const delay = (entry.timeMs - prevMs) / speed;
+        if (delay > 0) {
+          await sleep(delay);
+        }
+      }
+      if (entry.timeMs !== null) {
+        prevMs = entry.timeMs;
+      }
+      yield entry.message;
+    }
+  }
+
+  /**
+   * Close the pool handle.
+   * @returns {void}
+   */
   close() {
     this._inner.close();
   }
+
+  [Symbol.dispose]() {
+    this.close();
+  }
+}
+
+function normalizeTagFilter(tags) {
+  if (tags === undefined || tags === null) {
+    return [];
+  }
+  return Array.isArray(tags) ? tags : [tags];
+}
+
+function messageHasTags(message, requiredTags) {
+  if (!requiredTags.length) {
+    return true;
+  }
+  const messageTags = message && message.meta && Array.isArray(message.meta.tags)
+    ? message.meta.tags
+    : null;
+  if (!messageTags) {
+    return false;
+  }
+  return requiredTags.every((tag) => messageTags.includes(tag));
+}
+
+function messageTimeMs(message) {
+  if (!message || !(message.time instanceof Date)) {
+    return null;
+  }
+  const value = message.time.getTime();
+  return Number.isFinite(value) ? value : null;
+}
+
+function nextSinceSeq(message, fallback) {
+  if (!message) {
+    return fallback;
+  }
+  if (typeof message.seq === "bigint") {
+    return message.seq + 1n;
+  }
+  if (typeof message.seq === "number" && Number.isFinite(message.seq)) {
+    return message.seq + 1;
+  }
+  return fallback;
+}
+
+function decorateLite3Frame(frame) {
+  if (!frame || typeof frame !== "object") {
+    return frame;
+  }
+  if (!Object.prototype.hasOwnProperty.call(frame, "time")) {
+    Object.defineProperty(frame, "time", {
+      configurable: false,
+      enumerable: true,
+      get() {
+        return new Date(Number(this.timestampNs) / 1_000_000);
+      },
+    });
+  }
+  return frame;
+}
+
+function normalizeOptionalCount(value, fieldName) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === "bigint") {
+    if (value < 0n) {
+      throw new TypeError(`${fieldName} must be non-negative`);
+    }
+    return Number(value);
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new TypeError(`${fieldName} must be non-negative`);
+  }
+  return Math.floor(value);
+}
+
+function normalizePollingTimeout(timeoutMs) {
+  if (timeoutMs === undefined || timeoutMs === null) {
+    return 1000;
+  }
+  if (typeof timeoutMs === "bigint") {
+    if (timeoutMs <= 0n) {
+      return 1000;
+    }
+    return Number(timeoutMs);
+  }
+  if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+    throw new TypeError("timeoutMs must be numeric");
+  }
+  if (timeoutMs <= 0) {
+    return 1000;
+  }
+  return timeoutMs;
 }
 
 class Stream {
+  /**
+   * @param {object} inner
+   * @returns {Stream}
+   */
   constructor(inner) {
     if (!native) {
       throw makeNativeUnavailableError();
@@ -206,6 +539,10 @@ class Stream {
     this._inner = inner;
   }
 
+  /**
+   * Read the next raw JSON message.
+   * @returns {Buffer|null}
+   */
   nextJson() {
     try {
       return this._inner.nextJson();
@@ -214,12 +551,35 @@ class Stream {
     }
   }
 
+  /**
+   * Iterate raw JSON messages.
+   * @returns {Iterator<Buffer>}
+   */
+  *[Symbol.iterator]() {
+    let message;
+    while ((message = this.nextJson()) !== null) {
+      yield message;
+    }
+  }
+
+  /**
+   * Close the stream handle.
+   * @returns {void}
+   */
   close() {
     this._inner.close();
   }
+
+  [Symbol.dispose]() {
+    this.close();
+  }
 }
 
 class Lite3Stream {
+  /**
+   * @param {object} inner
+   * @returns {Lite3Stream}
+   */
   constructor(inner) {
     if (!native) {
       throw makeNativeUnavailableError();
@@ -227,52 +587,50 @@ class Lite3Stream {
     this._inner = inner;
   }
 
+  /**
+   * Read the next Lite3 frame.
+   * @returns {import("./types").Lite3Frame|null}
+   */
   next() {
     try {
-      return this._inner.next();
+      return decorateLite3Frame(this._inner.next());
     } catch (err) {
       throw wrapNativeError(err);
     }
   }
 
+  /**
+   * Iterate Lite3 frames.
+   * @returns {Iterator<import("./types").Lite3Frame>}
+   */
+  *[Symbol.iterator]() {
+    let frame;
+    while ((frame = this.next()) !== null) {
+      yield frame;
+    }
+  }
+
+  /**
+   * Close the Lite3 stream handle.
+   * @returns {void}
+   */
   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();
+  [Symbol.dispose]() {
+    this.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;
-  }
+/**
+ * Backward-compatible replay helper.
+ * @param {Pool} pool
+ * @param {object} [options]
+ * @returns {AsyncGenerator<Message, void, unknown>}
+ */
+async function* replay(pool, options = {}) {
+  yield* pool.replay(options);
 }
 
 module.exports = {
@@ -280,12 +638,16 @@ module.exports = {
   Pool,
   Stream,
   Lite3Stream,
-  Durability: native ? native.Durability : Object.freeze({}),
-  ErrorKind: native ? native.ErrorKind : Object.freeze({}),
+  Message,
+  DEFAULT_POOL_DIR,
+  DEFAULT_POOL_SIZE,
+  DEFAULT_POOL_SIZE_BYTES,
+  Durability,
+  ErrorKind,
   PlasmiteNativeError,
   RemoteClient,
   RemoteError,
   RemotePool,
-  RemoteTail,
+  parseMessage,
   replay,
 };

package/mappings.js

@@ -0,0 +1,55 @@
+/*
+Purpose: Centralize Node binding value mappings shared across local and remote paths.
+Key Exports: ERROR_KIND_VALUES, mapErrorKind, mapDurability.
+Role: Keep error-kind and durability normalization behavior consistent.
+Invariants: Error kind names map to stable numeric values for v0 semantics.
+Invariants: Durability accepts fast/flush and numeric enum aliases 0/1.
+*/
+
+const ERROR_KIND_VALUES = Object.freeze({
+  Internal: 1,
+  Usage: 2,
+  NotFound: 3,
+  AlreadyExists: 4,
+  Busy: 5,
+  Permission: 6,
+  Corrupt: 7,
+  Io: 8,
+});
+
+const DURABILITY_VALUES = Object.freeze({
+  fast: "fast",
+  flush: "flush",
+  0: "fast",
+  1: "flush",
+});
+
+function mapErrorKind(value, fallback = undefined) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const mapped = ERROR_KIND_VALUES[value];
+    if (mapped !== undefined) {
+      return mapped;
+    }
+  }
+  return fallback;
+}
+
+function mapDurability(value) {
+  if (value === undefined || value === null) {
+    return "fast";
+  }
+  const mapped = DURABILITY_VALUES[String(value).toLowerCase()];
+  if (mapped) {
+    return mapped;
+  }
+  throw new TypeError("durability must be Durability.Fast or Durability.Flush");
+}
+
+module.exports = {
+  ERROR_KIND_VALUES,
+  mapErrorKind,
+  mapDurability,
+};