@prosody-events/prosody 0.5.1 → 0.6.1

package/lib/state/published.js

@@ -0,0 +1,147 @@
+/**
+ * The read-only readers of published value, map, set, and deque collections.
+ * @module lib/state/published
+ * @private
+ */
+
+const { defineHidden, stateOp } = require("./bridge");
+const { jsonItems } = require("./codec");
+const { stateIterator } = require("./iterator");
+const { dequePosition, keyQuery, positionQuery } = require("./query");
+
+/** Read-only handle over a published single-value collection. */
+class PublishedValue {
+  constructor(native) {
+    defineHidden(this, { native });
+  }
+
+  async get(key) {
+    return jsonItems.decode(
+      await stateOp((carrier) => this.native.get(key, carrier)),
+    );
+  }
+}
+
+/** Read-only handle over a published map collection. */
+class PublishedMap {
+  constructor(native) {
+    defineHidden(this, { native });
+  }
+
+  async get(key, mapKey) {
+    return jsonItems.decode(
+      await stateOp((carrier) => this.native.get(key, mapKey, carrier)),
+    );
+  }
+
+  async getMany(key, mapKeys) {
+    const values = await stateOp((carrier) =>
+      this.native.getMany(key, mapKeys, carrier),
+    );
+    return values.map(jsonItems.decode);
+  }
+
+  has(key, mapKey) {
+    return stateOp((carrier) => this.native.contains(key, mapKey, carrier));
+  }
+
+  hasMany(key, mapKeys) {
+    return stateOp((carrier) =>
+      this.native.containsMany(key, mapKeys, carrier),
+    );
+  }
+
+  isEmpty(key) {
+    return stateOp((carrier) => this.native.isEmpty(key, carrier));
+  }
+
+  entries(key, options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.entries(key, query), ([mapKey, value]) => [
+      mapKey,
+      jsonItems.decode(value),
+    ]);
+  }
+
+  keys(key, options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.keys(key, query), (mapKey) => mapKey);
+  }
+
+  values(key, options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.entries(key, query), (entry) =>
+      jsonItems.decode(entry[1]),
+    );
+  }
+}
+
+/** Read-only handle over a published set collection. */
+class PublishedSet {
+  constructor(native) {
+    defineHidden(this, { native });
+  }
+
+  has(key, member) {
+    return stateOp((carrier) => this.native.contains(key, member, carrier));
+  }
+
+  hasMany(key, members) {
+    return stateOp((carrier) =>
+      this.native.containsMany(key, members, carrier),
+    );
+  }
+
+  isEmpty(key) {
+    return stateOp((carrier) => this.native.isEmpty(key, carrier));
+  }
+
+  keys(key, options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.keys(key, query), (member) => member);
+  }
+
+  values(key, options) {
+    return this.keys(key, options);
+  }
+}
+
+/** Read-only handle over a published deque collection. */
+class PublishedDeque {
+  constructor(native) {
+    defineHidden(this, { native });
+  }
+
+  length(key) {
+    return stateOp((carrier) => this.native.len(key, carrier));
+  }
+
+  isEmpty(key) {
+    return stateOp((carrier) => this.native.isEmpty(key, carrier));
+  }
+
+  async at(key, index) {
+    if (index === -1) {
+      return jsonItems.decode(
+        await stateOp((carrier) => this.native.peekBack(key, carrier)),
+      );
+    }
+    const position = await dequePosition(index, () => this.length(key));
+    if (position === null) return null;
+    return jsonItems.decode(
+      await stateOp((carrier) => this.native.get(key, position, carrier)),
+    );
+  }
+
+  values(key, options) {
+    const query = positionQuery(options);
+    return stateIterator(this.native.values(key, query), jsonItems.decode);
+  }
+}
+
+module.exports = {
+  PublishedDeque,
+  PublishedMap,
+  PublishedSet,
+  PublishedValue,
+};

