@prosody-events/prosody 0.4.0 → 0.5.0

package/index.d.ts

@@ -5,14 +5,30 @@
  */
 
 import type {
+  AdminClient,
   Configuration,
   ConsumerState,
+  ExciseMessage as NativeExciseMessage,
   Message as NativeMessage,
   Mode,
+  ReadCacheConfiguration,
   Timer,
 } from "./bindings";
 
-export { Configuration, ConsumerState, Timer, Mode };
+export {
+  AdminClient,
+  Configuration,
+  ConsumerState,
+  ReadCacheConfiguration,
+  Timer,
+  Mode,
+};
+
+/** Exports all pending telemetry data. */
+export function flushTelemetry(): void;
+
+/** Stops the global telemetry providers after they export pending data. */
+export function shutdownTelemetry(): void;
 
 /** A primitive value representable in JSON. */
 export type JsonPrimitive = null | boolean | number | string;
@@ -33,7 +49,7 @@ export type JsonValue =
  */
 export type JsonCompatible<T> = T extends JsonPrimitive
   ? T
-  : T extends bigint | symbol | undefined | ((...args: any[]) => unknown)
+  : T extends bigint | symbol | undefined | ((...args: never[]) => unknown)
     ? never
     : T extends readonly (infer Item)[]
       ? readonly JsonCompatible<Item>[]
@@ -41,6 +57,9 @@ export type JsonCompatible<T> = T extends JsonPrimitive
         ? { readonly [Key in keyof T]: JsonCompatible<T[Key]> }
         : never;
 
+/** A value that a handler can return now or through a promise. */
+export type MaybePromise<T> = T | PromiseLike<T>;
+
 /**
  * Represents a message consumed from a Kafka topic.
  *
@@ -48,12 +67,19 @@ export type JsonCompatible<T> = T extends JsonPrimitive
  * 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>`.
+ *
+ * A message can be stored into a message collection, whether it arrived from the
+ * topic or was read back out of a collection. What is stored is the message
+ * itself, so mutating its parsed `payload` does not change what is written.
  */
 export interface Message<P = JsonValue> extends Omit<NativeMessage, "payload"> {
   /** The message payload as a JSON-serializable value. */
   payload: P;
 }
 
+/** An excise record with Kafka metadata and no payload. */
+export type ExciseMessage = NativeExciseMessage;
+
 /**
  * Wrapper around `MessageContext` for use in Node.js bindings.
  * Automatically injects OpenTelemetry context for all operations.
@@ -185,8 +211,16 @@ export interface StateDefinitionOptions {
   readUncommitted?: boolean;
 }
 
+/** Options accepted by JSON collections that may be published. */
+export interface PublishedStateDefinitionOptions extends StateDefinitionOptions {
+  /** Allow read-only access from other consumer groups. */
+  published?: boolean;
+  /** Override caching when this descriptor opens a published reader. */
+  readCache?: ReadCacheOptions | false;
+}
+
 /** Options accepted by the map definition constructors. */
