@lakutata/nats 2.3.0 → 3.0.0-beta.0

package/dist/types/components/NATS.d.ts

@@ -0,0 +1,376 @@
+import { Application, Component, ComponentOptionsBuilder } from '@lakutata/core';
+import { type Codec, Subscription, type ObjectStoreStatus } from 'nats';
+import { SubscribeOptions } from '../types/SubscribeOptions.js';
+import { NatsClientOptions } from '../interfaces/NatsClientOptions.js';
+/**
+ * Build the component options of a {@link NATS} component, to register it in the `components` of an application (or a
+ * module) under the name of your choice. The options are validated when the component is created, not here.
+ * @param options The connection options: the servers, the codec, the authentication, the reconnection and the bulk
+ * channel of the large payloads.
+ * @returns The component options (`{class: NATS, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNatsClientOptions, type NATS} from '@lakutata/nats'
+ *
+ * Application
+ *     .run({
+ *         id: 'notifier.app',
+ *         name: 'Notifier',
+ *         components: {
+ *             nats: buildNatsClientOptions({
+ *                 servers: ['nats://10.0.0.1:4222', 'nats://10.0.0.2:4222'],
+ *                 user: 'notifier',
+ *                 pass: 'secret',
+ *                 name: 'notifier',
+ *                 //Never give up reconnecting
+ *                 maxReconnectAttempts: -1
+ *             })
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const nats: NATS = await app.getObject('nats')
+ *         nats.publish('notification.sent', {to: 'ada@example.com'})
+ *     })
+ * ```
+ */
+export declare const buildNatsClientOptions: ComponentOptionsBuilder<NatsClientOptions>;
+/**
+ * The NATS component: a connection to a NATS server (or cluster) to publish messages, subscribe to subjects, send
+ * requests and answer them, and emit and receive the service events. Register it in the `components` of an application
+ * with {@link buildNatsClientOptions} (or `{class: NATS, ...options}`) and get it with `getObject()` or `@Inject`; it is
+ * a singleton. The service entrypoint ({@link natsServiceEntrypoint}) and the service proxies ({@link ServiceProxy})
+ * use it by its component name.
+ *
+ * It connects when it is created: a server which cannot be reached within the `timeout` option fails its creation, and
+ * so the application's start. A lost connection is reestablished in the background (see the `reconnect` and
+ * `maxReconnectAttempts` options); once the reconnection is given up, an `'error'` event is emitted and the calls fail
+ * with the NATS client error `CONNECTION_CLOSED`. When it is destroyed, it drains its connections: the subscriptions stop receiving, the messages
+ * in progress are handled and the outgoing ones flushed before the connections close.
+ *
+ * Every payload is encoded with the codec ({@link messagePackCodec} by default). A payload larger than the server's
+ * `max_payload` (1 MiB by default) cannot be sent as a message: a request or a response of 90% of it or more is relayed
+ * through a JetStream object store when both sides enabled the bulk channel (the `bulk` option, on by default, which
+ * needs JetStream on the server), as a reference the receiving side reads transparently. The published messages and the
+ * events are never relayed: over `max_payload`, publishing them throws.
+ *
+ * It emits an `'error'` event, only when it has listeners, for the failures nobody else can report: a subscription
+ * callback or an event listener which threw, a message which could not be decoded, a subscription error (a permissions
+ * violation).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNatsClientOptions, type NATS} from '@lakutata/nats'
+ *
+ * Application
+ *     .run({
+ *         id: 'pricing.app',
+ *         name: 'Pricing',
+ *         components: {
+ *             nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222', name: 'pricing'})
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const nats: NATS = await app.getObject('nats')
+ *         nats.on('error', (error: Error): void => console.error('NATS message handling failed', error))
+ *         //Answer the requests, shared between the instances of the application: the value returned is the response
+ *         nats.subscribe('price.get', async (input: {sku: string}): Promise<number> => input.sku.length * 10, {queue: 'pricing'})
+ *         //The messages of every region: the subject tells which one
+ *         nats.subscribe('price.changed.*', (price: number, subject: string): void => console.log(subject, price))
+ *         nats.publish('price.changed.eu', 42)
+ *         console.log(await nats.request('price.get', {sku: 'ABC'}, 5000)) //30
+ *         //The service events of this application, received by the applications listening to them
+ *         nats.emitServiceEvent('priceChanged', 'ABC', 30)
+ *         nats.onServiceEvent('stock.service', 'stockChanged', (sku: string, quantity: number): void => console.log(sku, quantity))
+ *     })
+ * ```
+ */
+export declare class NATS extends Component {
+    #private;
+    /**
+     * The application the component belongs to; its id names the service events it emits.
+     */
+    protected readonly app: Application;
+    /**
+     * The NATS server, or the servers of a cluster: `host:port` or a URL (`nats://user:pass@host:4222`).
+     */
+    protected readonly servers: string | string[];
+    /**
+     * The codec encoding and decoding every payload.
+     * @default messagePackCodec()
+     */
+    protected readonly codec: Codec<unknown>;
+    /**
+     * The time to wait for the connection to a server to be established, in milliseconds.
+     * @default 20000
+     */
+    protected readonly timeout?: number;
+    /**
+     * The token of the server's token authentication.
+     */
+    protected readonly token?: string;
+    /**
+     * The user name of the server's user/password authentication.
+     */
+    protected readonly user?: string;
+    /**
+     * The password of the server's user/password authentication.
+     */
+    protected readonly pass?: string;
+    /**
+     * Whether the client prints the protocol messages it sends and receives.
+     * @default false
+     */
+    protected readonly debug?: boolean;
+    /**
+     * The number of pings left unanswered after which the connection is considered stale and the client reconnects.
+     * @default 2
+     */
+    protected readonly maxPingOut?: number;
+    /**
+     * The number of reconnection attempts to each server before giving up, `-1` never giving up.
+     * @default 10
+     */
+    protected readonly maxReconnectAttempts?: number;
+    /**
+     * The client name shown by the server's monitoring; it also names the default bucket of the bulk channel.
+     */
+    protected readonly name?: string;
+    /**
+     * Whether the messages this client publishes are never delivered to its own subscriptions.
+     * @default false
+     */
+    protected readonly noEcho?: boolean;
+    /**
+     * Whether the servers are tried in the order given, instead of a random order.
+     * @default false
+     */
+    protected readonly noRandomize?: boolean;
+    /**
+     * The interval between the pings the client sends to check the connection, in milliseconds.
+     * @default 120000
+     */
+    protected readonly pingInterval?: number;
+    /**
+     * Whether the client reconnects after losing its connection.
+     * @default true
+     */
+    protected readonly reconnect?: boolean;
+    /**
+     * Whether the bulk channel, relaying the large payloads through a JetStream object store over a second connection,
+     * is prepared when the component starts.
+     * @default true
+     */
+    protected readonly bulk?: boolean;
+    /**
+     * The object store bucket of the bulk channel.
+     * @default `lkt-bulk-{name}`, `lkt-bulk-default` without `name`
+     */
+    protected readonly bulkBucket?: string;
+    /**
+     * The time to live of the objects of the bulk channel, in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    protected readonly bulkTTL?: number;
+    /**
+     * The number of replicas of the bulk bucket, sent to the server only when set.
+     * @default none: the server's default (one replica)
+     */
+    protected readonly bulkReplicas?: number;
+    /**
+     * The subscriptions of the service event listeners, by event subject, then by listener.
+     */
+    protected readonly serviceEventSubscriptionMap: Map<string, Map<(...args: any[]) => void, Subscription>>;
+    /**
+     * Connect to the server, then prepare the bulk channel when it is enabled (a failure of the bulk channel only
+     * disables it, with a warning).
+     * @throws {Error} The NATS client error when no server can be reached.
+     */
+    protected init(): Promise<void>;
+    /**
+     * Drain the connections: stop receiving, finish the messages in progress and flush the outgoing ones, then close.
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Graceful shutdown: drain stops receiving, finishes the messages in progress and flushes the outgoing ones before closing,
+     * so the requests in progress survive a rolling update; a failed drain closes the connection
+     * @param conn
+     * @private
+     */
+    private drainConnection;
+    /**
+     * Publish a message: every subscription to the subject receives it (one per queue group). It is not answered, and is
+     * lost when nobody listens.
+     * @param subject The subject, without wildcards (`order.created`).
+     * @param payload The data, encoded with the codec.
+     * @throws {Error} The NATS client error `MAX_PAYLOAD_EXCEEDED` when the encoded payload is larger than the server's
+     * `max_payload` (the published messages are never relayed through the bulk channel), `CONNECTION_CLOSED` once the
+     * connection is closed, `BAD_SUBJECT` for an empty subject; the codec's error when the payload cannot be encoded.
+     */
+    publish(subject: string, payload: any): void;
+    /**
+     * Send a request and wait for its first response. A subscription answers it with its callback's return value (see
+     * {@link NATS.subscribe}); when nobody listens on the subject, it fails at once.
+     *
+     * A payload of 90% of the server's `max_payload` or more is relayed through the bulk channel when the subject's
+     * responders support it: learned from a previous response on the subject, else asked once by a probe of the subject
+     * (answered by the responders of this version with the bulk channel on; the older ones do not answer it). Otherwise it
+     * is sent as a message, and fails over `max_payload`. A large response is relayed the same way and read
+     * transparently.
+     * @param subject The subject of the responders.
+     * @param payload The data, encoded with the codec.
+     * @param timeout The time to wait for the response, in milliseconds; `0` or no value waits 600000 (10 minutes).
+     * @returns The response, decoded.
+     * @throws {NatsNoRespondersAvailableException} When nobody listens on the subject.
+     * @throws {NatsRequestTimeoutException} When no response arrives in time (the request may have been processed).
+     * @throws {NatsBulkException} When a large request cannot be stored, or a large response cannot be read.
+     * @throws {Error} The NATS client error `MAX_PAYLOAD_EXCEEDED` when a payload too large is not relayed,
+     * `CONNECTION_CLOSED` once the connection is closed; the codec's error when the payload or the response cannot be
+     * encoded or decoded.
+     */
+    request(subject: string, payload?: any, timeout?: number): Promise<any>;
+    /**
+     * Subscribe to a subject and handle its messages with a callback. The payloads are decoded (and read from the bulk
+     * channel when they are references) before the callback runs. A request (a message with a reply subject, sent by
+     * {@link NATS.request}) is answered with the callback's return value, awaited and encoded, relayed through the bulk
+     * channel when it is large and the requester supports it; the return value of a published message is ignored.
+     *
+     * When the callback throws (or a payload cannot be decoded, or a response cannot be sent), the error is emitted as an
+     * `'error'` event, and a request is answered with `subscribeOptions.errorResponse`, or not answered at all (the
+     * requester waits for its timeout).
+     * @param subject The subject, possibly with wildcards: `*` matches one token (`order.*`), `>` the remaining tokens
+     * (`order.>`).
+     * @param callback The handler: receives the decoded payload and the subject the message arrived on (useful with the
+     * wildcards), and returns the response to a request.
+     * @param subscribeOptions The queue group, the number of messages, the sequential handling and the error response.
+     * @returns The NATS subscription: `unsubscribe()` stops it at once, `drain()` once the messages received are handled.
+     * @throws {Error} The NATS client error `CONNECTION_CLOSED` once the connection is closed, `BAD_SUBJECT` for an invalid
+     * subject.
+     */
+    subscribe(subject: string, callback: (data: any, subject: string) => any | Promise<any>, subscribeOptions?: SubscribeOptions): Subscription;
+    /**
+     * Subscribe to a subject, as {@link NATS.subscribe}; the subscriptions of the events do not answer the capability
+     * probes of the requesters (nobody requests them).
+     * @param subject The subject, wildcards allowed.
+     * @param callback Called with each message's data and subject; its result answers a request.
+     * @param subscribeOptions The queue group, the number of messages, the iteration and the error responses.
+     * @param answerProbes Whether the subscription answers the capability probes of the large requests to its subject.
+     * @returns The NATS subscription.
+     * @protected
+     */
+    protected subscribeTo(subject: string, callback: (data: any, subject: string) => any | Promise<any>, subscribeOptions: SubscribeOptions | undefined, answerProbes: boolean): Subscription;
+    /**
+     * Emit an `'error'` event when the component has listeners, and do nothing otherwise (an `'error'` event
+     * without listener would throw).
+     * @param error The error to report.
+     */
+    protected emitError(error: any): void;
+    /**
+     * Whether the bulk channel is ready: enabled by the `bulk` option and started (its connection and object store
+     * prepared).
+     */
+    get bulkEnabled(): boolean;
+    /**
+     * The encoded size from which a payload is relayed through the bulk channel, in bytes: 90% of the current server's
+     * `max_payload` (1 MiB when unknown).
+     */
+    get bulkThreshold(): number;
+    /**
+     * Whether the current server supports the message headers, which the bulk channel needs to mark its references.
+     */
+    get headersSupported(): boolean;
+    /**
+     * Store bytes in the bulk channel's object store, for its time to live (`bulkTTL`).
+     * @param bytes The bytes to store.
+     * @returns The id of the object (a random UUID), to read it with {@link NATS.getBulk}.
+     * @throws {NatsBulkException} When the bulk channel is not enabled, or the object store rejects the write.
+     */
+    putBulk(bytes: Uint8Array): Promise<string>;
+    /**
+     * Read an object from the bulk channel's object store. The object is not deleted.
+     * @param objId The id returned by {@link NATS.putBulk}.
+     * @returns The bytes stored.
+     * @throws {NatsBulkException} When the bulk channel is not enabled, the object store rejects the read, or the object
+     * does not exist (never stored, expired, or deleted).
+     */
+    getBulk(objId: string): Promise<Uint8Array>;
+    /**
+     * Delete an object from the bulk channel's object store; nothing happens when the bulk channel is not enabled.
+     * @param objId The id returned by {@link NATS.putBulk}.
+     * @throws {Error} The object store's error when the deletion fails.
+     */
+    deleteBulk(objId: string): Promise<void>;
+    /**
+     * Read the status of the bulk channel's object store: its bucket, time to live, replicas, storage and size.
+     * @returns The status, or `undefined` when the bulk channel is not enabled.
+     */
+    bulkStatus(): Promise<ObjectStoreStatus | undefined>;
+    /**
+     * Ask the responders of a subject whether they support the bulk references, before the first large request to it:
+     * the responders supporting them answer on the probe subject, the others (an older version, the bulk channel off)
+     * have no subscription there (no responders, or no answer in time). The answer is kept for the subject.
+     * @param subject The subject of the request.
+     * @returns Whether its responders support the bulk references.
+     * @private
+     */
+    private probeBulk;
+    /**
+     * Pack a payload to send: encoded, then stored in the object store and sent as a small reference when it is large and the peer supports it
+     * @param payload
+     * @param peerSupportsBulk whether the peer supports the references (the payload itself is sent otherwise)
+     * @private
+     */
+    private packPayload;
+    /**
+     * Unpack received bytes: a reference is read from the object store then decoded (deleted once read, its time to live covers a failure)
+     * @param bytes
+     * @param isRef
+     * @private
+     */
+    private unpackPayload;
+    /**
+     * Emit a service event of this application: the listeners registered for it with the application's id (with
+     * {@link NATS.onServiceEvent} or `ServiceProxy.on()`) receive the arguments. The event is published at most once: the
+     * applications not listening, or disconnected, miss it.
+     * @param eventName The event name.
+     * @param args The arguments given to the listeners, encoded with the codec (as one array).
+     * @returns The component, for chaining.
+     * @throws {Error} The NATS client error `MAX_PAYLOAD_EXCEEDED` when the encoded arguments are larger than the server's
+     * `max_payload` (the events are never relayed through the bulk channel), `CONNECTION_CLOSED` once the connection is
+     * closed; the codec's error when the arguments cannot be encoded.
+     */
+    emitServiceEvent(eventName: string, ...args: any[]): this;
+    /**
+     * Listen to a service event of an application. A listener registered again for the same event (by this method or
+     * {@link NATS.onceServiceEvent}) is ignored. A listener which throws is reported as an `'error'` event; the rejection of
+     * an asynchronous listener is not caught.
+     * @param serviceId The id of the application emitting the event (its `id` option).
+     * @param eventName The event name.
+     * @param listener The listener, receiving the event's arguments.
+     * @param onlySingleClientReceived Whether each event goes to one of the listeners registered with `true` for it, across
+     * all the applications (a queue group), instead of to each of them; the listeners registered with `false` still receive
+     * every event.
+     * @returns The component, for chaining.
+     * @throws {Error} The NATS client error `CONNECTION_CLOSED` once the connection is closed.
+     */
+    onServiceEvent(serviceId: string, eventName: string, listener: (...args: any[]) => void, onlySingleClientReceived?: boolean): this;
+    /**
+     * Listen to the next occurrence of a service event of an application only: the listener is removed once called. A
+     * listener already registered for the event is ignored.
+     * @param serviceId The id of the application emitting the event (its `id` option).
+     * @param eventName The event name.
+     * @param listener The listener, receiving the event's arguments.
+     * @returns The component, for chaining.
+     * @throws {Error} The NATS client error `CONNECTION_CLOSED` once the connection is closed.
+     */
+    onceServiceEvent(serviceId: string, eventName: string, listener: (...args: any[]) => void): this;
+    /**
+     * Stop listening to a service event of an application.
+     * @param serviceId The id of the application emitting the event.
+     * @param eventName The event name.
+     * @param listener The listener to remove; without it, every listener registered on this component for the event is
+     * removed (those of the service proxies using the component included).
+     * @returns The component, for chaining.
+     */
+    offServiceEvent(serviceId: string, eventName: string, listener?: (...args: any[]) => void): this;
+}