package/lib/state/query.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The query options of map, set, and deque scans. The runtime checks stay private.
+ * @module lib/state/query
+ */
+
+/**
+ * Scan direction over a map or deque collection. `"forward"` visits a map in
+ * ascending key order and a deque from front to back; `"backward"` reverses
+ * each. Defaults to `"forward"` wherever it is optional.
+ */
+export type ScanDirection = "forward" | "backward";
+
+/**
+ * The start of a query. `from` includes its bound and `after` excludes it.
+ * Set at most one. The start is in query order, so a backward query starts
+ * at the high end.
+ */
+export type QueryStart<B> =
+  | { readonly from?: B; readonly after?: never }
+  | { readonly from?: never; readonly after?: B };
+
+/**
+ * The end of a query. `to` includes its bound and `before` excludes it. Set
+ * at most one. The end is in query order.
+ */
+export type QueryEnd<B> =
+  | { readonly to?: B; readonly before?: never }
+  | { readonly to?: never; readonly before?: B };
+
+/**
+ * An ascending, half-open range: `[start, end]` keeps the keys or positions
+ * from `start` up to, but not including, `end`. A `null` bound leaves its end
+ * open, so `[2, null]` keeps position 2 and every later one. The range applies
+ * in both directions, so a backward query yields the same items in the
+ * opposite order. A range whose `start` is not below its `end` selects
+ * nothing.
+ */
+export type QueryRange<B> = readonly [start: B | null, end: B | null];
+
+/**
+ * The bounds of a query: the edges and an optional range. A query that sets
+ * both keeps their overlap.
+ */
+export type QueryBounds<B> = QueryStart<B> &
+  QueryEnd<B> & {
+    /** Keeps the items within this ascending range. See {@link QueryRange}. */
+    readonly range?: QueryRange<B>;
+  };
+
+/** The options that every query accepts. */
+export interface QueryOptions {
+  /** The query order. Defaults to `"forward"`. */
+  readonly direction?: ScanDirection;
+  /**
+   * The maximum number of results. Must be a positive safe integer. A
+   * `RangeError` reports any other number.
+   */
+  readonly limit?: number;
+}
+
+/**
+ * Query options for map entries, map keys, and set members. Every option is
+ * optional. Bounds and `prefix` narrow the selection and never widen it.
+ * Setting both edges of a pair, a malformed range, an unknown option, or an
+ * unknown direction throws a `TypeError`. The call
+ * copies the options, so a later change to the object has no effect on the
+ * query.
+ *
+ * For keyset paging, set `after` to the last key of the previous page and
+ * `limit` to the page size. To read the keys from `"a"` up to `"m"` in either
+ * direction, set `range: ["a", "m"]`.
+ */
+export type KeyQueryOptions = QueryOptions & {
+  /** Keeps keys that start with this prefix. */
+  readonly prefix?: string;
+} & QueryBounds<string>;
+
+/**
+ * Query options for deque values. Positions count from the front. Each
+ * position must be a non-negative safe integer; a `RangeError` reports any
+ * other number. Negative positions are not resolved against the length. To
+ * read the last N elements, use `values({ direction: "backward", limit: N })`.
+ * To read positions 2, 3, and 4 in either direction, set `range: [2, 5]`.
+ */
+export type PositionQueryOptions = QueryOptions & QueryBounds<number>;

package/lib/state/query.js