-export interface MapDefinitionOptions extends StateDefinitionOptions {
+export interface MapDefinitionOptions extends PublishedStateDefinitionOptions {
   /**
    * Keyset bound for ordered scans (`0..=4096`; default 128 core-side; `0`
    * disables ordered-scan tracking). Map collections only.
@@ -195,7 +229,7 @@ export interface MapDefinitionOptions extends StateDefinitionOptions {
 }
 
 /** Options accepted by the deque definition constructors. */
-export interface DequeDefinitionOptions extends StateDefinitionOptions {
+export interface DequeDefinitionOptions extends PublishedStateDefinitionOptions {
   /**
    * Optional maximum element count (bounded backlog). Must be a whole number
    * >= 1. Runtime-only: not persisted, not part of collection identity, and
@@ -206,47 +240,70 @@ export interface DequeDefinitionOptions extends StateDefinitionOptions {
   capacity?: number;
 }
 
+/** Options accepted by message-map definitions, which cannot be published. */
+export interface MessageMapDefinitionOptions extends StateDefinitionOptions {
+  /** Keyset bound for ordered scans (`0..=4096`; default 128 core-side). */
+  keysetLimit?: number;
+}
+
+/** Options accepted by message-deque definitions, which cannot be published. */
+export interface MessageDequeDefinitionOptions extends StateDefinitionOptions {
+  /** Optional maximum element count. Must be a whole number >= 1. */
+  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;
+declare const StateDescriptor: unique symbol;
+
+interface DefinitionBrand {
+  readonly [StateDescriptor]: true;
+}
 
 /** A frozen single-value JSON collection definition. */
-export interface ValueDefinition<T = JsonValue> {
+export interface ValueDefinition<T = JsonValue> extends DefinitionBrand {
   readonly name: string;
   readonly kind: "value";
   readonly payload: "json";
   readonly ttlSeconds?: number;
   readonly readUncommitted?: boolean;
+  readonly published?: boolean;
+  readonly readCache?: ReadCacheOptions | false;
   readonly [StateItem]?: T;
 }
 
 /** A frozen ordered-map JSON collection definition (string keys). */
-export interface MapDefinition<V = JsonValue> {
+export interface MapDefinition<V = JsonValue> extends DefinitionBrand {
   readonly name: string;
   readonly kind: "map";
   readonly payload: "json";
   readonly ttlSeconds?: number;
   readonly readUncommitted?: boolean;
+  readonly published?: boolean;
+  readonly readCache?: ReadCacheOptions | false;
   readonly keysetLimit?: number;
   readonly [StateItem]?: V;
 }
 
 /** A frozen deque JSON collection definition. */
-export interface DequeDefinition<T = JsonValue> {
+export interface DequeDefinition<T = JsonValue> extends DefinitionBrand {
   readonly name: string;
   readonly kind: "deque";
   readonly payload: "json";
   readonly ttlSeconds?: number;
   readonly readUncommitted?: boolean;
+  readonly published?: boolean;
+  readonly readCache?: ReadCacheOptions | false;
   readonly capacity?: number;
   readonly [StateItem]?: T;
 }
 
 /** A frozen single-value message collection definition (items are `Message<P>`). */
-export interface MessageValueDefinition<P = JsonValue> {
+export interface MessageValueDefinition<P = JsonValue> extends DefinitionBrand {
   readonly name: string;
   readonly kind: "value";
   readonly payload: "message";
@@ -256,7 +313,7 @@ export interface MessageValueDefinition<P = JsonValue> {
 }
 
 /** A frozen ordered-map message collection definition (values are `Message<P>`). */
-export interface MessageMapDefinition<P = JsonValue> {
+export interface MessageMapDefinition<P = JsonValue> extends DefinitionBrand {
   readonly name: string;
   readonly kind: "map";
   readonly payload: "message";
@@ -267,7 +324,7 @@ export interface MessageMapDefinition<P = JsonValue> {
 }
 
 /** A frozen deque message collection definition (elements are `Message<P>`). */
-export interface MessageDequeDefinition<P = JsonValue> {
+export interface MessageDequeDefinition<P = JsonValue> extends DefinitionBrand {
   readonly name: string;
   readonly kind: "deque";
   readonly payload: "message";
@@ -284,11 +341,12 @@ export interface MessageDequeDefinition<P = JsonValue> {
  * 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`.
+ * @param options - Optional retention, transaction, publication, and read-cache
+ *   settings.
  */
 export function value<T = JsonValue>(
   name: string,
-  options?: StateDefinitionOptions,
+  options?: PublishedStateDefinitionOptions,
 ): ValueDefinition<T>;
 
 /**
@@ -297,7 +355,8 @@ export function value<T = JsonValue>(
  * 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`.
+ * @param options - Optional retention, transaction, publication, read-cache,
+ *   and `keysetLimit` settings.
  */
 export function map<V = JsonValue>(
   name: string,
@@ -309,8 +368,8 @@ export function map<V = JsonValue>(
  * 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).
+ * @param options - Optional retention, transaction, publication, read-cache,
+ *   and `capacity` settings.
  */
 export function deque<T = JsonValue>(
   name: string,
@@ -338,7 +397,7 @@ export function messageValue<P = JsonValue>(
  */
 export function messageMap<P = JsonValue>(
   name: string,
-  options?: MapDefinitionOptions,
+  options?: MessageMapDefinitionOptions,
 ): MessageMapDefinition<P>;
 
 /**
@@ -351,7 +410,7 @@ export function messageMap<P = JsonValue>(
  */
 export function messageDeque<P = JsonValue>(
   name: string,
-  options?: DequeDefinitionOptions,
+  options?: MessageDequeDefinitionOptions,
 ): MessageDequeDefinition<P>;
 
 /**
@@ -538,31 +597,52 @@ export declare class DequeState<T = JsonValue> {
  */
 export interface Logger {
   /** Logs error-level messages. */
-  error: (message: string | undefined | null, metadata?: any) => void;
+  error: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs warning-level messages. */
-  warn: (message: string | undefined | null, metadata?: any) => void;
+  warn: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs info-level messages. */
-  info: (message: string | undefined | null, metadata?: any) => void;
+  info: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs debug-level messages. */
-  debug: (message: string | undefined | null, metadata?: any) => void;
+  debug: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Logs trace-level messages. */
-  trace: (message: string | undefined | null, metadata?: any) => void;
+  trace: (
+    message: string | undefined | null,
+    metadata?: Record<string, unknown>,
+  ) => void;
 }
 
-export interface EventHandler<P = JsonValue> {
+export interface EventHandler<P = JsonValue, R = JsonValue> {
+  /** Handles an excise record. */
+  onExcise: (
+    context: Context,
+    message: ExciseMessage,
+    signal: AbortSignal,
+  ) => MaybePromise<R & JsonCompatible<R>>;
   /**
    * Callback function to handle incoming messages.
    *
    * @param context - The context of the message processing.
    * @param message - The received Kafka message.
    * @param signal - An AbortSignal that can be used to cancel the message processing.
-   * @returns A promise that resolves when the message has been processed.
+   * @returns A JSON response for subsystem requests. JSON null is valid.
    */
-  onMessage?: (
+  onMessage: (
     context: Context,
     message: Message<P>,
     signal: AbortSignal,
-  ) => Promise<void>;
+  ) => MaybePromise<R & JsonCompatible<R>>;
 
   /**
    * Callback function to handle timers.
@@ -570,22 +650,56 @@ export interface EventHandler<P = JsonValue> {
    * @param context - The context of the message processing.
    * @param timer - The triggered timer.
    * @param signal - An AbortSignal that can be used to cancel the message processing.
-   * @returns A promise that resolves when the timer has been processed.
+   * @returns No value.
    */
-  onTimer?: (
+  onTimer: (
     context: Context,
     timer: Timer,
     signal: AbortSignal,
-  ) => Promise<void>;
+  ) => MaybePromise<void>;
+}
+
+/** One successful subsystem outcome. */
+export interface Success<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+/** One failed subsystem outcome. */
+export interface Failure {
+  readonly ok: false;
+  readonly error: ResponseError;
+}
+
+/** One subsystem outcome. */
+export type Outcome<T> = Success<T> | Failure;
+
+/** One subsystem failure. */
+export type ResponseError =
+  | { readonly kind: "handler"; readonly message: string }
+  | { readonly kind: "timeout"; readonly message: string }
+  | { readonly kind: "formatMismatch"; readonly message: string }
+  | { readonly kind: "malformedResponse"; readonly message: string };
+
+/** Request targets, deadline, and cancellation. */
+export interface RequestOptions {
+  /** The subsystems that must respond. */
+  readonly subsystems: readonly string[];
+  /** The response deadline in milliseconds. */
+  readonly timeoutMs: number;
+  /** Cancels the local wait. */
+  readonly signal?: AbortSignal;
 }
 
 export declare class ProsodyClient {
+  private constructor();
+
   /**
-   * Creates a new ProsodyClient instance.
+   * Creates a Prosody client without blocking the Node.js event loop.
    *
    * @param config - The configuration options for the client.
    */
-  constructor(config: Configuration);
+  static create(config: Configuration): Promise<ProsodyClient>;
 
   /**
    * Gets the current state of the consumer.
@@ -611,6 +725,22 @@ export declare class ProsodyClient {
    */
   isStalled(): Promise<boolean>;
 
+  /** Opens a read-only view of a published JSON value collection. */
+  state<T>(
+    subsystem: string,
+    definition: ValueDefinition<T>,
+  ): Promise<PublishedValue<T>>;
+  /** Opens a read-only view of a published JSON map collection. */
+  state<V>(
+    subsystem: string,
+    definition: MapDefinition<V>,
+  ): Promise<PublishedMap<V>>;
+  /** Opens a read-only view of a published JSON deque collection. */
+  state<T>(
+    subsystem: string,
+    definition: DequeDefinition<T>,
+  ): Promise<PublishedDeque<T>>;
+
   /**
    * Gets the source system identifier configured for the client.
    *
@@ -635,22 +765,89 @@ export declare class ProsodyClient {
     signal?: AbortSignal,
   ): Promise<void>;
 
+  /** Sends an excise record for a key. */
+  excise(topic: string, key: string, signal?: AbortSignal): Promise<void>;
+
+  /**
+   * Sends a request and returns one outcome for each subsystem.
+   *
+   * The map contains every selected subsystem. A missing response has a timeout outcome.
+   * @throws Error if the input is invalid, sending fails, shutdown starts, or the signal aborts.
+   */
+  request<R = JsonValue>(
+    topic: string,
+    key: string,
+    payload: JsonValue,
+    options: RequestOptions,
+  ): Promise<ReadonlyMap<string, Outcome<R>>>;
+
+  /** Sends an excise request and returns one outcome for each subsystem. */
+  requestExcise<R = JsonValue>(
+    topic: string,
+    key: string,
+    options: RequestOptions,
+  ): Promise<ReadonlyMap<string, Outcome<R>>>;
+
   /**
    * Subscribes to receive messages using the provided event handler.
    *
    * @param eventHandler - The event handler to process received messages and timers.
    * @returns A promise that resolves when the subscription is successfully established and the consumer is ready to receive messages.
+   * @throws TypeError if any required handler method is missing.
    * @throws Error if the subscription fails to establish.
    */
-  subscribe<P = JsonValue>(eventHandler: EventHandler<P>): Promise<void>;
+  subscribe<P = JsonValue, R = JsonValue>(
+    eventHandler: EventHandler<P, R>,
+  ): Promise<void>;
 
   /**
-   * Unsubscribes from receiving messages and shuts down the consumer.
+   * Stops the consumer. You can subscribe again later.
    *
    * @returns A promise that resolves when the unsubscribe operation is complete.
    * @throws Error if the unsubscribe operation fails.
    */
   unsubscribe(): Promise<void>;
+
+  /**
+   * Shuts down the client and all its services.
+   * Concurrent and repeated calls await the same shutdown operation.
+   *
+   * @returns A promise that resolves when shutdown is complete.
+   * @throws Error if shutdown fails.
+   */
+  shutdown(): Promise<void>;
+}
+
+/** 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> {
+  get(key: string): Promise<T | null>;
+}
+
+/** Read-only published map collection. */
+export declare class PublishedMap<V = JsonValue> {
+  get(key: string, mapKey: string): Promise<V | null>;
+  getMany(key: string, mapKeys: string[]): Promise<Array<V | null>>;
+  has(key: string, mapKey: string): Promise<boolean>;
+  entries(
+    key: string,
+    direction?: ScanDirection,
+  ): AsyncIterableIterator<[string, V]>;
+  keys(key: string, direction?: ScanDirection): AsyncIterableIterator<string>;
+  values(key: string, direction?: ScanDirection): AsyncIterableIterator<V>;
+}
+
+/** Read-only published deque collection. */
+export declare class PublishedDeque<T = JsonValue> {
+  length(key: string): Promise<number>;
+  isEmpty(key: string): Promise<boolean>;
+  at(key: string, index: number): Promise<T | null>;
+  values(key: string, direction?: ScanDirection): AsyncIterableIterator<T>;
 }
 
 /**
@@ -765,7 +962,7 @@ export function isStateError(
 ): error is PermanentStateError | TransientStateError;
 
 /** Type alias for a constructor of an Error subclass. */
-type ErrorClass<T extends Error> = new (...args: any[]) => T;
+type ErrorClass<T extends Error> = new (...args: never[]) => T;
 
 /**
  * Type for a decorator function that can be applied to both methods and standalone functions.