package/dist/types/entrypoints/NatsServiceEntrypoint.d.ts

@@ -0,0 +1,102 @@
+import { ServiceContext, type EntrypointAdapter, type MiddlewareDefinition } from '@lakutata/entrypoint';
+/**
+ * The options of {@link natsServiceEntrypoint}.
+ */
+export type NatsServiceEntrypointOptions = {
+    /**
+     * The adapter name, to tell apart several service adapters of one entrypoint.
+     */
+    name?: string;
+    /**
+     * The subject the requests are received on: the `serviceId` the service proxies use. The events of
+     * `Entrypoint.broadcast()` are published under it; the ones of `NATS.emitServiceEvent()` under the application id.
+     * @default the application id (its `id` option)
+     */
+    subject?: string;
+    /**
+     * The queue group sharing the requests between the instances of the service: each request is handled by one of
+     * them.
+     * @default `{subject}.serviceQueue`
+     */
+    queue?: string;
+    /**
+     * The middlewares of this adapter's actions, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+};
+/**
+ * Create a service adapter of an entrypoint served over NATS: the requests sent to the application's id (by the
+ * {@link ServiceProxy} components of the other applications, or any NATS client) are dispatched to the controllers'
+ * service actions, through the {@link NATS} component registered under `natsComponentName`.
+ *
+ * A request's payload is the message matched against the `@ServiceAction` patterns: the action's pattern and its input
+ * in one object. It is answered with a service response `{success, error, payload}` (see `ServiceResponseCodec`):
+ * `payload` is the action's result, or `error` the properties of the error when the action failed (no matching action,
+ * validation, access denied…). A request whose payload cannot be decoded, or whose response cannot be sent, is answered
+ * with such an error too, so the requester does not wait for its timeout. A published message (without reply subject)
+ * runs the action without answer.
+ *
+ * The instances of the service share the requests through a queue group: each request is handled by one of them. Large
+ * requests and responses go through the NATS component's bulk channel. `Entrypoint.broadcast()` publishes its events
+ * under the entrypoint's subject, to the proxies of the service (it counts them 0: NATS does not tell how many receive
+ * them); `Entrypoint.notify()` does not reach it (NATS has no client ids). When the entrypoint stops, the subscription is drained: no request is received any more
+ * (the callers get no responder and retry), the requests in progress are answered.
+ * @param natsComponentName The name of the NATS component, as registered in the components; the entrypoint fails to
+ * start when it is not registered.
+ * @param options The subject, the queue group, the adapter name and its middlewares.
+ * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application, DTO} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {buildNatsClientOptions, natsServiceEntrypoint} from '@lakutata/nats'
+ *
+ * class GetOrderDTO extends DTO {
+ *     @Expect(DTO.Number().integer().required())
+ *     public id!: number
+ * }
+ *
+ * class OrderController extends Controller {
+ *     //Invoked by orderService.invoke({cmd: 'order.get', id: 1}) in the other applications
+ *     @ServiceAction({cmd: 'order.get'}, GetOrderDTO)
+ *     public async get(input: GetOrderDTO): Promise<{ id: number, total: number }> {
+ *         return {id: input.id, total: 42}
+ *     }
+ * }
+ *
+ * Application.run({
+ *     //The subject of the requests: the serviceId of the proxies
+ *     id: 'order.service',
+ *     name: 'OrderService',
+ *     components: {
+ *         nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'}),
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [OrderController],
+ *             service: natsServiceEntrypoint('nats')
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * })
+ * ```
+ */
+export declare function natsServiceEntrypoint(natsComponentName: string, options?: NatsServiceEntrypointOptions): EntrypointAdapter<ServiceContext>;
+/**
+ * The former name of {@link natsServiceEntrypoint}, kept for the applications written for 2.x; it behaves the same.
+ * @param natsComponentName The name of the NATS component, as registered in the components.
+ * @param options The subject, the queue group, the adapter name and its middlewares.
+ * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {setupNatsServiceEntrypoint} from '@lakutata/nats'
+ *
+ * class OrderController extends Controller {
+ * }
+ *
+ * //The same as natsServiceEntrypoint('nats')
+ * export const entrypoint = buildEntrypoints({controllers: [OrderController], service: setupNatsServiceEntrypoint('nats')})
+ * ```
+ */
+export declare const setupNatsServiceEntrypoint: (natsComponentName: string, options?: NatsServiceEntrypointOptions) => EntrypointAdapter<ServiceContext>;

package/dist/types/exceptions/NatsBadRequestException.d.ts

@@ -0,0 +1,11 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by `NATS.request()` (and so `ServiceProxy.invoke()`) when the request fails with an error of the NATS client
+ * whose code is `400` (a bad request). The client reports such codes for some JetStream operations, not for the core
+ * requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_BAD_REQUEST`, its `statusCode` 400.
+ */
+export declare class NatsBadRequestException extends Exception {
+    errno: string | number;
+    message: string;
+    statusCode: number;
+}

package/dist/types/exceptions/NatsBulkException.d.ts

@@ -0,0 +1,19 @@
+import { Exception } from '@lakutata/core';
+/**
+ * A failure of the bulk channel, which relays the large payloads through a JetStream object store; its message tells
+ * the cause:
+ * - `bulk channel is not enabled`: `putBulk()` or `getBulk()` called, or a reference received, while the channel is
+ *   disabled (the `bulk` option is `false`, or the channel failed to start);
+ * - `bulk put failed: …` / `bulk get failed: …`: the object store rejected the write or the read;
+ * - `bulk object not found: <id>`: the referenced object is gone (its time to live passed) or is in another bucket
+ *   (the peers do not share their `bulkBucket`).
+ *
+ * `NATS.request()` and `ServiceProxy.invoke()` throw it when the large request cannot be stored or the large response
+ * cannot be read; `ServiceProxy.invoke()` never retries it, since the service may have processed the request. On the
+ * service side, the failure is answered to the requester, which receives a `ServiceInvokeException` whose `errno` is
+ * `E_NATS_BULK`. Its `errno` is `E_NATS_BULK`, its `statusCode` 502.
+ */
+export declare class NatsBulkException extends Exception {
+    errno: string | number;
+    statusCode: number;
+}

package/dist/types/exceptions/NatsForbiddenException.d.ts

@@ -0,0 +1,11 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by `NATS.request()` (and so `ServiceProxy.invoke()`) when the request fails with an error of the NATS client
+ * whose code is `403` (a forbidden request). The client reports such codes for some JetStream operations, not for the
+ * core requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_FORBIDDEN`, its `statusCode` 403.
+ */
+export declare class NatsForbiddenException extends Exception {
+    errno: string | number;
+    message: string;
+    statusCode: number;
+}

package/dist/types/exceptions/NatsInternalServerException.d.ts

@@ -0,0 +1,12 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by `NATS.request()` (and so `ServiceProxy.invoke()`) when the request fails with an error of the NATS client
+ * whose code is `500` (an internal error of the server). The client reports such codes for some JetStream operations,
+ * not for the core requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_INTERNAL_SERVER`, its
+ * `statusCode` 500.
+ */
+export declare class NatsInternalServerException extends Exception {
+    errno: string | number;
+    message: string;
+    statusCode: number;
+}

package/dist/types/exceptions/NatsNoRespondersAvailableException.d.ts

@@ -0,0 +1,12 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by `NATS.request()` when no subscription receives the request: nobody listens on the subject (the service is
+ * not running, or is stopping). It is thrown at once, without waiting for the timeout, and the request was not
+ * processed: `ServiceProxy.invoke()` retries it (`maxRetries` times) before throwing it. Its `errno` is
+ * `E_NATS_NO_RESPONDERS_AVAILABLE`, its `statusCode` 503.
+ */
+export declare class NatsNoRespondersAvailableException extends Exception {
+    errno: string | number;
+    message: string;
+    statusCode: number;
+}

package/dist/types/exceptions/NatsNotFoundException.d.ts

@@ -0,0 +1,11 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by `NATS.request()` (and so `ServiceProxy.invoke()`) when the request fails with an error of the NATS client
+ * whose code is `404` (a subject not found). The client reports such codes for some JetStream operations, not for the
+ * core requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_NOT_FOUND`, its `statusCode` 404.
+ */
+export declare class NatsNotFoundException extends Exception {
+    errno: string | number;
+    message: string;
+    statusCode: number;
+}

package/dist/types/exceptions/NatsRequestTimeoutException.d.ts

@@ -0,0 +1,11 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by `NATS.request()` (and so `ServiceProxy.invoke()`) when no response arrives within the request's timeout.
+ * The request may have been received and processed, its response lost or late: it is never retried. Its `errno` is
+ * `E_NATS_REQUEST_TIMEOUT`, its `statusCode` 408.
+ */
+export declare class NatsRequestTimeoutException extends Exception {
+    errno: string | number;
+    message: string;
+    statusCode: number;
+}

package/dist/types/exports/Nats.d.ts

@@ -0,0 +1,18 @@
+export { natsServiceEntrypoint, setupNatsServiceEntrypoint, type NatsServiceEntrypointOptions } from '../entrypoints/NatsServiceEntrypoint.js';
+export { ServiceProxy, buildServiceProxy, type BuildServiceProxyOptions } from '../providers/ServiceProxy.js';
+export { RetentionPolicy } from 'nats';
+export { NATS, buildNatsClientOptions } from '../components/NATS.js';
+export { jsonCodec } from '../codecs/JSONCodec.js';
+export { messagePackCodec } from '../codecs/MessagePackCodec.js';
+export { StringCodec } from 'nats';
+export type { SubscribeOptions } from '../types/SubscribeOptions.js';
+export type { Subscription, Codec } from 'nats';
+export type { NatsClientOptions } from '../interfaces/NatsClientOptions.js';
+export { NatsBadRequestException } from '../exceptions/NatsBadRequestException.js';
+export { NatsForbiddenException } from '../exceptions/NatsForbiddenException.js';
+export { NatsInternalServerException } from '../exceptions/NatsInternalServerException.js';
+export { NatsNoRespondersAvailableException } from '../exceptions/NatsNoRespondersAvailableException.js';
+export { NatsNotFoundException } from '../exceptions/NatsNotFoundException.js';
+export { NatsRequestTimeoutException } from '../exceptions/NatsRequestTimeoutException.js';
+export { ServiceInvokeException } from '@lakutata/entrypoint';
+export { NatsBulkException } from '../exceptions/NatsBulkException.js';