@@ -0,0 +1,206 @@
+/**
+ * Checks and copies the query options of map, set, and deque scans, and
+ * resolves deque `at` indexes.
+ * @module lib/state/query
+ * @private
+ */
+
+const { TransientStateError } = require("../errors");
+const { describeValue } = require("./bridge");
+
+/** The options a map or set query accepts. @private */
+const KEY_QUERY_FIELDS = new Set([
+  "direction",
+  "limit",
+  "prefix",
+  "from",
+  "after",
+  "to",
+  "before",
+  "range",
+]);
+
+/** The options a deque query accepts. @private */
+const POSITION_QUERY_FIELDS = new Set([
+  "direction",
+  "limit",
+  "from",
+  "after",
+  "to",
+  "before",
+  "range",
+]);
+
+/** The query edges. @private */
+const QUERY_EDGES = ["from", "after", "to", "before"];
+
+/**
+ * Checks the shared query options and copies them into a fresh object. A
+ * bare direction string stands for `{ direction }` and gets the same checks.
+ * The copy holds only the set, checked fields, so a later change to the
+ * caller's object cannot reach the native layer. The copy also holds its own
+ * copy of the `range` array. A `range` may combine with the edges; the query
+ * then keeps the overlap. A `null` bound leaves that end of the range open.
+ * @param {string|object} [options] - A scan direction or a query object.
+ * @param {Set<string>} fields - The option names this query accepts.
+ * @returns {object} The checked query.
+ * @throws {TypeError} If `options` has the wrong type, has an unknown option,
+ *   sets both edges of an exclusive pair, sets a `range` that is not an array
+ *   of two bounds, or sets an unknown direction.
+ * @throws {RangeError} If `limit` is not a positive safe integer.
+ * @private
+ */
+function queryOptions(options, fields) {
+  if (options === undefined) return {};
+  const source = typeof options === "string" ? { direction: options } : options;
+  if (source === null || typeof source !== "object") {
+    throw new TypeError(
+      `query: expected a scan direction or an options object, got ${describeValue(options)}`,
+    );
+  }
+  const query = {};
+  for (const [field, value] of Object.entries(source)) {
+    if (!fields.has(field)) {
+      throw new TypeError(`query: unknown option ${describeValue(field)}`);
+    }
+    if (value !== undefined) query[field] = value;
+  }
+  for (const [start, end] of [
+    ["from", "after"],
+    ["to", "before"],
+  ]) {
+    if (query[start] !== undefined && query[end] !== undefined) {
+      throw new TypeError(`query: set ${start} or ${end}, not both`);
+    }
+  }
+  if (query.range !== undefined) {
+    if (
+      !Array.isArray(query.range) ||
+      query.range.length !== 2 ||
+      query.range.includes(undefined)
+    ) {
+      throw new TypeError(
+        `range: expected a [start, end] array, got ${describeValue(query.range)}`,
+      );
+    }
+    query.range = [...query.range];
+  }
+  const { direction } = query;
+  if (
+    direction !== undefined &&
+    direction !== "forward" &&
+    direction !== "backward"
+  ) {
+    throw new TypeError(
+      `direction: expected "forward" or "backward", got ${describeValue(direction)}`,
+    );
+  }
+  checkCount(query.limit, "limit", 1);
+  return query;
+}
+
+/**
+ * Checks a whole-number query option.
+ * @param {*} count - The option value, or `undefined` when it is not set.
+ * @param {string} field - The option name.
+ * @param {number} min - The smallest valid value.
+ * @throws {TypeError} If the value is not a number.
+ * @throws {RangeError} If the value is not a safe integer of at least `min`.
+ * @private
+ */
+function checkCount(count, field, min) {
+  if (count === undefined) return;
+  if (typeof count !== "number") {
+    throw new TypeError(
+      `${field}: expected a number, got ${describeValue(count)}`,
+    );
+  }
+  if (!Number.isSafeInteger(count) || count < min) {
+    throw new RangeError(
+      `${field}: expected a safe integer of at least ${min}, got ${count}`,
+    );
+  }
+}
+
+/**
+ * Checks the options of a map or set query.
+ * @param {string|object} [options] - A scan direction or a key query.
+ * @returns {object} The key query.
+ * @throws {TypeError|RangeError} If an option is invalid.
+ * @private
+ */
+function keyQuery(options) {
+  const query = queryOptions(options, KEY_QUERY_FIELDS);
+  for (const field of ["prefix", ...QUERY_EDGES]) {
+    checkKey(query[field], field);
+  }
+  for (const key of rangeBounds(query)) checkKey(key, "range");
+  return query;
+}
+
+/**
+ * Lists the closed bounds of a checked query's range. A `null` bound is open.
+ * @param {object} query - A query checked by {@link queryOptions}.
+ * @returns {Array<*>} The bounds that are not `null`.
+ * @private
+ */
+function rangeBounds(query) {
+  return (query.range ?? []).filter((bound) => bound !== null);
+}
+
+/**
+ * Checks a string-key query option.
+ * @param {*} key - The option value, or `undefined` when it is not set.
+ * @param {string} field - The option name.
+ * @throws {TypeError} If the value is not a string.
+ * @private
+ */
+function checkKey(key, field) {
+  if (key !== undefined && typeof key !== "string") {
+    throw new TypeError(
+      `${field}: expected a string key, got ${describeValue(key)}`,
+    );
+  }
+}
+
+/**
+ * Checks the options of a deque query. Positions count from the front and
+ * must be non-negative.
+ * @param {string|object} [options] - A scan direction or a position query.
+ * @returns {object} The position query.
+ * @throws {TypeError|RangeError} If an option is invalid.
+ * @private
+ */
+function positionQuery(options) {
+  const query = queryOptions(options, POSITION_QUERY_FIELDS);
+  for (const field of QUERY_EDGES) checkCount(query[field], field, 0);
+  for (const position of rangeBounds(query)) checkCount(position, "range", 0);
+  return query;
+}
+
+/**
+ * Resolves an `at` index to a front position. A negative index counts from
+ * the back and reads the length. The handler owns the deque, so nothing
+ * changes it between the reads.
+ * @param {*} index - The caller's index.
+ * @param {() => Promise<number>} length - Reads the deque length.
+ * @returns {Promise<number|null>} The position, or null outside the deque.
+ * @throws {TransientStateError} If `index` is not a safe integer.
+ * @private
+ */
+async function dequePosition(index, length) {
+  if (!Number.isSafeInteger(index)) {
+    throw new TransientStateError(
+      `at: index must be a safe integer, got ${describeValue(index)}`,
+    );
+  }
+  const position = index < 0 ? index + (await length()) : index;
+  // Native get takes a u32. A larger position is past the end.
+  return position < 0 || position > 0xffffffff ? null : position;
+}
+
+module.exports = {
+  dequePosition,
+  keyQuery,
+  positionQuery,
+};

