@prosody-events/prosody 0.3.0 → 0.4.0

package/index.d.ts

@@ -7,12 +7,52 @@
 import type {
   Configuration,
   ConsumerState,
-  Message,
+  Message as NativeMessage,
   Mode,
   Timer,
 } from "./bindings";
 
-export { Configuration, ConsumerState, Message, Timer, Mode };
+export { Configuration, ConsumerState, Timer, Mode };
+
+/** A primitive value representable in JSON. */
+export type JsonPrimitive = null | boolean | number | string;
+
+/**
+ * Any value representable in JSON.
+ *
+ * This is a compile-time contract. Prosody serializes payloads at runtime but
+ * does not validate them against a more specific application payload type.
+ */
+export type JsonValue =
+  JsonPrimitive | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+
+/**
+ * Maps an application type to its JSON-compatible shape. This lets APIs
+ * accept ordinary interfaces and type aliases without requiring an index
+ * signature, while rejecting non-JSON members wherever they are nested.
+ */
+export type JsonCompatible<T> = T extends JsonPrimitive
+  ? T
+  : T extends bigint | symbol | undefined | ((...args: any[]) => unknown)
+    ? never
+    : T extends readonly (infer Item)[]
+      ? readonly JsonCompatible<Item>[]
+      : T extends object
+        ? { readonly [Key in keyof T]: JsonCompatible<T[Key]> }
+        : never;
+
+/**
+ * Represents a message consumed from a Kafka topic.
+ *
+ * The optional payload type parameter is annotation-level only: the runtime
+ * payload is unchanged. An unparameterized `Message` uses {@link JsonValue};
+ * provide an application payload type for precise field-level checking.
+ * Message-backed keyed-state collections vend their items as `Message<P>`.
+ */
+export interface Message<P = JsonValue> extends Omit<NativeMessage, "payload"> {
+  /** The message payload as a JSON-serializable value. */
+  payload: P;
+}
 
 /**
  * Wrapper around `MessageContext` for use in Node.js bindings.
@@ -74,6 +114,421 @@ export declare class Context {
    * @throws Error if retrieval fails.
    */
   scheduled(): Promise<Array<Date>>;
