@znight/messaging 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,459 @@
+import { a as DriverDelivery, c as SubscribeOptions, d as InboundMessage, f as OutboundMessage, i as DriverContext, l as Subscription, m as PublishResult, n as DeliveryHandler, o as MessagingDriver, p as PublishOptions, r as DriverCapabilities, s as RetryRequest, t as DeadLetterRequest, u as DeadLetterReason } from "./driver-ZxLqy_Ap.mjs";
+import { ClassMarker, CoreLogger, MessagePublishEvent, MethodMarker, ParameterMarker, Plugin, PluginOptions, Scope, Token, TypedToken, ZnightError } from "@znight/core";
+/** Backoff strategy between attempts. */
+type BackoffStrategy = "fixed" | "exponential";
+/** Options of `@Retry()` and of the plugin's `defaults.retry`. */
+interface RetryOptions {
+  /** Total number of attempts, including the first delivery (`1`: no retry). */
+  readonly attempts: number;
+  /** `fixed`: always `delay`; `exponential`: `delay * 2^(attempt - 1)`, capped by `maxDelay`. Default: `exponential`. */
+  readonly backoff?: BackoffStrategy;
+  /** Base delay between attempts, in milliseconds. Default: 1000. */
+  readonly delay?: number;
+  /** Upper bound of exponential delays, in milliseconds. */
+  readonly maxDelay?: number;
+}
+/** A normalized retry policy, as stored in the metadata (`MessageHandlerDefinition.retry`). */
+interface RetryPolicy {
+  readonly attempts: number;
+  readonly backoff: BackoffStrategy;
+  readonly delay: number;
+  readonly maxDelay?: number;
+}
+/** Default base delay of a retry policy, in milliseconds. */
+export declare const DEFAULT_RETRY_DELAY_MS = 1e3;
+/** Default backoff strategy. */
+export declare const DEFAULT_BACKOFF: BackoffStrategy;
+/** Policy applied to handlers without `@Retry` when the plugin sets no `defaults.retry`. */
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Validates retry options and fills defaults.
+ *
+ * @throws ZnightError ZNIGHT011 for invalid values (`where` names the handler in the message).
+ */
+export declare function normalizeRetry(options: RetryOptions | RetryPolicy, where?: string): RetryPolicy;
+/**
+ * Delay before the next attempt once `attempt` (1-based) failed: `delay` for `fixed`,
+ * `delay * 2^(attempt - 1)` capped by `maxDelay` for `exponential`.
+ */
+export declare function computeRetryDelay(policy: RetryPolicy, attempt: number): number;
+/** Messaging metadata of the application. */
+interface MessagingMetadata {
+  readonly consumers: readonly ConsumerDefinition[];
+}
+/**
+ * Options of a consumer: `concurrency` and `deadLetter` are read by the runtime, every other key is a
+ * driver option (e.g. Kafka `groupId`) forwarded to `MessagingDriver.subscribe`.
+ */
+interface ConsumerRuntimeOptions {
+  /** Maximum number of messages handled concurrently by this consumer. Default: plugin `defaults.concurrency`. */
+  readonly concurrency?: number;
+  /** Dead-letter destination, or `false` to disable dead-lettering. Default: the plugin/driver naming. */
+  readonly deadLetter?: string | false;
+  readonly [driverOption: string]: unknown;
+}
+/** One `@Consumer` class. */
+interface ConsumerDefinition {
+  /** Provider token of the consumer class. */
+  readonly token: Token;
+  /** Queue (RabbitMQ, SQS) or topic (Kafka) consumed. */
+  readonly queue: string;
+  /** `@Consumer({ queue, ...options })` without `queue` and `scope`. */
+  readonly options?: ConsumerRuntimeOptions;
+  /** `@OnMessage` methods, in declaration order. */
+  readonly handlers: readonly MessageHandlerDefinition[];
+  /** Name of the `@OnError` method, if any: `(error, message) => void | 'ack'`. */
+  readonly errorHandler?: string;
+}
+/** One `@OnMessage` method. */
+interface MessageHandlerDefinition {
+  /** Method name (logs, hook events). */
+  readonly method: string;
+  /**
+   * `@OnMessage(type)`: the message type handled (exact match, or a pattern where `*` matches any
+   * sequence of characters). Without type, the handler is the consumer's default handler.
+   */
+  readonly type?: string;
+  /** `@Retry` policy, normalized. Default: the plugin's `defaults.retry`. */
+  readonly retry?: RetryPolicy;
+  /**
+   * Calls the handler: extracts and validates the parameters from the message
+   * (`@Message(schema)` → `validateMessage(schema, m.payload)`, `@Headers(name)` →
+   * `messageHeader(m, name)`, `@Ctx()` → `m`).
+   */
+  readonly invoke: (consumer: any, message: InboundMessage) => unknown;
+}
+declare module "@znight/core" {
+  interface ZnightExtensionsMetadata {
+    readonly messaging?: MessagingMetadata;
+  }
+}
+/** An encoded body and its content type. */
+interface EncodedBody {
+  readonly body: Uint8Array | string;
+  readonly contentType: string;
+}
+/**
+ * Converts payloads to bodies and back. The default {@link jsonCodec} handles JSON, text and binary
+ * payloads; provide your own (MessagePack, Avro...) with `MessagingPlugin.configure({ codec })`.
+ */
+interface MessageCodec {
+  /**
+   * Encodes a payload for publication. `contentType` is the one requested by the publisher, if any
+   * (`publish(queue, payload, { contentType })`).
+   */
+  encode(payload: unknown, contentType: string | undefined): EncodedBody;
+  /**
+   * Decodes a received body. Throw a {@link MessageDecodeError} (a `NonRetryableError`) for malformed
+   * bodies: the message is dead-lettered with reason `decode`.
+   */
+  decode(body: Uint8Array | string, contentType: string | undefined): unknown;
+}
+export declare const JSON_CONTENT_TYPE = "application/json";
+export declare const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
+export declare const BINARY_CONTENT_TYPE = "application/octet-stream";
+/** Body as text (UTF-8). */
+export declare function bodyToText(body: Uint8Array | string): string;
+/** Body as bytes (UTF-8 for strings). */
+export declare function bodyToBytes(body: Uint8Array | string): Uint8Array;
+/** Lower-cased media type without parameters (`application/json; charset=utf-8` → `application/json`). */
+export declare function mediaType(contentType: string | undefined): string | undefined;
+/**
+ * The default codec.
+ *
+ * - encode: `Uint8Array` → `application/octet-stream`; a `string` with an explicit text/binary
+ *   `contentType` is sent as is; everything else is JSON (`application/json`), including strings.
+ *   `undefined` is an empty JSON body.
+ * - decode: JSON (`application/json`, `*+json`) is parsed (empty body → `undefined`; malformed →
+ *   `MessageDecodeError`); `text/*` → string; other declared types → `Uint8Array`. Without content
+ *   type, JSON is attempted and the text is returned when it is not valid JSON.
+ */
+export declare const jsonCodec: MessageCodec;
+/** State of a {@link ConsumerRuntime}. */
+type ConsumerState = "created" | "starting" | "running" | "stopping" | "stopped";
+/**
+ * Publishes messages. Inject it in any provider (it is a singleton external provided by
+ * `MessagingPlugin`):
+ *
+ * ```ts
+ * @Injectable()
+ * export class OrderService {
+ *   constructor(private readonly broker: MessageBroker) {}
+ *
+ *   async place(order: Order) {
+ *     await this.broker.publish('orders', order, { type: 'order.placed', key: order.customerId })
+ *   }
+ * }
+ * ```
+ *
+ * `publish()` resolves once the broker confirmed the message (publisher confirms, SQS response,
+ * Kafka acknowledgement). It is usable from `onBootstrap` of the messaging plugin until the
+ * application is disposed (including providers' `onStart` / `onStop`).
+ */
+export declare abstract class MessageBroker {
+  /**
+   * Publishes `payload` to `queue` (a queue for RabbitMQ/SQS, a topic for Kafka). The payload is
+   * encoded by the plugin codec (JSON by default; `Uint8Array` is sent as binary).
+   */
+  abstract publish(queue: string, payload: unknown, options?: PublishOptions): Promise<PublishResult>;
+}
+/**
+ * Copy of the [Standard Schema v1](https://standardschema.dev) interface (MIT). Zod, Valibot, ArkType,
+ * Effect Schema... implement it: `@Message(schema)` accepts any of them without depending on one.
+ *
+ * The upstream declaration uses a namespace; the types are flattened here (`erasableSyntaxOnly`) but
+ * remain structurally identical, so any Standard Schema implementation is assignable.
+ */
+/** A schema implementing the Standard Schema v1 interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": StandardSchemaV1Props<Input, Output>;
+}
+/** The `~standard` property of a {@link StandardSchemaV1}. */
+interface StandardSchemaV1Props<Input = unknown, Output = Input> {
+  /** Version of the Standard Schema specification. */
+  readonly version: 1;
+  /** Library implementing the schema (`zod`, `valibot`...). */
+  readonly vendor: string;
+  /** Validates an unknown value, synchronously or asynchronously. */
+  readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+  /** Inferred types (type-level only). */
+  readonly types?: StandardSchemaV1Types<Input, Output> | undefined;
+}
+/** Result of {@link StandardSchemaV1Props.validate}. */
+type StandardSchemaV1Result<Output> = StandardSchemaV1SuccessResult<Output> | StandardSchemaV1FailureResult;
+/** Successful validation: `value` is the schema output (defaults, transforms applied). */
+interface StandardSchemaV1SuccessResult<Output> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+/** Failed validation. */
+interface StandardSchemaV1FailureResult {
+  readonly issues: readonly StandardSchemaV1Issue[];
+}
+/** One validation issue. */
+interface StandardSchemaV1Issue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | StandardSchemaV1PathSegment)[] | undefined;
+}
+/** A segment of an issue path. */
+interface StandardSchemaV1PathSegment {
+  readonly key: PropertyKey;
+}
+/** Input and output types of a schema (type-level only). */
+interface StandardSchemaV1Types<Input = unknown, Output = Input> {
+  readonly input: Input;
+  readonly output: Output;
+}
+/** Input type of a Standard Schema. */
+type InferSchemaInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+/** Output type of a Standard Schema (what handlers receive). */
+type InferSchemaOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+/** Whether `value` looks like a Standard Schema v1 (has a `~standard.validate` function). */
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/** Options of {@link Consumer} (static). */
+interface ConsumerOptions {
+  /** Queue (RabbitMQ, SQS) or topic (Kafka) to consume. */
+  readonly queue: string;
+  /** Scope of the consumer provider. Default: `singleton`; `request` creates one instance per message. */
+  readonly scope?: Scope;
+  /** Maximum number of messages handled concurrently. Default: plugin `defaults.concurrency` (1). */
+  readonly concurrency?: number;
+  /** Dead-letter queue/topic, or `false` to disable dead-lettering. Default: driver naming (`<queue>.dlq`). */
+  readonly deadLetter?: string | false;
+  /** Driver-specific options (e.g. Kafka `groupId`). */
+  readonly [driverOption: string]: unknown;
+}
+/** Result of an `@OnError` method: `'ack'` acknowledges (swallows) the message, anything else dead-letters it. */
+type ErrorHandlerResult = "ack" | undefined | void;
+/**
+ * Signature of an `@OnError` method. Declared as a method signature so that parameters may be
+ * narrowed (`onError(error: Error, message: InboundMessage<Order>)`).
+ */
+type ErrorHandlerMethod = ErrorHandlerSignature["onError"];
+interface ErrorHandlerSignature {
+  onError(error: unknown, message: InboundMessage): ErrorHandlerResult | Promise<ErrorHandlerResult>;
+}
+/** Marker usable on an `@OnError` method: checks its signature. */
+type ErrorHandlerMarker = <F extends ErrorHandlerMethod>(target: object, propertyKeyOrContext: string | symbol | ClassMethodDecoratorContext<unknown, F>, descriptor?: TypedPropertyDescriptor<F>) => void;
+/**
+ * Declares a message consumer: a provider (singleton by default) whose `@OnMessage` methods handle
+ * the messages of `queue`. Arguments are static.
+ *
+ * ```ts
+ * @Consumer('orders')
+ * export class OrderConsumer {
+ *   constructor(private readonly orders: OrderService) {}
+ *
+ *   @OnMessage('order.created')
+ *   @Retry({ attempts: 5, backoff: 'exponential', delay: 500 })
+ *   async created(@Message(OrderCreated) event: OrderCreated) {
+ *     await this.orders.process(event)
+ *   }
+ * }
+ * ```
+ */
+export declare function Consumer(queue: string): ClassMarker;
+export declare function Consumer(options: ConsumerOptions): ClassMarker;
+/**
+ * Declares a message handler. With `type` (static), it handles the messages of that type (exact
+ * match, or a pattern where `*` matches any sequence: `'order.*'`); without type it is the consumer's
+ * default handler (messages without type, or whose type no other handler matches). A message no
+ * handler matches is dead-lettered (reason `no-handler`).
+ */
+export declare function OnMessage(_type?: string): MethodMarker;
+/**
+ * Retry policy of a handler (static options). `attempts` counts the first delivery:
+ * `{ attempts: 3 }` means one delivery plus two retries. Without `@Retry`, the plugin's
+ * `defaults.retry` applies (3 attempts, exponential from 1 s).
+ */
+export declare function Retry(_options: RetryOptions): MethodMarker;
+/**
+ * Declares the consumer's error handler, called once a message will not be retried anymore (last
+ * attempt failed, `NonRetryableError`, invalid payload, no matching handler). Returning `'ack'`
+ * acknowledges the message; returning anything else (or throwing) dead-letters it.
+ *
+ * ```ts
+ * @OnError()
+ * onError(error: unknown, message: InboundMessage) {
+ *   if (message.type?.startsWith('legacy.')) return 'ack'
+ * }
+ * ```
+ */
+export declare function OnError(): ErrorHandlerMarker;
+/**
+ * Injects the message payload. With a Standard Schema (Zod, Valibot...), the payload is validated and
+ * the parameter receives the schema output; an invalid payload is dead-lettered without retry
+ * (reason `validation`). The schema is a _value_ argument (inline, or an exported binding).
+ */
+export declare function Message(_schema?: StandardSchemaV1): ParameterMarker;
+/** Injects all the message headers, or the value of one header (`string | undefined`). `name` is static. */
+export declare function Headers(_name?: string): ParameterMarker;
+/** Injects the {@link InboundMessage} (id, type, attempt, headers, raw message, abort signal...). */
+export declare function Ctx(): ParameterMarker;
+/**
+ * Thrown by a handler to dead-letter the message immediately, without further attempts (invalid
+ * business data, permanent failure...). Subclass it for domain errors.
+ *
+ * ```ts
+ * if (order.total < 0) throw new NonRetryableError('Negative order total')
+ * ```
+ */
+export declare class NonRetryableError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Whether retrying `error` is pointless: a {@link NonRetryableError} (also recognised across copies of
+ * this package, through a global symbol brand).
+ */
+export declare function isNonRetryable(error: unknown): boolean;
+/** One failed check of a `@Message(schema)` validation. */
+interface MessageValidationIssue {
+  /** Dotted path of the invalid value (`items.0.quantity`), empty for the root. */
+  readonly path: string;
+  readonly message: string;
+}
+/** The payload does not match the `@Message(schema)` of the handler. Never retried. */
+export declare class MessageValidationError extends NonRetryableError {
+  readonly issues: readonly MessageValidationIssue[];
+  constructor(label: string, issues: readonly MessageValidationIssue[]);
+}
+/** The body cannot be decoded (malformed JSON...). Never retried. */
+export declare class MessageDecodeError extends NonRetryableError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/** No `@OnMessage` handler of the consumer matches the message type. Never retried. */
+export declare class NoHandlerError extends NonRetryableError {
+  readonly messageType: string | undefined;
+  constructor(consumer: string, type: string | undefined);
+}
+/** A delivery arrived after its last allowed attempt (e.g. redelivered after a dead-letter failure). */
+export declare class AttemptsExhaustedError extends NonRetryableError {
+  constructor(attempt: number, maxAttempts: number);
+}
+/**
+ * Header names used by Znight on the wire. They are plain message headers (AMQP headers, SQS message
+ * attributes, Kafka record headers), so non-Znight producers and consumers can read and write them.
+ */
+export declare const MessagingHeaders: {
+  /** Znight message id (Kafka and SQS; AMQP uses the `message-id` property). */
+  readonly Id: "x-znight-id";
+  /** Message type used to select the handler (Kafka and SQS; AMQP uses the `type` property). */
+  readonly Type: "x-znight-type";
+  /** Content type of the body (Kafka and SQS; AMQP uses the `content-type` property). */
+  readonly ContentType: "content-type";
+  /** 1-based attempt number carried by republished retries (RabbitMQ, Kafka). */
+  readonly Attempt: "x-znight-attempt";
+  /** Epoch milliseconds before which a Kafka retry record must not be processed. */
+  readonly NotBefore: "x-znight-not-before";
+  /** Body encoding when the transport only carries text (SQS: `base64` for binary payloads). */
+  readonly Encoding: "x-znight-encoding";
+  /** Why the message was dead-lettered (`DeadLetterReason`). */
+  readonly DeadLetterReason: "x-znight-dead-letter-reason";
+  /** Message of the error that dead-lettered the message (truncated). */
+  readonly Error: "x-znight-error";
+  /** Queue the dead-lettered message was consumed from. */
+  readonly OriginalQueue: "x-znight-original-queue";
+  /** Number of attempts made before the message was dead-lettered. */
+  readonly Attempts: "x-znight-attempts";
+  /** Kafka consumer group that dead-lettered the record. */
+  readonly ConsumerGroup: "x-znight-consumer-group";
+};
+/**
+ * Reads a header: exact name first, then a case-insensitive match. Used by the code generated for
+ * `@Headers('name')` parameters.
+ */
+export declare function messageHeader(message: {
+  readonly headers: Readonly<Record<string, string>>;
+}, name: string): string | undefined;
+/** Parses the {@link MessagingHeaders.Attempt} header: a positive integer, `1` when absent or invalid. */
+export declare function attemptFromHeaders(headers: Readonly<Record<string, string>>): number;
+/** Defaults applied to every consumer (each `@Consumer` / `@Retry` may override them). */
+interface MessagingDefaults {
+  /** Retry policy of handlers without `@Retry`. Default: 3 attempts, exponential from 1 s up to 30 s. `false`: no retry. */
+  readonly retry?: RetryOptions | false;
+  /** Concurrency of consumers without `concurrency` option. Default: 1. */
+  readonly concurrency?: number;
+  /**
+   * Dead-letter destination of a queue, or `false` to disable dead-lettering (messages are then
+   * rejected natively or discarded). Default: the driver naming (`orders.dlq`, SQS `orders-dlq`).
+   */
+  readonly deadLetter?: ((queue: string) => string) | false;
+  /**
+   * Pause, in milliseconds, before releasing a message whose settlement failed (dead-letter queue
+   * unavailable...), to avoid hot redelivery loops. Default: 1000.
+   */
+  readonly requeueDelay?: number;
+}
+/** Options of {@link MessagingPlugin.configure}. */
+interface MessagingPluginOptions {
+  /** The broker driver: `rabbitmq()`, `sqs()`, `kafka()` or `memory()` (from the matching subpath). */
+  readonly driver: MessagingDriver;
+  readonly defaults?: MessagingDefaults;
+  /** Payload encoding. Default: {@link jsonCodec}. */
+  readonly codec?: MessageCodec;
+  /** Subscribe the consumers on start. `false` for publish-only processes. Default: `true`. */
+  readonly consume?: boolean;
+}
+/** Runtime status of a consumer. */
+interface ConsumerStatus {
+  /** Display name of the consumer class. */
+  readonly consumer: string;
+  readonly queue: string;
+  readonly state: ConsumerState;
+  readonly concurrency: number;
+  readonly inFlight: number;
+  readonly deadLetterQueue: string | undefined;
+}
+/** The plugin returned by {@link MessagingPlugin.configure}. */
+interface MessagingPluginInstance extends Plugin {
+  readonly name: "messaging";
+  /** The broker (also injectable as `MessageBroker`). */
+  readonly broker: MessageBroker;
+  /** The driver, once the plugin is bootstrapped. */
+  readonly driver: MessagingDriver | undefined;
+  /** Status of every consumer, once the plugin is bootstrapped. */
+  consumers(): ConsumerStatus[];
+}
+/**
+ * Message consumers and publishing.
+ *
+ * ```ts
+ * import { MessagingPlugin } from '@znight/messaging'
+ * import { rabbitmq } from '@znight/messaging/rabbitmq'
+ *
+ * const app = await Application.create({
+ *   metadata: __ZNIGHT_METADATA__,
+ *   plugins: [MessagingPlugin.configure({ driver: rabbitmq({ url: 'amqp://localhost' }) })],
+ * })
+ * ```
+ *
+ * Options may be computed from the container (evaluated in `onBootstrap`):
+ * `MessagingPlugin.configure(c => ({ driver: rabbitmq({ url: c.get(AmqpConfig).url }) }))`.
+ */
+export declare const MessagingPlugin: {
+  configure(options: PluginOptions<MessagingPluginOptions>): MessagingPluginInstance;
+};
+/** Tokens of the externals provided by `MessagingPlugin` (declared in the package manifest). */
+export declare const MessagingTokens: {
+  /** The {@link MessageBroker} singleton. */
+  readonly MessageBroker: TypedToken<MessageBroker>;
+  /** The {@link InboundMessage} of the current delivery (request-scoped). */
+  readonly InboundMessage: TypedToken<InboundMessage>;
+};
+/**
+ * Validates `value` with a Standard Schema (Zod, Valibot, ArkType...) and returns the schema
+ * **output** (defaults and transforms applied). On failure it throws a {@link MessageValidationError},
+ * a `NonRetryableError`: the message is dead-lettered without further attempts.
+ *
+ * Returns synchronously when the schema validates synchronously, a promise otherwise. Called by the
+ * code generated for `@Message(schema)` parameters:
+ *
+ * ```ts
+ * invoke: async (c, m) => c.handle(await validateMessage(OrderCreated, m.payload))
+ * ```
+ *
+ * @param label Describes the value in the error message. Default: `'message payload'`.
+ */
+export declare function validateMessage<S extends StandardSchemaV1>(schema: S, value: unknown, label?: string): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>>;
+export type { BackoffStrategy, ConsumerDefinition, ConsumerOptions, ConsumerRuntimeOptions, ConsumerState, ConsumerStatus, DeadLetterReason, DeadLetterRequest, DeliveryHandler, DriverCapabilities, DriverContext, DriverDelivery, EncodedBody, ErrorHandlerMarker, ErrorHandlerMethod, ErrorHandlerResult, InboundMessage, InferSchemaInput, InferSchemaOutput, MessageCodec, MessageHandlerDefinition, MessagePublishEvent, MessageValidationIssue, MessagingDefaults, MessagingDriver, MessagingMetadata, MessagingPluginInstance, MessagingPluginOptions, OutboundMessage, PublishOptions, PublishResult, RetryOptions, RetryPolicy, RetryRequest, StandardSchemaV1, StandardSchemaV1FailureResult, StandardSchemaV1Issue, StandardSchemaV1PathSegment, StandardSchemaV1Props, StandardSchemaV1Result, StandardSchemaV1SuccessResult, StandardSchemaV1Types, SubscribeOptions, Subscription };
+//# sourceMappingURL=index.d.mts.map