package/lib/state/set.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The ordered-set keyed-state handle.
+ * @module lib/state/set
+ */
+
+import type { StateTransaction } from "./handle";
+import type { KeyQueryOptions, ScanDirection } from "./query";
+
+/**
+ * Handle over a presence-only ordered set of string members, vended by
+ * `Context.state()`. It mirrors the JavaScript `Set` with asynchronous
+ * methods. Valid only within the handler invocation (attempt) that vended it.
+ * A failed call rejects with a {@link PermanentStateError} or a
+ * {@link TransientStateError}.
+ */
+export declare class SetState {
+  /** Vended only by {@link Context#state}; not constructible directly. */
+  private constructor(native: unknown);
+  /** Adds `member` to the set. */
+  add(member: string): Promise<void>;
+  /** Reports whether `member` belongs to the set. */
+  has(member: string): Promise<boolean>;
+  /**
+   * Tests several members in one read. `result[i]` answers `members[i]`.
+   */
+  hasMany(members: readonly string[]): Promise<boolean[]>;
+  /**
+   * Removes `member`. An absent member is not an error. Unlike `Set#delete`,
+   * this returns no "was present" flag, because that flag needs a read.
+   */
+  delete(member: string): Promise<void>;
+  /** Removes every member. */
+  clear(): Promise<void>;
+  /** Reports whether the set has no live members. */
+  isEmpty(): Promise<boolean>;
+  /**
+   * Async iterator over the members in order. Pass a direction or a
+   * {@link KeyQueryOptions} to select members. Early exit from a `for await` loop
+   * closes the underlying cursor.
+   */
+  keys(
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<string>;
+  /** The same iterator as {@link SetState#keys}, as on the JavaScript `Set`. */
+  values(
+    options?: ScanDirection | KeyQueryOptions,
+  ): AsyncIterableIterator<string>;
+  /** Forward iteration over the members. */
+  [Symbol.asyncIterator](): AsyncIterableIterator<string>;
+}
+
+export interface SetState extends StateTransaction {}

package/lib/state/set.js

@@ -0,0 +1,54 @@
+/**
+ * The ordered-set keyed-state handle.
+ * @module lib/state/set
+ * @private
+ */
+
+const { stateOp } = require("./bridge");
+const { StateHandle } = require("./handle");
+const { stateIterator } = require("./iterator");
+const { keyQuery } = require("./query");
+
+/** Handle over a presence-only ordered set of string members. */
+class SetState extends StateHandle {
+  add(member) {
+    return stateOp((carrier) => this.native.insert(member, carrier));
+  }
+
+  has(member) {
+    return stateOp((carrier) => this.native.contains(member, carrier));
+  }
+
+  hasMany(members) {
+    return stateOp((carrier) => this.native.containsMany(members, carrier));
+  }
+
+  delete(member) {
+    return stateOp((carrier) => this.native.remove(member, carrier));
+  }
+
+  clear() {
+    return stateOp((carrier) => this.native.clear(carrier));
+  }
+
+  isEmpty() {
+    return stateOp((carrier) => this.native.isEmpty(carrier));
+  }
+
+  keys(options) {
+    const query = keyQuery(options);
+    return stateIterator(this.native.keys(query), (member) => member);
+  }
+
+  values(options) {
+    return this.keys(options);
+  }
+
+  [Symbol.asyncIterator]() {
+    return this.values();
+  }
+}
+
+module.exports = {
+  SetState,
+};

package/lib/state/value.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The single-value keyed-state handle.
+ * @module lib/state/value
+ */
+
+import type { JsonValue } from "../payload";
+import type { StateTransaction } from "./handle";
+
+/**
+ * Typed handle over a single-value 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 ValueState<T = JsonValue> {
+  /** Vended only by {@link Context#state}; not constructible directly. */
+  private constructor(native: unknown);
+  /** Reads the current value, or null when absent/cleared. */
+  get(): Promise<T | null>;
+  /**
+   * Buffers a write of the value. The parameter 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 ValueState#clear} to delete. A nested `null` is stored.
+   */
+  set(value: NonNullable<T>): Promise<void>;
+  /** Deletes the stored value. */
+  clear(): Promise<void>;
+}
+
+export interface ValueState<T = JsonValue> extends StateTransaction {}

