plasmite 0.2.0 → 0.5.0

package/message.js

@@ -0,0 +1,97 @@
+/*
+Purpose: Define the canonical Node Message model shared by local and remote clients.
+Key Exports: Message, parseMessage, messageFromEnvelope.
+Role: Keep local/remote message shapes and parsing behavior identical.
+Invariants: Message timestamps parse as valid UTC Date values.
+Invariants: Message meta tags are normalized to string arrays.
+Notes: Raw bytes are preserved when source buffers are available.
+*/
+
+function normalizeMessageSeq(value) {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return BigInt(Math.trunc(value));
+  }
+  if (typeof value === "string" && value.length) {
+    return BigInt(value);
+  }
+  throw new TypeError("message seq must be numeric");
+}
+
+function normalizeMessageTags(meta) {
+  if (!meta || typeof meta !== "object" || !Array.isArray(meta.tags)) {
+    return Object.freeze([]);
+  }
+  return Object.freeze(meta.tags.map((tag) => String(tag)));
+}
+
+function serializeSeq(seq) {
+  const asNumber = Number(seq);
+  if (Number.isSafeInteger(asNumber)) {
+    return asNumber;
+  }
+  return seq.toString();
+}
+
+class Message {
+  constructor(envelope, raw = null) {
+    if (!envelope || typeof envelope !== "object") {
+      throw new TypeError("message envelope must be an object");
+    }
+    const seq = normalizeMessageSeq(envelope.seq);
+    const timeRfc3339 = String(envelope.time);
+    const time = new Date(timeRfc3339);
+    if (!Number.isFinite(time.getTime())) {
+      throw new TypeError("message time must be RFC3339");
+    }
+    const tags = normalizeMessageTags(envelope.meta);
+    this.seq = seq;
+    this.time = time;
+    this.timeRfc3339 = timeRfc3339;
+    this.data = envelope.data;
+    this.meta = Object.freeze({ tags });
+    this._raw = Buffer.isBuffer(raw) ? raw : null;
+  }
+
+  get tags() {
+    return this.meta.tags;
+  }
+
+  get raw() {
+    if (!this._raw) {
+      this._raw = Buffer.from(JSON.stringify({
+        seq: serializeSeq(this.seq),
+        time: this.timeRfc3339,
+        data: this.data,
+        meta: { tags: [...this.meta.tags] },
+      }));
+    }
+    return this._raw;
+  }
+}
+
+function messageFromEnvelope(envelope, raw = null) {
+  return new Message(envelope, raw);
+}
+
+function parseMessage(payload) {
+  if (payload instanceof Message) {
+    return payload;
+  }
+  if (Buffer.isBuffer(payload)) {
+    const parsed = JSON.parse(payload.toString("utf8"));
+    return messageFromEnvelope(parsed, payload);
+  }
+  if (payload && typeof payload === "object") {
+    return messageFromEnvelope(payload);
+  }
+  throw new TypeError("payload must be Buffer, Message, or message envelope object");
+}
+
+module.exports = {
+  Message,
+  messageFromEnvelope,
+  parseMessage,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plasmite",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Persistent JSON message queues for Node.js - native bindings for local and remote IPC",
   "license": "MIT",
   "main": "index.js",
@@ -11,7 +11,8 @@
   },
   "files": [
     "index.js",
-    "index.d.ts",
+    "message.js",
+    "mappings.js",
     "types.d.ts",
     "remote.js",
     "bin/plasmite.js",
@@ -38,7 +39,8 @@
   "scripts": {
     "prepare-native": "node scripts/prepare_native_assets.js",
     "build": "napi build --cargo-cwd native",
-    "test": "npm run build && node --test test/*.test.js",
+    "check:type-surface": "node scripts/check_type_surface.js",
+    "test": "npm run build && npm run check:type-surface && node --test test/*.test.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "prepack": "npm run build && npm run prepare-native",
     "prepublishOnly": "npm run typecheck"

package/remote.js

@@ -1,23 +1,31 @@
 /*
 Purpose: Provide an HTTP/JSON RemoteClient for the Node binding.
-Key Exports: RemoteClient, RemotePool, RemoteTail, RemoteError.
+Key Exports: RemoteClient, RemotePool, 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.
+Invariants: Tail streams are JSONL and exposed as async iterables.
 */
 
 const { Readable } = require("node:stream");
 const readline = require("node:readline");
+const { messageFromEnvelope } = require("./message");
+const { ERROR_KIND_VALUES, mapDurability, mapErrorKind } = require("./mappings");
 
 class RemoteError extends Error {
+  /**
+   * Build a structured remote error from an error envelope.
+   * @param {unknown} payload
+   * @param {number} status
+   * @returns {RemoteError}
+   */
   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.kind = mapErrorKind(error && error.kind, ERROR_KIND_VALUES.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;
@@ -26,16 +34,33 @@ class RemoteError extends Error {
 }
 
 class RemoteClient {
+  /**
+   * Create a remote client bound to a base URL.
+   * @param {string} baseUrl
+   * @param {{token?: string}} [options]
+   * @returns {RemoteClient}
+   */
   constructor(baseUrl, options = {}) {
     this.baseUrl = normalizeBaseUrl(baseUrl);
     this.token = options.token || null;
   }
 
+  /**
+   * Set bearer token and return the same client.
+   * @param {string} token
+   * @returns {RemoteClient}
+   */
   withToken(token) {
     this.token = token;
     return this;
   }
 
+  /**
+   * Create a pool on the remote server.
+   * @param {string} pool
+   * @param {number|bigint} sizeBytes
+   * @returns {Promise<unknown>}
+   */
   async createPool(pool, sizeBytes) {
     const payload = { pool, size_bytes: Number(sizeBytes) };
     const url = buildUrl(this.baseUrl, ["v0", "pools"]);
@@ -43,6 +68,11 @@ class RemoteClient {
     return data.pool;
   }
 
+  /**
+   * Open a remote pool handle.
+   * @param {string} pool
+   * @returns {Promise<RemotePool>}
+   */
   async openPool(pool) {
     const payload = { pool };
     const url = buildUrl(this.baseUrl, ["v0", "pools", "open"]);
@@ -50,18 +80,32 @@ class RemoteClient {
     return new RemotePool(this, pool);
   }
 
+  /**
+   * Fetch pool metadata.
+   * @param {string} pool
+   * @returns {Promise<unknown>}
+   */
   async poolInfo(pool) {
     const url = buildUrl(this.baseUrl, ["v0", "pools", pool, "info"]);
     const data = await this._requestJson("GET", url, null);
     return data.pool;
   }
 
+  /**
+   * List pools on the remote server.
+   * @returns {Promise<unknown[]>}
+   */
   async listPools() {
     const url = buildUrl(this.baseUrl, ["v0", "pools"]);
     const data = await this._requestJson("GET", url, null);
     return data.pools;
   }
 
+  /**
+   * Delete a pool by name.
+   * @param {string} pool
+   * @returns {Promise<void>}
+   */
   async deletePool(pool) {
     const url = buildUrl(this.baseUrl, ["v0", "pools", pool]);
     await this._requestJson("DELETE", url, null);
@@ -115,22 +159,43 @@ class RemoteClient {
 }
 
 class RemotePool {
+  /**
+   * @param {RemoteClient} client
+   * @param {string} pool
+   * @returns {RemotePool}
+   */
   constructor(client, pool) {
     this.client = client;
     this.pool = pool;
   }
 
+  /**
+   * Return pool reference string.
+   * @returns {string}
+   */
   poolRef() {
     return this.pool;
   }
 
+  /**
+   * Append message data to the remote pool.
+   * @param {unknown} data
+   * @param {string[]} [tags]
+   * @param {number|string} [durability]
+   * @returns {Promise<import("./message").Message>}
+   */
   async append(data, tags = [], durability = "fast") {
-    const payload = { data, tags, durability };
+    const payload = { data, tags, durability: mapDurability(durability) };
     const url = buildUrl(this.client.baseUrl, ["v0", "pools", this.pool, "append"]);
     const response = await this.client._requestJson("POST", url, payload);
-    return response.message;
+    return messageFromEnvelope(response.message);
   }
 
+  /**
+   * Get message by sequence from remote pool.
+   * @param {number|bigint} seq
+   * @returns {Promise<import("./message").Message>}
+   */
   async get(seq) {
     const url = buildUrl(this.client.baseUrl, [
       "v0",
@@ -140,10 +205,15 @@ class RemotePool {
       String(seq),
     ]);
     const response = await this.client._requestJson("GET", url, null);
-    return response.message;
+    return messageFromEnvelope(response.message);
   }
 
-  async tail(options = {}) {
+  /**
+   * Tail remote messages as an async iterable.
+   * @param {{sinceSeq?: number|bigint, maxMessages?: number|bigint, timeoutMs?: number, tags?: string[]}} [options]
+   * @returns {AsyncGenerator<import("./message").Message, void, unknown>}
+   */
+  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));
@@ -163,44 +233,23 @@ class RemotePool {
 
     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;
+    const reader = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+      for await (const line of reader) {
+        if (!line || !line.trim()) {
+          continue;
+        }
+        const raw = Buffer.from(line, "utf8");
+        yield messageFromEnvelope(JSON.parse(line), raw);
+      }
+    } finally {
+      controller.abort();
+      reader.close();
     }
-    this.done = true;
-    this.controller.abort();
-    this.reader.close();
   }
 }
 
@@ -237,6 +286,5 @@ async function parseRemoteError(response) {
 module.exports = {
   RemoteClient,
   RemotePool,
-  RemoteTail,
   RemoteError,
 };

package/types.d.ts

@@ -1,10 +1,10 @@
 /*
 Purpose: Stable TypeScript declarations for the public Node bindings API.
-Key Exports: Client, Pool, Stream, Lite3Stream, replay, and remote client types.
+Key Exports: Client, Pool, Stream, Lite3Stream, parseMessage, 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.
+Notes: Canonical declaration source for package typing (`package.json#types`).
 */
 
 export const enum Durability {
@@ -22,16 +22,43 @@ export const enum ErrorKind {
   Corrupt = 7,
   Io = 8,
 }
+export const DEFAULT_POOL_DIR: string
+export const DEFAULT_POOL_SIZE_BYTES: number
+export const DEFAULT_POOL_SIZE: number
 
 export interface Lite3Frame {
   seq: bigint
   timestampNs: bigint
   flags: number
   payload: Buffer
+  time: Date
+}
+
+export interface MessageMeta {
+  tags: string[]
+}
+
+export class Message {
+  readonly seq: bigint
+  readonly time: Date
+  readonly timeRfc3339: string
+  readonly data: unknown
+  readonly meta: MessageMeta
+  readonly raw: Buffer
+  get tags(): string[]
+}
+
+export interface MessageEnvelope {
+  seq: number | bigint | string
+  time: string
+  data: unknown
+  meta?: {
+    tags?: unknown[]
+  }
 }
 
 export class PlasmiteNativeError extends Error {
-  kind?: string
+  kind?: ErrorKind
   path?: string
   seq?: number
   offset?: number
@@ -39,17 +66,23 @@ export class PlasmiteNativeError extends Error {
 }
 
 export class Client {
-  constructor(poolDir: string)
-  createPool(poolRef: string, sizeBytes: number | bigint): Pool
+  constructor(poolDir?: string)
+  createPool(poolRef: string, sizeBytes?: number | bigint): Pool
   openPool(poolRef: string): Pool
+  pool(poolRef: string, sizeBytes?: number | bigint): Pool
   close(): void
+  [Symbol.dispose](): void
 }
 
 export class Pool {
-  appendJson(payload: Buffer, tags: string[], durability: Durability): Buffer
-  appendLite3(payload: Buffer, durability: Durability): bigint
+  append(payload: unknown, tags?: string[], durability?: Durability): Message
+  appendJson(payload: unknown, tags?: string[], durability?: Durability): Buffer
+  appendLite3(payload: Buffer, durability?: Durability): bigint
+  get(seq: number | bigint): Message
   getJson(seq: number | bigint): Buffer
   getLite3(seq: number | bigint): Lite3Frame
+  tail(options?: LocalTailOptions): AsyncGenerator<Message, void, unknown>
+  replay(options?: ReplayOptions): AsyncGenerator<Message, void, unknown>
   openStream(
     sinceSeq?: number | bigint | null,
     maxMessages?: number | bigint | null,
@@ -61,16 +94,21 @@ export class Pool {
     timeoutMs?: number | bigint | null,
   ): Lite3Stream
   close(): void
+  [Symbol.dispose](): void
 }
 
 export class Stream {
+  [Symbol.iterator](): Iterator<Buffer>
   nextJson(): Buffer | null
   close(): void
+  [Symbol.dispose](): void
 }
 
 export class Lite3Stream {
+  [Symbol.iterator](): Iterator<Lite3Frame>
   next(): Lite3Frame | null
   close(): void
+  [Symbol.dispose](): void
 }
 
 export interface ReplayOptions {
@@ -78,12 +116,22 @@ export interface ReplayOptions {
   sinceSeq?: number | bigint
   maxMessages?: number | bigint
   timeoutMs?: number | bigint
+  tags?: string[]
+}
+
+export interface LocalTailOptions {
+  sinceSeq?: number | bigint
+  maxMessages?: number | bigint
+  timeoutMs?: number | bigint
+  tags?: string[]
 }
 
+export function parseMessage(payload: Buffer | Message | MessageEnvelope): Message
+
 export function replay(
   pool: Pool,
   options?: ReplayOptions,
-): AsyncGenerator<Buffer, void, unknown>
+): AsyncGenerator<Message, void, unknown>
 
 export interface RemoteClientOptions {
   token?: string
@@ -102,15 +150,6 @@ export interface RemotePoolInfo {
   index_inline: boolean
 }
 
-export interface RemoteMessage {
-  seq: number
-  time: string
-  data: unknown
-  meta?: {
-    tags?: string[]
-  }
-}
-
 export interface RemoteTailOptions {
   sinceSeq?: number | bigint
   maxMessages?: number | bigint
@@ -119,7 +158,7 @@ export interface RemoteTailOptions {
 
 export class RemoteError extends Error {
   status: number
-  kind: string
+  kind: ErrorKind
   hint?: string
   path?: string
   seq?: number
@@ -146,13 +185,8 @@ export class RemotePool {
   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
+    durability?: Durability,
+  ): Promise<Message>
+  get(seq: number | bigint): Promise<Message>
+  tail(options?: RemoteTailOptions): AsyncGenerator<Message, void, unknown>
 }

package/index.d.ts

@@ -1,48 +0,0 @@
-/* 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
-}