+
+  /**
+   * Binds a registered message single-value collection, vending a handle whose
+   * item is the full `Message<P>`.
+   *
+   * The handle and any iterator it opens are valid only within this event
+   * attempt. Throws a {@link PermanentStateError} if the collection name is
+   * unregistered or its registered identity mismatches.
+   * @param definition - A definition from {@link messageValue}.
+   */
+  state<P>(definition: MessageValueDefinition<P>): ValueState<Message<P>>;
+  /**
+   * Binds a registered message ordered-map collection, vending a handle whose
+   * values are the full `Message<P>`. Valid only within this event attempt;
+   * throws {@link PermanentStateError} on an unregistered name or identity
+   * mismatch.
+   * @param definition - A definition from {@link messageMap}.
+   */
+  state<P>(definition: MessageMapDefinition<P>): MapState<Message<P>>;
+  /**
+   * Binds a registered message deque collection, vending a handle whose
+   * elements are the full `Message<P>`. Valid only within this event attempt;
+   * throws {@link PermanentStateError} on an unregistered name or identity
+   * mismatch.
+   * @param definition - A definition from {@link messageDeque}.
+   */
+  state<P>(definition: MessageDequeDefinition<P>): DequeState<Message<P>>;
+  /**
+   * Binds a registered single-value JSON collection. Valid only within this
+   * event attempt; throws {@link PermanentStateError} on an unregistered name
+   * or identity mismatch.
+   * @param definition - A definition from {@link value}.
+   */
+  state<T>(definition: ValueDefinition<T>): ValueState<T>;
+  /**
+   * Binds a registered ordered-map JSON collection (string keys). Valid only
+   * within this event attempt; throws {@link PermanentStateError} on an
+   * unregistered name or identity mismatch.
+   * @param definition - A definition from {@link map}.
+   */
+  state<V>(definition: MapDefinition<V>): MapState<V>;
+  /**
+   * Binds a registered deque JSON collection. Valid only within this event
+   * attempt; throws {@link PermanentStateError} on an unregistered name or
+   * identity mismatch.
+   * @param definition - A definition from {@link deque}.
+   */
+  state<T>(definition: DequeDefinition<T>): DequeState<T>;
+}
+
+/**
+ * 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";
+
+/** Options accepted by every keyed-state definition constructor. */
+export interface StateDefinitionOptions {
+  /**
+   * Optional per-write TTL in whole seconds. Must be at least 1 and must
+   * exceed the client's recovery delay (enforced core-side).
+   */
+  ttlSeconds?: number;
+  /**
+   * Opt out of transactional staging (read-uncommitted, at-least-once).
+   * Defaults to transactional.
+   */
+  readUncommitted?: boolean;
+}
+
+/** Options accepted by the map definition constructors. */
+export interface MapDefinitionOptions extends StateDefinitionOptions {
+  /**
+   * Keyset bound for ordered scans (`0..=4096`; default 128 core-side; `0`
+   * disables ordered-scan tracking). Map collections only.
+   */
+  keysetLimit?: number;
+}
+
+/** Options accepted by the deque definition constructors. */
+export interface DequeDefinitionOptions extends StateDefinitionOptions {
+  /**
+   * Optional maximum element count (bounded backlog). Must be a whole number
+   * >= 1. Runtime-only: not persisted, not part of collection identity, and
+   * changeable across deploys. Enforced lazily on push — the opposite end is
+   * evicted toward the bound (no decode, no fetch); a shrunk deque reports its
+   * old length until the next push trims it. Deque collections only.
+   */
+  capacity?: number;
+}
+
+/**
+ * Phantom brand carrying a definition's item type. Never present at runtime —
+ * it exists only so the item type survives on the frozen definition object and
+ * flows into the vended handle.
+ */
+declare const StateItem: unique symbol;
+
+/** A frozen single-value JSON collection definition. */
+export interface ValueDefinition<T = JsonValue> {
+  readonly name: string;
+  readonly kind: "value";
+  readonly payload: "json";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly [StateItem]?: T;
+}
+
+/** A frozen ordered-map JSON collection definition (string keys). */
+export interface MapDefinition<V = JsonValue> {
+  readonly name: string;
+  readonly kind: "map";
+  readonly payload: "json";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly keysetLimit?: number;
+  readonly [StateItem]?: V;
+}
+
+/** A frozen deque JSON collection definition. */
+export interface DequeDefinition<T = JsonValue> {
+  readonly name: string;
+  readonly kind: "deque";
+  readonly payload: "json";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly capacity?: number;
+  readonly [StateItem]?: T;
+}
+
+/** A frozen single-value message collection definition (items are `Message<P>`). */
+export interface MessageValueDefinition<P = JsonValue> {
+  readonly name: string;
+  readonly kind: "value";
+  readonly payload: "message";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly [StateItem]?: P;
+}
+
+/** A frozen ordered-map message collection definition (values are `Message<P>`). */
+export interface MessageMapDefinition<P = JsonValue> {
+  readonly name: string;
+  readonly kind: "map";
+  readonly payload: "message";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly keysetLimit?: number;
+  readonly [StateItem]?: P;
+}
+
+/** A frozen deque message collection definition (elements are `Message<P>`). */
+export interface MessageDequeDefinition<P = JsonValue> {
+  readonly name: string;
+  readonly kind: "deque";
+  readonly payload: "message";
+  readonly ttlSeconds?: number;
+  readonly readUncommitted?: boolean;
+  readonly capacity?: number;
+  readonly [StateItem]?: P;
+}
+
+/**
+ * Declares a single-value JSON collection. The returned frozen definition is
+ * the single source of typing: place it in `Configuration.stateCollections` to
+ * register the collection, and pass it to `Context.state()` to vend a typed
+ * handle. The type parameter annotates the stored value and is compile-time
+ * only — payloads cross as plain JSON with no runtime validation.
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds) and `readUncommitted`.
+ */
+export function value<T = JsonValue>(
+  name: string,
+  options?: StateDefinitionOptions,
+): ValueDefinition<T>;
+
+/**
+ * Declares an ordered-map JSON collection. Map keys are always `string`. The
+ * returned frozen definition is used both in `Configuration.stateCollections`
+ * and with `Context.state()`. The type parameter annotates the stored value
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds`, `readUncommitted`, and `keysetLimit`.
+ */
+export function map<V = JsonValue>(
+  name: string,
+  options?: MapDefinitionOptions,
+): MapDefinition<V>;
+
+/**
+ * Declares a double-ended-queue JSON collection. The returned frozen definition
+ * is used both in `Configuration.stateCollections` and with `Context.state()`.
+ * The type parameter annotates the stored element (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds), `readUncommitted`, and
+ *   `capacity` (bounded backlog; enforced lazily on push).
+ */
+export function deque<T = JsonValue>(
+  name: string,
+  options?: DequeDefinitionOptions,
+): DequeDefinition<T>;
+
+/**
+ * Declares a single-value message collection: each stored item is the full
+ * Kafka `Message<P>` the handler received. The type parameter annotates the
+ * message payload (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds) and `readUncommitted`.
+ */
+export function messageValue<P = JsonValue>(
+  name: string,
+  options?: StateDefinitionOptions,
+): MessageValueDefinition<P>;
+
+/**
+ * Declares an ordered-map message collection (string keys; values are the full
+ * Kafka `Message<P>`). The type parameter annotates the message payload
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds`, `readUncommitted`, and `keysetLimit`.
+ */
+export function messageMap<P = JsonValue>(
+  name: string,
+  options?: MapDefinitionOptions,
+): MessageMapDefinition<P>;
+
+/**
+ * Declares a double-ended-queue message collection: each stored element is the
+ * full Kafka `Message<P>`. The type parameter annotates the message payload
+ * (compile-time only).
+ * @param name - The collection name (unique per client).
+ * @param options - Optional `ttlSeconds` (whole seconds), `readUncommitted`, and
+ *   `capacity` (bounded backlog; enforced lazily on push).
+ */
+export function messageDeque<P = JsonValue>(
+  name: string,
+  options?: DequeDefinitionOptions,
+): MessageDequeDefinition<P>;
+
+/**
+ * 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.
+ */
+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`/`undefined`
+   * (via {@link !NonNullable}) because a top-level `null` is not a storable
+   * value — writing one (or an unrepresentable value) is a caller mistake,
+   * rejected at runtime with a {@link TransientStateError} naming `clear()` —
+   * use {@link ValueState#clear}. Transient so it retries and stays visible
+   * rather than discarding the message. (Nested `null`, e.g. inside an object or
+   * array, is permitted and round-trips.)
+   */
+  set(value: NonNullable<T>): Promise<void>;
+  /** Deletes the stored value. */
+  clear(): Promise<void>;
+  /**
+   * Durably commits the buffered operations mid-handler (at-least-once).
+   * Resolves with no value — the erased seam drops the store outcome.
+   */
+  commit(): Promise<void>;
+  /** Discards buffered uncommitted operations back to the committed floor. */
+  rollback(): Promise<void>;
+}
+
+/**
+ * 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.
+ */
+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 a single call. Returns an array with one entry per
+   * key, in the same order you asked, so `result[i]` is the value for
+   * `keys[i]`. A key that isn't there comes back as `null`, and a key you list
+   * more than once is answered at each spot. The whole read happens as one
+   * step, so no other change to this event's state can slip in partway through.
+   */
+  getMany(keys: readonly string[]): Promise<(V | null)[]>;
+  /**
+   * Reports whether `key` currently has a stored value. A presence check that
+   * skips the value decode and the resolver: for a message-backed map it
+   * answers with zero Kafka fetches and can report `true` for a message that
+   * can no longer be fetched. Not zero-I/O — a cache miss can still reach the
+   * store — but cheaper than {@link MapState#get} when you only need presence.
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Inserts or overwrites `key`. The value type excludes `null`/`undefined`
+   * (via {@link !NonNullable}) because a top-level `null` is not a storable
+   * value — writing one (or an unrepresentable value) is a caller mistake,
+   * rejected at runtime with a {@link TransientStateError} — use
+   * {@link MapState#delete} to remove. Transient so it retries and stays visible
+   * rather than discarding the message. (Nested `null` is permitted.)
+   */
+  set(key: string, value: NonNullable<V>): Promise<void>;
+  /**
+   * Removes `key`.
+   *
+   * Deliberate divergence from `Map#delete`: returns void, NOT a boolean
+   * "was present" flag — surfacing that boolean would force a hidden read on
+   * every delete. (The underlying native operation is named `remove`.)
+   */
+  delete(key: string): Promise<void>;
+  /** Removes every entry. */
+  clear(): Promise<void>;
+  /**
+   * Async iterator over the live `[key, value]` entries in key order. Valid
+   * only within the handler invocation (attempt) that opened it; early exit
+   * from a `for await` loop closes the underlying cursor.
+   */
+  entries(direction?: ScanDirection): AsyncIterableIterator<[string, V]>;
+  /**
+   * Async iterator over the live keys in key order. 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(direction?: ScanDirection): AsyncIterableIterator<string>;
+  /**
+   * Async iterator over the live values in key order. Valid only within the
+   * handler invocation (attempt) that opened it; early exit from a `for await`
+   * loop closes the underlying cursor.
+   */
+  values(direction?: ScanDirection): AsyncIterableIterator<V>;
+  /**
+   * Forward iteration over `[key, value]` entries. Valid only within the
+   * handler invocation (attempt) that opened it.
+   */
+  [Symbol.asyncIterator](): AsyncIterableIterator<[string, V]>;
+  /**
+   * Durably commits the buffered operations mid-handler (at-least-once).
+   * Resolves with no value — the erased seam drops the store outcome.
+   */
+  commit(): Promise<void>;
+  /** Discards buffered uncommitted operations back to the committed floor. */
+  rollback(): Promise<void>;
+}
+
+/**
+ * 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.
+ */
+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`/`undefined`
+   * (via {@link !NonNullable}) because a top-level `null` is not a storable
+   * element — writing one (or an unrepresentable value) is a caller mistake,
+   * rejected at runtime with a {@link TransientStateError} so it retries and
+   * stays visible rather than discarding the message. (Nested `null` is
+   * permitted.)
+   */
+  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).
+   *
+   * The endpoints `at(0)` and `at(-1)` ride the front/back peeks — a single
+   * read, and `at(-1)` makes no length read. Any other negative `index` is
+   * resolved against the current {@link DequeState#length}, so it makes an
+   * extra boundary crossing that a non-negative one does not.
+   */
+  at(index: number): Promise<T | null>;
+  /**
+   * Async iterator over the live elements in index order. Valid only within
+   * the handler invocation (attempt) that opened it; early exit from a
+   * `for await` loop closes the underlying cursor.
+   */
+  values(direction?: ScanDirection): AsyncIterableIterator<T>;
+  /**
+   * Forward iteration over the elements. Valid only within the handler
+   * invocation (attempt) that opened it.
+   */
+  [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+  /**
+   * Durably commits the buffered operations mid-handler (at-least-once).
+   * Resolves with no value — the erased seam drops the store outcome.
+   */
+  commit(): Promise<void>;
+  /** Discards buffered uncommitted operations back to the committed floor. */
+  rollback(): Promise<void>;
 }
 
 /**
@@ -94,7 +549,7 @@ export interface Logger {
   trace: (message: string | undefined | null, metadata?: any) => void;
 }
 
-export interface EventHandler {
+export interface EventHandler<P = JsonValue> {
   /**
    * Callback function to handle incoming messages.
    *
@@ -105,7 +560,7 @@ export interface EventHandler {
    */
   onMessage?: (
     context: Context,
-    message: Message,
+    message: Message<P>,
     signal: AbortSignal,
   ) => Promise<void>;
 
@@ -173,10 +628,10 @@ export declare class ProsodyClient {
    * @returns A promise that resolves when the message has been successfully sent.
    * @throws Error if the send operation fails or is aborted.
    */
-  send(
+  send<P>(
     topic: string,
     key: string,
-    payload: unknown,
+    payload: P & JsonCompatible<P>,
     signal?: AbortSignal,
   ): Promise<void>;
 
@@ -187,7 +642,7 @@ export declare class ProsodyClient {
    * @returns A promise that resolves when the subscription is successfully established and the consumer is ready to receive messages.
    * @throws Error if the subscription fails to establish.
    */
-  subscribe(eventHandler: EventHandler): Promise<void>;
+  subscribe<P = JsonValue>(eventHandler: EventHandler<P>): Promise<void>;
 
   /**
    * Unsubscribes from receiving messages and shuts down the consumer.
@@ -277,6 +732,38 @@ export class PermanentError extends EventHandlerError {
   get isPermanent(): true;
 }
 
+/**
+ * Represents a transient keyed-state failure that may succeed on a later
+ * attempt — a store read/write timeout, AND every caller mistake (a
+ * null/unrepresentable write, an item-shape mismatch, an out-of-range index, an
+ * invalid scan direction). Caller mistakes are transient on purpose so they
+ * retry and stay visible rather than discarding the message. Subclasses
+ * {@link TransientError}, so rethrowing it from a handler classifies the event
+ * transient through the existing error bridge unchanged.
+ */
+export class TransientStateError extends TransientError {}
+
+/**
+ * Represents a permanent keyed-state failure a retry cannot resolve in-process
+ * — an unregistered collection name, a registered-identity mismatch, or a
+ * duplicate registration (or one a handler throws explicitly). Caller mistakes
+ * are NOT permanent; they are {@link TransientStateError}. Subclasses
+ * {@link PermanentError}, so rethrowing it from a handler classifies the event
+ * permanent through the existing error bridge unchanged.
+ */
+export class PermanentStateError extends PermanentError {}
+
+/**
+ * Name-branded predicate that narrows to either keyed-state error class,
+ * regardless of category.
+ *
+ * @param error - The value to test.
+ * @returns True when the value is a keyed-state error.
+ */
+export function isStateError(
+  error: unknown,
+): error is PermanentStateError | TransientStateError;
+
 /** Type alias for a constructor of an Error subclass. */
 type ErrorClass<T extends Error> = new (...args: any[]) => T;