package/lib/state/value.js

@@ -0,0 +1,31 @@
+/**
+ * The single-value keyed-state handle.
+ * @module lib/state/value
+ * @private
+ */
+
+const { stateOp } = require("./bridge");
+const { StateHandle } = require("./handle");
+
+/** Typed handle over a single-value keyed-state collection. */
+class ValueState extends StateHandle {
+  get() {
+    return stateOp((carrier) => this.native.get(carrier)).then(
+      this.items.decode,
+    );
+  }
+
+  set(value) {
+    return stateOp((carrier) =>
+      this.native.set(this.items.encode(value), carrier),
+    );
+  }
+
+  clear() {
+    return stateOp((carrier) => this.native.clear(carrier));
+  }
+}
+
+module.exports = {
+  ValueState,
+};

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@prosody-events/prosody",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
     "index.js",
     "index.d.ts",
+    "lib",
     "bindings.js",
     "bindings.d.ts",
     "README.md"
@@ -30,24 +31,24 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/exporter-trace-otlp-proto": "^0.221.0"
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.222.0"
   },
   "devDependencies": {
     "@babel/core": "^8",
     "@babel/plugin-proposal-decorators": "^8",
     "@babel/preset-env": "^8",
-    "@napi-rs/cli": "^3.8.6",
-    "@opentelemetry/auto-instrumentations-node": "^0.79.0",
-    "@opentelemetry/core": "^2.10.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
-    "@opentelemetry/sdk-metrics": "^2.10.0",
-    "@opentelemetry/sdk-node": "^0.221.0",
-    "@opentelemetry/sdk-trace-base": "^2.10.0",
-    "@opentelemetry/sdk-trace-node": "^2.10.0",
-    "@sentry/node": "^10.70.0",
-    "@types/node": "^24",
-    "jest": "^30.4.2",
-    "prettier": "^3.9.6",
+    "@napi-rs/cli": "^3.10.5",
+    "@opentelemetry/auto-instrumentations-node": "^0.80.0",
+    "@opentelemetry/core": "^2.11.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/sdk-metrics": "^2.11.0",
+    "@opentelemetry/sdk-node": "^0.222.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@opentelemetry/sdk-trace-node": "^2.11.0",
+    "@sentry/node": "^11.1.0",
+    "@types/node": "^26",
+    "jest": "^30.5.2",
+    "prettier": "^3.9.9",
     "typescript": "^7.0.2",
     "yarn-upgrade-all": "^0.8.1"
   },
@@ -66,7 +67,7 @@
     "universal": "napi universalize",
     "version": "napi version"
   },
-  "packageManager": "yarn@4.4.0",
+  "packageManager": "yarn@4.18.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/prosody-events/prosody-js.git"
@@ -77,9 +78,9 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@prosody-events/prosody-linux-x64-gnu": "0.5.1",
-    "@prosody-events/prosody-win32-x64-msvc": "0.5.1",
-    "@prosody-events/prosody-darwin-arm64": "0.5.1",
-    "@prosody-events/prosody-linux-arm64-gnu": "0.5.1"
+    "@prosody-events/prosody-linux-x64-gnu": "0.6.1",
+    "@prosody-events/prosody-win32-x64-msvc": "0.6.1",
+    "@prosody-events/prosody-darwin-arm64": "0.6.1",
+    "@prosody-events/prosody-linux-arm64-gnu": "0.6.1"
   }
-}
+}