@prosody-events/prosody 0.5.1 → 0.6.1

package/lib/state/deque.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The double-ended-queue keyed-state handle.
+ * @module lib/state/deque
+ */
+
+import type { JsonValue } from "../payload";
+import type { StateTransaction } from "./handle";
+import type { PositionQueryOptions, ScanDirection } from "./query";
+
+/**
+ * Typed handle over a double-ended-queue keyed-state collection, vended by
+ * `Context.state()`. Valid only within the handler invocation (attempt) that
+ * vended it. Every method opens its own per-operation trace span.
+ * A failed call rejects with a {@link PermanentStateError} or a
+ * {@link TransientStateError}. A write of a value with no JSON form rejects
+ * with a {@link TransientStateError}.
+ */
+export declare class DequeState<T = JsonValue> {
+  /** Vended only by {@link Context#state}; not constructible directly. */
+  private constructor(native: unknown);
+  /**
+   * Appends an element at the back. The item type excludes `null` and
+   * `undefined`, because a top-level `null` is not a storable element. At run
+   * time Prosody rejects JSON `null` with a {@link PermanentStateError}. A
+   * nested `null` is stored.
+   */
+  push(item: NonNullable<T>): Promise<void>;
+  /**
+   * Prepends an element at the front. The item type excludes `null`/`undefined`
+   * (via {@link !NonNullable}); see {@link DequeState#push}.
+   */
+  unshift(item: NonNullable<T>): Promise<void>;
+  /** Removes and returns the back element, or null when empty. */
+  pop(): Promise<T | null>;
+  /** Removes and returns the front element, or null when empty. */
+  shift(): Promise<T | null>;
+  /** Returns the number of live elements. */
+  length(): Promise<number>;
+  /** Reports whether the deque holds no live elements. */
+  isEmpty(): Promise<boolean>;
+  /** Removes every element. */
+  clear(): Promise<void>;
+  /**
+   * Reads the element at `index`, like `Array.prototype.at`: a non-negative
+   * `index` counts from the front (`0` is the front), a negative `index` counts
+   * back from the end (`-1` is the back). Any out-of-range position — including
+   * every index on an empty deque — resolves to null. `index` must be a safe
+   * integer; a fractional, `NaN`, or infinite value is a caller mistake,
+   * rejected with a {@link TransientStateError} (it retries and stays visible).
+   *
+   * A non-negative `index` and `at(-1)` make a single read. Any other negative
+   * `index` is resolved against the current {@link DequeState#length}, so it
+   * makes an extra read.
+   *
+   * Under a TTL, an expired element reads as null. This is also true for an
+   * expired front or back element when live elements remain inside the deque.
+   */
+  at(index: number): Promise<T | null>;
+  /**
+   * Async iterator over the live elements in index order. Pass a direction or
+   * a {@link PositionQueryOptions} to select elements. Valid only within the handler
+   * invocation (attempt) that opened it; early exit from a `for await` loop
+   * closes the underlying cursor.
+   */
+  values(
+    options?: ScanDirection | PositionQueryOptions,
+  ): AsyncIterableIterator<T>;
+  /**
+   * Forward iteration over the elements. Valid only within the handler
+   * invocation (attempt) that opened it.
+   */
+  [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+
+export interface DequeState<T = JsonValue> extends StateTransaction {}

package/lib/state/deque.js

@@ -0,0 +1,77 @@
+/**
+ * The double-ended-queue keyed-state handle.
+ * @module lib/state/deque
+ * @private
+ */
+
+const { stateOp } = require("./bridge");
+const { StateHandle } = require("./handle");
+const { stateIterator } = require("./iterator");
+const { dequePosition, positionQuery } = require("./query");
+
+/** Typed handle over a double-ended-queue keyed-state collection. */
+class DequeState extends StateHandle {
+  push(item) {
+    return stateOp((carrier) =>
+      this.native.pushBack(this.items.encode(item), carrier),
+    );
+  }
+
+  unshift(item) {
+    return stateOp((carrier) =>
+      this.native.pushFront(this.items.encode(item), carrier),
+    );
+  }
+
+  pop() {
+    return stateOp((carrier) => this.native.popBack(carrier)).then(
+      this.items.decode,
+    );
+  }
+
+  shift() {
+    return stateOp((carrier) => this.native.popFront(carrier)).then(
+      this.items.decode,
+    );
+  }
+
+  length() {
+    return stateOp((carrier) => this.native.len(carrier));
+  }
+
+  isEmpty() {
+    return stateOp((carrier) => this.native.isEmpty(carrier));
+  }
+
+  clear() {
+    return stateOp((carrier) => this.native.clear(carrier));
+  }
+
+  async at(index) {
+    if (index === -1) {
+      return this.items.decode(
+        await stateOp((carrier) => this.native.peekBack(carrier)),
+      );
+    }
+    const position = await dequePosition(index, () => this.length());
+    if (position === null) return null;
+    return this.items.decode(
+      await stateOp((carrier) => this.native.get(position, carrier)),
+    );
+  }
+
+  values(options) {
+    const query = positionQuery(options);
+    return stateIterator(this.native.values(query), (item) =>
+      this.items.decode(item),
+    );
+  }
+
+  [Symbol.asyncIterator]() {
+    return this.values();
+  }
+}
+
+module.exports = {
+  DequeState,
+};

package/lib/state/handle.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The commit and rollback methods of every state handle, and their outcome.
+ * @module lib/state/handle
+ */
+
+/**
+ * The effect of `commit()` or `rollback()`. `"applied"` means the call wrote or
+ * discarded buffered operations. `"noOp"` means nothing was buffered.
+ */
+export type StoreOutcome = "applied" | "noOp";
+
+/** The commit and rollback methods of every state handle. */
+export interface StateTransaction {
+  /**
+   * Durably commits the buffered operations mid-handler (at-least-once). The
+   * committed changes survive a later rollback or a failed event. Resolves to
+   * `"applied"` when it wrote buffered operations, or `"noOp"`.
+   */
+  commit(): Promise<StoreOutcome>;
+  /**
+   * Discards buffered uncommitted operations back to the committed floor.
+   * Resolves to `"applied"` when it discarded buffered operations, or `"noOp"`.
+   */
+  rollback(): Promise<StoreOutcome>;
+}

package/lib/state/handle.js

@@ -0,0 +1,26 @@
+/**
+ * The base class of the keyed-state handles: commit and rollback.
+ * @module lib/state/handle
+ * @private
+ */
+
+const { defineHidden, stateOp } = require("./bridge");
+
+/** The base class of every keyed-state handle: commit and rollback. */
+class StateHandle {
+  constructor(native, items) {
+    defineHidden(this, { native, items });
+  }
+
+  commit() {
+    return stateOp((carrier) => this.native.commit(carrier));
+  }
+
+  rollback() {
+    return stateOp((carrier) => this.native.rollback(carrier));
+  }
+}
+
+module.exports = {
+  StateHandle,
+};

package/lib/state/iterator.js

@@ -0,0 +1,66 @@
+/**
+ * Adapts a chunked native scan cursor to a JavaScript async iterator.
+ * @module lib/state/iterator
+ * @private
+ */
+
+const { injectedCarrier, toStateError } = require("./bridge");
+
+/**
+ * Adapts a chunked native scan cursor to an async generator. Each native pull
+ * gets a fresh trace carrier and records no span. Each `next()` call takes the
+ * next item of the held chunk without an N-API call. A native `null` means
+ * the scan is done. The generator queues concurrent `next()` and `return()`
+ * calls, so no item is yielded twice and no close runs during a pull.
+ *
+ * The end of the scan, an early exit from a `for await` loop, and a pull or
+ * decode error all close the cursor. Every failure a caller sees goes through
+ * `toStateError`.
+ *
+ * Owned cursors stay fenced to their attempt. Published cursors stay valid
+ * with their reader.
+ * @param {object} cursor - The native scan cursor.
+ * @param {(item: *) => *} transform - Maps each raw item to the yielded value.
+ * @returns {AsyncGenerator<*>} The async iterator.
+ * @private
+ */
+async function* stateIterator(cursor, transform) {
+  let failed = false;
+  try {
+    for (;;) {
+      const chunk = await cursor.nextChunk(injectedCarrier());
+      if (chunk === null) return;
+      for (let index = 0; index < chunk.length; index += 1) {
+        const item = chunk[index];
+        // Release consumed values even while the rest of a large chunk remains.
+        chunk[index] = undefined;
+        yield transform(item);
+      }
+    }
+  } catch (error) {
+    failed = true;
+    throw toStateError(error);
+  } finally {
+    await close(cursor, failed);
+  }
+}
+
+/**
+ * Closes a native scan cursor. After a failure the close is best effort and
+ * never hides that error.
+ * @param {object} cursor - The native scan cursor.
+ * @param {boolean} quietly - Whether to ignore a close failure.
+ * @returns {Promise<void>} Resolves when the cursor is closed.
+ * @private
+ */
+async function close(cursor, quietly) {
+  try {
+    await cursor.close();
+  } catch (error) {
+    if (!quietly) throw toStateError(error);
+  }
+}
+
+module.exports = {
+  stateIterator,
+};

package/lib/state/map.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The ordered-map keyed-state handle.
+ * @module lib/state/map
+ */
+
+import type { JsonValue } from "../payload";
+import type { StateTransaction } from "./handle";
+import type { KeyQueryOptions, ScanDirection } from "./query";
+
+/**
+ * Typed handle over an ordered-map keyed-state collection, vended by
+ * `Context.state()`. Map keys are always `string`. Valid only within the
+ * handler invocation (attempt) that vended it. Every method opens its own
+ * per-operation trace span.
+ * A failed call rejects with a {@link PermanentStateError} or a
+ * {@link TransientStateError}. A write of a value with no JSON form rejects
+ * with a {@link TransientStateError}.
+ */
+export declare class MapState<V = JsonValue> {
+  /** Vended only by {@link Context#state}; not constructible directly. */
+  private constructor(native: unknown);
+  /** Reads the value for `key`, or null when the key is absent. */
+  get(key: string): Promise<V | null>;
+  /**
+   * Reads several keys in one call. The result has one entry per key, in the
+   * order given, so `result[i]` is the value for `keys[i]`. An absent key reads
+   * as `null`. A repeated key gets an entry at each position. No other change
+   * to the state of this event occurs during the read.
+   */
+  getMany(keys: readonly string[]): Promise<(V | null)[]>;
+  /**
+   * Reports whether `key` currently has a stored value. It skips the value
+   * decode and the resolver. A message map answers with no Kafka fetch, so it
+   * can report `true` for a message that Kafka no longer holds. A cache miss
+   * still reads the store, but the call costs less than {@link MapState#get}.
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Tests several keys for presence in one read. `result[i]` answers
+   * `keys[i]`. Like {@link MapState#has}, it skips the value decode.
+   */
+  hasMany(keys: readonly string[]): Promise<boolean[]>;
+  /** Reports whether the map holds no live entries. */
+  isEmpty(): Promise<boolean>;
+  /**
+   * Inserts or overwrites `key`. The value type excludes `null` and
+   * `undefined`, because a top-level `null` is not a storable value. At run
+   * time Prosody rejects JSON `null` with a {@link PermanentStateError}; use
+   * {@link MapState#delete} to remove an entry. A nested `null` is stored.
+   */
+  set(key: string, value: NonNullable<V>): Promise<void>;
+  /**
+   * Removes `key`.
+   *
+   * Unlike `Map#delete`, it returns no "was present" flag, because that flag
+   * needs a read on every delete.
+   */
+  delete(key: string): Promise<void>;
+  /** Removes every entry. */
+  clear(): Promise<void>;
+  /**
+   * Async iterator over the live `[key, value]` entries in key order. Pass a
+   * direction or a {@link KeyQueryOptions} to select entries. Valid only within the
+   * handler invocation (attempt) that opened it; early exit from a
+   * `for await` loop closes the underlying cursor.
+   */
+  entries(
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<[string, V]>;
+  /**
+   * Async iterator over the live keys in key order. Takes the same options as
+   * {@link MapState#entries}. Skips the value decode and the resolver, so a message-backed map enumerates keys with zero Kafka
+   * fetches; it still reads presence, so it is not zero-I/O. Valid only within
+   * the handler invocation (attempt) that opened it; early exit from a
+   * `for await` loop closes the underlying cursor.
+   */
+  keys(
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<string>;
+  /**
+   * Async iterator over the live values in key order. Takes the same options
+   * as {@link MapState#entries}. Valid only within the handler invocation
+   * (attempt) that opened it; early exit from a `for await` loop closes the
+   * underlying cursor.
+   */
+  values(options?: ScanDirection | KeyQueryOptions): AsyncIterableIterator<V>;
+  /**
+   * Forward iteration over `[key, value]` entries. Valid only within the
+   * handler invocation (attempt) that opened it.
+   */
+  [Symbol.asyncIterator](): AsyncIterableIterator<[string, V]>;
+}
+
+export interface MapState<V = JsonValue> extends StateTransaction {}

package/lib/state/map.js

@@ -0,0 +1,79 @@
+/**
+ * The ordered-map keyed-state handle.
+ * @module lib/state/map
+ * @private
+ */
+
+const { stateOp } = require("./bridge");
+const { StateHandle } = require("./handle");
+const { stateIterator } = require("./iterator");
+const { keyQuery } = require("./query");
+
+/** Typed handle over an ordered-map keyed-state collection. */
+class MapState extends StateHandle {
+  get(key) {
+    return stateOp((carrier) => this.native.get(key, carrier)).then(
+      this.items.decode,
+    );
+  }
+
+  getMany(keys) {
+    return stateOp((carrier) => this.native.getMany(keys, carrier)).then(
+      (items) => items.map(this.items.decode),
+    );
+  }
+
+  has(key) {
+    return stateOp((carrier) => this.native.contains(key, carrier));
+  }
+
+  hasMany(keys) {
+    return stateOp((carrier) => this.native.containsMany(keys, carrier));
+  }
+
+  isEmpty() {
+    return stateOp((carrier) => this.native.isEmpty(carrier));
+  }
+
+  set(key, value) {
+    return stateOp((carrier) =>
+      this.native.set(key, this.items.encode(value), carrier),
+    );
+  }
+
+  delete(key) {
+    return stateOp((carrier) => this.native.remove(key, carrier));
+  }
+
+  clear() {
+    return stateOp((carrier) => this.native.clear(carrier));
+  }
+
+  entries(options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.entries(query), ([key, item]) => [
+      key,
+      this.items.decode(item),
+    ]);
+  }
+
+  keys(options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.keys(query), (key) => key);
+  }
+
+  values(options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.entries(query), ([, item]) =>
+      this.items.decode(item),
+    );
+  }
+
+  [Symbol.asyncIterator]() {
+    return this.entries();
+  }
+}
+
+module.exports = {
+  MapState,
+};

package/lib/state/published.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The read-only readers of published value, map, set, and deque collections.
+ *
+ * `ProsodyClient.state(subsystem, definition)` opens a reader. A reader reads
+ * the committed state of another consumer group, so every read takes the
+ * partition key. It is independent of subscription and stays valid while its
+ * client runs. A failed read rejects with a {@link TransientStateError} or a
+ * {@link PermanentStateError}, like a read through an owned handle. A reader
+ * error at open, such as a zero `readCache` TTL, rejects `state()` the same way.
+ * @module lib/state/published
+ */
+
+import type { JsonValue } from "../payload";
+import type { PermanentStateError, TransientStateError } from "../errors";
+import type {
+  KeyQueryOptions,
+  PositionQueryOptions,
+  ScanDirection,
+} from "./query";
+
+/** Per-collection cache override for published reads. */
+export interface ReadCacheOptions {
+  /** Cache duration in milliseconds. */
+  ttlMs: number;
+}
+
+/** Read-only published value collection. */
+export declare class PublishedValue<T = JsonValue> {
+  private constructor();
+
+  /** Reads the committed value for `key`, or null when it is absent. */
+  get(key: string): Promise<T | null>;
+}
+
+/** Read-only published map collection. */
+export declare class PublishedMap<V = JsonValue> {
+  private constructor();
+
+  /** Reads the committed value of `mapKey` for `key`, or null when absent. */
+  get(key: string, mapKey: string): Promise<V | null>;
+  /**
+   * Reads several map keys in one call. The result has one entry per map key,
+   * in the order given, and an absent map key reads as null.
+   */
+  getMany(key: string, mapKeys: readonly string[]): Promise<Array<V | null>>;
+  /** Reports whether the map for `key` holds `mapKey`. */
+  has(key: string, mapKey: string): Promise<boolean>;
+  /** Tests several map keys in one call. `result[i]` answers `mapKeys[i]`. */
+  hasMany(key: string, mapKeys: readonly string[]): Promise<boolean[]>;
+  /** Reports whether the map for `key` holds no entries. */
+  isEmpty(key: string): Promise<boolean>;
+  /** Iterates the selected `[mapKey, value]` entries in key order. */
+  entries(
+    key: string,
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<[string, V]>;
+  /** Iterates the selected map keys in key order. */
+  keys(
+    key: string,
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<string>;
+  /** Iterates the values of the selected entries in key order. */
+  values(
+    key: string,
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<V>;
+}
+
+/** Read-only published set collection. */
+export declare class PublishedSet {
+  private constructor();
+
+  /** Reports whether the set for `key` holds `member`. */
+  has(key: string, member: string): Promise<boolean>;
+  /** Tests several members in one call. `result[i]` answers `members[i]`. */
+  hasMany(key: string, members: readonly string[]): Promise<boolean[]>;
+  /** Reports whether the set for `key` holds no members. */
+  isEmpty(key: string): Promise<boolean>;
+  /** Iterates the selected members in order. */
+  keys(
+    key: string,
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<string>;
+  /** The same iterator as `keys`, as on the JavaScript `Set`. */
+  values(
+    key: string,
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<string>;
+}
+
+/** Read-only published deque collection. */
+export declare class PublishedDeque<T = JsonValue> {
+  private constructor();
+
+  /** Reads the number of values in the deque for `key`. */
+  length(key: string): Promise<number>;
+  /** Reports whether the deque for `key` holds no values. */
+  isEmpty(key: string): Promise<boolean>;
+  /**
+   * Reads the value at `index`, or null when the position is out of range.
+   * `0` is the front and `-1` is the back. A negative index other than `-1`
+   * also reads the length, so it makes two reads. Under a TTL, an expired
+   * element reads as null. This is also true for an expired front or back
+   * element when live elements remain inside the deque.
+   * @throws TransientStateError if `index` is not a safe integer.
+   */
+  at(key: string, index: number): Promise<T | null>;
+  /** Iterates the selected values from the front. */
+  values(
+    key: string,
+    options?: ScanDirection | PositionQueryOptions,
+  ): AsyncIterableIterator<T>;
+}