@lakutata/nats 2.2.2 → 3.0.0-beta.0

package/dist/{lib → cjs/lib}/ServiceEventCodec.js

@@ -15,20 +15,30 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceEventCodec = void 0;
-const helper_1 = require("lakutata/helper");
+const utils_1 = require("@lakutata/utils");
 const querystring = __importStar(require("node:querystring"));
 class ServiceEventCodec {
     static hashEventName(serviceId, eventName) {
-        return (0, helper_1.MD5)(querystring.encode({
+        return (0, utils_1.md5)(querystring.encode({
             serviceId: serviceId,
             eventName: eventName
         })).toString('hex');

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/providers/ServiceProxy.d.ts

@@ -0,0 +1,210 @@
+import { ActionPattern, Application, Provider, type ProviderOptionsBuilder } from '@lakutata/core';
+import { NATS } from '../components/NATS.js';
+/**
+ * The options of a {@link ServiceProxy}, given to {@link buildServiceProxy}.
+ */
+export type BuildServiceProxyOptions = {
+    /**
+     * The name of the {@link NATS} component the proxy sends its requests through, as registered in the components.
+     */
+    readonly natsComponentName: string;
+    /**
+     * The id of the remote service: the subject its {@link natsServiceEntrypoint} listens on, which is its application
+     * id (its `id` option) unless the entrypoint's `subject` option changes it. Its events are listened to under this id
+     * too, which only matches the application id.
+     */
+    readonly serviceId: string;
+    /**
+     * The number of times a request nobody received (no responder: the service is not running or is restarting) is
+     * sent again before {@link NatsNoRespondersAvailableException} is thrown. The timeouts and the failures of the
+     * service are never retried, since the request may have been processed.
+     * @default 3
+     */
+    readonly maxRetries?: number;
+    /**
+     * The delay before each retry, in milliseconds.
+     * @default 100
+     */
+    readonly retryDelay?: number;
+};
+/**
+ * Build the provider options of a {@link ServiceProxy}, to register it in the `providers` of an application under the
+ * name of your choice (as in 2.x); declare one per remote service. The options are validated when the proxy is created,
+ * not here.
+ * @param options The NATS component to use, the id of the remote service, and the retries of the requests nobody
+ * received.
+ * @returns The provider options (`{class: ServiceProxy, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNatsClientOptions, buildServiceProxy, type ServiceProxy} from '@lakutata/nats'
+ *
+ * Application
+ *     .run({
+ *         id: 'shop.app',
+ *         name: 'Shop',
+ *         components: {
+ *             nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'})
+ *         },
+ *         providers: {
+ *             //The actions and the events of the application whose id is "order.service"
+ *             orderService: buildServiceProxy({natsComponentName: 'nats', serviceId: 'order.service', maxRetries: 5})
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const orderService: ServiceProxy = await app.getObject('orderService')
+ *         console.log(await orderService.invoke({cmd: 'order.get', id: 1}))
+ *     })
+ * ```
+ */
+export declare const buildServiceProxy: ProviderOptionsBuilder<BuildServiceProxyOptions>;
+/**
+ * The proxy of a remote service served by {@link natsServiceEntrypoint}: it invokes the service's actions and listens to
+ * its events, over a {@link NATS} component. Register it in the `providers` of an application with
+ * {@link buildServiceProxy} (as in 2.x), one per remote service, and get it with `getObject()` or `@Inject`; it is a
+ * singleton provider, shared by the scopes. It resolves its NATS component when it is created (which fails when that
+ * component is not registered).
+ *
+ * An invocation is a NATS request to the service id, answered by one instance of the service (its queue group): the
+ * action's result is returned, the action's failure thrown as a `ServiceInvokeException` carrying the remote error's
+ * properties (`errno`, `statusCode`, `message`…). A request nobody received is sent again (`maxRetries`, `retryDelay`);
+ * a timeout is never retried, since the action may have run. Large requests and responses go through the bulk channel
+ * of the NATS component (see {@link NATS}).
+ *
+ * The event listeners registered through the proxy are removed when it is destroyed.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {buildNatsClientOptions, buildServiceProxy, ServiceInvokeException, type ServiceProxy} from '@lakutata/nats'
+ *
+ * type Order = {id: number, total: number}
+ *
+ * class Billing extends Component {
+ *     @Inject('orderService')
+ *     protected readonly orderService: ServiceProxy
+ *
+ *     public async total(id: number): Promise<number | undefined> {
+ *         try {
+ *             //The action of the order service matching {cmd: 'order.get'}, its input {id}; 30 seconds at most
+ *             const order: Order = await this.orderService.invoke({cmd: 'order.get', id: id}, 30000)
+ *             return order.total
+ *         } catch (error) {
+ *             //The action failed: the remote error's errno and statusCode are copied
+ *             if (error instanceof ServiceInvokeException && error.statusCode === 404) return undefined
+ *             //NatsNoRespondersAvailableException (not running, after the retries), NatsRequestTimeoutException…
+ *             throw error
+ *         }
+ *     }
+ * }
+ *
+ * Application
+ *     .run({
+ *         id: 'billing.app',
+ *         name: 'Billing',
+ *         components: {
+ *             nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'}),
+ *             billing: {class: Billing}
+ *         },
+ *         providers: {
+ *             orderService: buildServiceProxy({natsComponentName: 'nats', serviceId: 'order.service'})
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const orderService: ServiceProxy = await app.getObject('orderService')
+ *         //The events emitted by the order service with NATS.emitServiceEvent('orderPaid', id, total)
+ *         orderService.on('orderPaid', (id: number, total: number): void => console.log(`Order ${id} paid: ${total}`))
+ *         const billing: Billing = await app.getObject('billing')
+ *         console.log(await billing.total(1))
+ *     })
+ * ```
+ */
+export declare class ServiceProxy extends Provider {
+    /**
+     * The application the proxy belongs to, to resolve its NATS component.
+     */
+    protected readonly app: Application;
+    /**
+     * The name of the NATS component the proxy uses.
+     */
+    protected readonly natsComponentName: string;
+    /**
+     * The id of the remote service: the subject of its requests and the id of its events.
+     */
+    protected readonly serviceId: string;
+    /**
+     * The number of times a request nobody received is sent again; the timeouts and the failures of the service are
+     * never retried.
+     * @default 3
+     */
+    protected readonly maxRetries: number;
+    /**
+     * The delay before each retry, in milliseconds.
+     * @default 100
+     */
+    protected readonly retryDelay: number;
+    /**
+     * The NATS component, resolved when the proxy is created.
+     */
+    protected nats: NATS;
+    /**
+     * The event listeners registered through this proxy, by event name, removed when it is destroyed.
+     */
+    protected readonly eventListeners: Map<string, Map<(...args: any[]) => void, (...args: any[]) => unknown>>;
+    /**
+     * Resolve the NATS component.
+     * @throws {Error} When no component is registered under `natsComponentName`.
+     */
+    protected init(): Promise<void>;
+    /**
+     * Remove the event listeners registered through this proxy.
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Record an event listener registered through this proxy, to remove it when the proxy is destroyed.
+     * @param eventName The event name.
+     * @param listener The listener.
+     */
+    protected keepListener(eventName: string, listener: (...args: any[]) => void): ((...args: any[]) => unknown) | undefined;
+    /**
+     * Invoke an action of the remote service and return its result.
+     * @param input The message: the action's pattern (as declared by its `@ServiceAction`) and its input, in one object
+     * (`{cmd: 'order.get', id: 1}`). It is encoded with the NATS component's codec (plain JSON data).
+     * @param timeout The time to wait for the response of each attempt, in milliseconds. A missing service fails at once
+     * (no responder), so it only bounds a request received and processed too slowly; `0` waits 600000 (10 minutes).
+     * @returns The action's result (the data of a `StatusResult`).
+     * @throws {ServiceInvokeException} When the action fails, or no action matches: its message is the remote error's, its
+     * `errno`, `statusCode` and other properties are copied from it, its `service` is the service id.
+     * @throws {NatsNoRespondersAvailableException} When nobody received the request, after `maxRetries` retries.
+     * @throws {NatsRequestTimeoutException} When no response arrives in time (never retried: the action may have run).
+     * @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 request too large is not relayed (see
+     * {@link NATS.request}), `CONNECTION_CLOSED` once the connection is closed.
+     */
+    invoke<T extends Record<string, any>>(input: ActionPattern<T>, timeout?: number): Promise<any>;
+    /**
+     * Listen to an event of the remote service, emitted by its NATS component with `emitServiceEvent()`. A listener
+     * registered again for the same event on the same NATS component is ignored.
+     * @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, such as the instances of one service), instead of to each of them.
+     * @returns The proxy, for chaining.
+     */
+    on(eventName: string, listener: (...args: any[]) => void, onlySingleClientReceived?: boolean): this;
+    /**
+     * Listen to the next occurrence of an event of the remote service only.
+     * @param eventName The event name.
+     * @param listener The listener, receiving the event's arguments.
+     * @returns The proxy, for chaining.
+     */
+    once(eventName: string, listener: (...args: any[]) => void): this;
+    /**
+     * Stop listening to an event of the remote service.
+     * @param eventName The event name.
+     * @param listener The listener to remove; without it, every listener of the event added through this proxy (the
+     * listeners added through the other proxies or `NATS.onServiceEvent()` are kept).
+     * @returns The proxy, for chaining.
+     */
+    off(eventName: string, listener?: (...args: any[]) => void): this;
+}

package/dist/cjs/providers/ServiceProxy.js

@@ -0,0 +1,274 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceProxy = exports.buildServiceProxy = void 0;
+const core_1 = require("@lakutata/core");
+const di_1 = require("@lakutata/core/decorator/di");
+const utils_1 = require("@lakutata/utils");
+const channel_1 = require("@lakutata/entrypoint/channel");
+const NatsNoRespondersAvailableException_js_1 = require("../exceptions/NatsNoRespondersAvailableException.js");
+/**
+ * Build the provider options of a {@link ServiceProxy}, to register it in the `providers` of an application under the
+ * name of your choice (as in 2.x); declare one per remote service. The options are validated when the proxy is created,
+ * not here.
+ * @param options The NATS component to use, the id of the remote service, and the retries of the requests nobody
+ * received.
+ * @returns The provider options (`{class: ServiceProxy, ...options}`).
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNatsClientOptions, buildServiceProxy, type ServiceProxy} from '@lakutata/nats'
+ *
+ * Application
+ *     .run({
+ *         id: 'shop.app',
+ *         name: 'Shop',
+ *         components: {
+ *             nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'})
+ *         },
+ *         providers: {
+ *             //The actions and the events of the application whose id is "order.service"
+ *             orderService: buildServiceProxy({natsComponentName: 'nats', serviceId: 'order.service', maxRetries: 5})
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const orderService: ServiceProxy = await app.getObject('orderService')
+ *         console.log(await orderService.invoke({cmd: 'order.get', id: 1}))
+ *     })
+ * ```
+ */
+const buildServiceProxy = (options) => {
+    return {
+        class: ServiceProxy,
+        natsComponentName: options.natsComponentName,
+        serviceId: options.serviceId,
+        maxRetries: options.maxRetries,
+        retryDelay: options.retryDelay
+    };
+};
+exports.buildServiceProxy = buildServiceProxy;
+/**
+ * The proxy of a remote service served by {@link natsServiceEntrypoint}: it invokes the service's actions and listens to
+ * its events, over a {@link NATS} component. Register it in the `providers` of an application with
+ * {@link buildServiceProxy} (as in 2.x), one per remote service, and get it with `getObject()` or `@Inject`; it is a
+ * singleton provider, shared by the scopes. It resolves its NATS component when it is created (which fails when that
+ * component is not registered).
+ *
+ * An invocation is a NATS request to the service id, answered by one instance of the service (its queue group): the
+ * action's result is returned, the action's failure thrown as a `ServiceInvokeException` carrying the remote error's
+ * properties (`errno`, `statusCode`, `message`…). A request nobody received is sent again (`maxRetries`, `retryDelay`);
+ * a timeout is never retried, since the action may have run. Large requests and responses go through the bulk channel
+ * of the NATS component (see {@link NATS}).
+ *
+ * The event listeners registered through the proxy are removed when it is destroyed.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {buildNatsClientOptions, buildServiceProxy, ServiceInvokeException, type ServiceProxy} from '@lakutata/nats'
+ *
+ * type Order = {id: number, total: number}
+ *
+ * class Billing extends Component {
+ *     @Inject('orderService')
+ *     protected readonly orderService: ServiceProxy
+ *
+ *     public async total(id: number): Promise<number | undefined> {
+ *         try {
+ *             //The action of the order service matching {cmd: 'order.get'}, its input {id}; 30 seconds at most
+ *             const order: Order = await this.orderService.invoke({cmd: 'order.get', id: id}, 30000)
+ *             return order.total
+ *         } catch (error) {
+ *             //The action failed: the remote error's errno and statusCode are copied
+ *             if (error instanceof ServiceInvokeException && error.statusCode === 404) return undefined
+ *             //NatsNoRespondersAvailableException (not running, after the retries), NatsRequestTimeoutException…
+ *             throw error
+ *         }
+ *     }
+ * }
+ *
+ * Application
+ *     .run({
+ *         id: 'billing.app',
+ *         name: 'Billing',
+ *         components: {
+ *             nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'}),
+ *             billing: {class: Billing}
+ *         },
+ *         providers: {
+ *             orderService: buildServiceProxy({natsComponentName: 'nats', serviceId: 'order.service'})
+ *         }
+ *     })
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const orderService: ServiceProxy = await app.getObject('orderService')
+ *         //The events emitted by the order service with NATS.emitServiceEvent('orderPaid', id, total)
+ *         orderService.on('orderPaid', (id: number, total: number): void => console.log(`Order ${id} paid: ${total}`))
+ *         const billing: Billing = await app.getObject('billing')
+ *         console.log(await billing.total(1))
+ *     })
+ * ```
+ */
+let ServiceProxy = class ServiceProxy extends core_1.Provider {
+    constructor() {
+        super(...arguments);
+        /**
+         * The event listeners registered through this proxy, by event name, removed when it is destroyed.
+         */
+        this.eventListeners = new Map();
+    }
+    /**
+     * Resolve the NATS component.
+     * @throws {Error} When no component is registered under `natsComponentName`.
+     */
+    async init() {
+        this.nats = await this.app.getObject(this.natsComponentName);
+    }
+    /**
+     * Remove the event listeners registered through this proxy.
+     */
+    async destroy() {
+        this.eventListeners.forEach((listeners, eventName) => listeners.forEach((wrapper) => this.nats.offServiceEvent(this.serviceId, eventName, wrapper)));
+        this.eventListeners.clear();
+    }
+    /**
+     * Record an event listener registered through this proxy, to remove it when the proxy is destroyed.
+     * @param eventName The event name.
+     * @param listener The listener.
+     */
+    keepListener(eventName, listener) {
+        const listeners = this.eventListeners.get(eventName) ?? new Map();
+        this.eventListeners.set(eventName, listeners);
+        //Added once
+        if (listeners.has(listener))
+            return undefined;
+        //A wrapper of this proxy: the NATS component shared by the proxies keeps their listeners apart, the same function
+        //added by two proxies included
+        const wrapper = (...args) => listener(...args);
+        listeners.set(listener, wrapper);
+        return wrapper;
+    }
+    /**
+     * Invoke an action of the remote service and return its result.
+     * @param input The message: the action's pattern (as declared by its `@ServiceAction`) and its input, in one object
+     * (`{cmd: 'order.get', id: 1}`). It is encoded with the NATS component's codec (plain JSON data).
+     * @param timeout The time to wait for the response of each attempt, in milliseconds. A missing service fails at once
+     * (no responder), so it only bounds a request received and processed too slowly; `0` waits 600000 (10 minutes).
+     * @returns The action's result (the data of a `StatusResult`).
+     * @throws {ServiceInvokeException} When the action fails, or no action matches: its message is the remote error's, its
+     * `errno`, `statusCode` and other properties are copied from it, its `service` is the service id.
+     * @throws {NatsNoRespondersAvailableException} When nobody received the request, after `maxRetries` retries.
+     * @throws {NatsRequestTimeoutException} When no response arrives in time (never retried: the action may have run).
+     * @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 request too large is not relayed (see
+     * {@link NATS.request}), `CONNECTION_CLOSED` once the connection is closed.
+     */
+    async invoke(input, timeout = 10 * 60 * 1000) {
+        //Only a request nobody received is retried: no instance processed it, so the retry is its first processing.
+        //A timeout (the request may be processed and its response lost) and a failure of the service (processed) are thrown,
+        //a non-idempotent action is never run twice
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await this.nats.request(this.serviceId, input, timeout);
+                return channel_1.ServiceResponseCodec.decode(response, this.serviceId);
+            }
+            catch (e) {
+                if (e instanceof NatsNoRespondersAvailableException_js_1.NatsNoRespondersAvailableException && attempt < this.maxRetries) {
+                    await (0, utils_1.delay)(this.retryDelay);
+                    continue;
+                }
+                throw e;
+            }
+        }
+    }
+    /**
+     * Listen to an event of the remote service, emitted by its NATS component with `emitServiceEvent()`. A listener
+     * registered again for the same event on the same NATS component is ignored.
+     * @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, such as the instances of one service), instead of to each of them.
+     * @returns The proxy, for chaining.
+     */
+    on(eventName, listener, onlySingleClientReceived = false) {
+        const wrapper = this.keepListener(eventName, listener);
+        if (wrapper)
+            this.nats.onServiceEvent(this.serviceId, eventName, wrapper, onlySingleClientReceived);
+        return this;
+    }
+    /**
+     * Listen to the next occurrence of an event of the remote service only.
+     * @param eventName The event name.
+     * @param listener The listener, receiving the event's arguments.
+     * @returns The proxy, for chaining.
+     */
+    once(eventName, listener) {
+        if (!this.keepListener(eventName, listener))
+            return this;
+        //The function registered is the one kept: off() removes it
+        const registered = (...args) => {
+            this.eventListeners.get(eventName)?.delete(listener);
+            return listener(...args);
+        };
+        this.eventListeners.get(eventName).set(listener, registered);
+        this.nats.onceServiceEvent(this.serviceId, eventName, registered);
+        return this;
+    }
+    /**
+     * Stop listening to an event of the remote service.
+     * @param eventName The event name.
+     * @param listener The listener to remove; without it, every listener of the event added through this proxy (the
+     * listeners added through the other proxies or `NATS.onServiceEvent()` are kept).
+     * @returns The proxy, for chaining.
+     */
+    off(eventName, listener) {
+        //This proxy's listeners only: the other proxies of the NATS component keep theirs
+        const listeners = this.eventListeners.get(eventName);
+        if (!listeners)
+            return this;
+        for (const [registered, wrapper] of [...listeners]) {
+            if (listener && registered !== listener)
+                continue;
+            this.nats.offServiceEvent(this.serviceId, eventName, wrapper);
+            listeners.delete(registered);
+        }
+        if (!listeners.size)
+            this.eventListeners.delete(eventName);
+        return this;
+    }
+};
+exports.ServiceProxy = ServiceProxy;
+__decorate([
+    (0, di_1.Inject)(core_1.Application),
+    __metadata("design:type", core_1.Application
+    /**
+     * The name of the NATS component the proxy uses.
+     */
+    )
+], ServiceProxy.prototype, "app", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], ServiceProxy.prototype, "natsComponentName", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], ServiceProxy.prototype, "serviceId", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().optional().default(3)),
+    __metadata("design:type", Number)
+], ServiceProxy.prototype, "maxRetries", void 0);
+__decorate([
+    (0, di_1.Configurable)(core_1.DTO.Number().integer().optional().default(100)),
+    __metadata("design:type", Number)
+], ServiceProxy.prototype, "retryDelay", void 0);
+exports.ServiceProxy = ServiceProxy = __decorate([
+    (0, di_1.Singleton)()
+], ServiceProxy);

package/dist/cjs/types/SubscribeOptions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The options of {@link NATS.subscribe}.
+ */
+export type SubscribeOptions = {
+    /**
+     * The queue group of the subscription: the subscriptions of one queue group on one subject share its messages, each
+     * message delivered to one of them only (load balancing between the instances of a service).
+     * @default none: every subscription receives every message
+     */
+    queue?: string;
+    /**
+     * The number of messages after which the subscription ends by itself (unsubscribed automatically).
+     * @default none: no limit
+     */
+    max?: number;
+    /**
+     * Whether the messages are handled one after the other, each callback awaited before the next message, instead of
+     * concurrently (a callback started for each message as it arrives).
+     * @default false
+     */
+    iterator?: boolean;
+    /**
+     * Build the response to a request (a message with a reply subject) whose handling failed: the callback threw, the
+     * payload could not be decoded or read from the object store, or the response could not be encoded or sent. Its
+     * return value is encoded with the codec and sent (never relayed through the object store); `undefined` answers
+     * nothing, and the requester waits for its timeout. Without it, a failed request is not answered either.
+     * It lets an upper layer (such as the service entrypoint) answer with its own error protocol.
+     * @param error The error of the handling.
+     * @returns The payload of the response, or `undefined` to answer nothing.
+     * @default none: a failed request is not answered
+     */
+    errorResponse?: (error: any) => any;
+};

package/dist/esm/codecs/JSONCodec.js

@@ -0,0 +1,41 @@
+/**
+ * Create the JSON codec of the NATS messages, for the `codec` option of {@link buildNatsClientOptions}. A value is sent
+ * as the UTF-8 JSON text of a one-element array (`{id: 1}` is sent as `[{"id":1}]`), so that every value, `null` and
+ * the strings included, has a JSON form; the peers written in other languages wrap and unwrap that array.
+ *
+ * The values go through `JSON.stringify()`: a `Date` arrives as its ISO string, a `Buffer` as
+ * `{type: 'Buffer', data: [...]}`, a class instance as a plain object, `undefined` as `null` (and is dropped from the
+ * objects), `NaN` and `Infinity` as `null`; a `bigint` or a circular value fails the encoding with a `TypeError`.
+ * Decoding bytes which are not such JSON throws a `SyntaxError`. Both sides of a subject must use the same codec.
+ * @returns The codec.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildNatsClientOptions, jsonCodec} from '@lakutata/nats'
+ *
+ * Application.run({
+ *     id: 'json.app',
+ *     name: 'JSON',
+ *     components: {
+ *         //Readable messages, for peers which do not speak MessagePack
+ *         nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222', codec: jsonCodec()})
+ *     }
+ * })
+ *
+ * const codec = jsonCodec()
+ * const bytes: Uint8Array = codec.encode({id: 1, at: new Date(0)})
+ * console.log(Buffer.from(bytes).toString()) //[{"id":1,"at":"1970-01-01T00:00:00.000Z"}]
+ * console.log(codec.decode(bytes)) //{id: 1, at: '1970-01-01T00:00:00.000Z'}
+ * ```
+ */
+export function jsonCodec() {
+    return {
+        encode(d) {
+            return Buffer.from(JSON.stringify([d]));
+        },
+        decode(a) {
+            const [res] = JSON.parse(Buffer.from(a).toString());
+            return res;
+        }
+    };
+}

package/dist/esm/codecs/MessagePackCodec.js

@@ -0,0 +1,32 @@
+import { MessagePack } from '@lakutata/utils';
+/**
+ * Create the MessagePack codec of the NATS messages, the default `codec` of the {@link NATS} component. A value is sent
+ * as the MessagePack encoding of a one-element array holding it, smaller and faster to decode than JSON.
+ *
+ * The value is first normalized through JSON (`JSON.parse(JSON.stringify(value))`), so that the peers written in other
+ * languages receive plain JSON data: a `Date` arrives as its ISO string, a `Buffer` as `{type: 'Buffer', data: [...]}`
+ * (the binary data is not kept as binary), a class instance as a plain object, `undefined` as `null` (and is dropped
+ * from the objects); a `bigint` or a circular value fails the encoding with a `TypeError`. Decoding bytes which are not
+ * MessagePack throws. Both sides of a subject must use the same codec.
+ * @returns The codec.
+ * @example
+ * ```typescript
+ * import {messagePackCodec} from '@lakutata/nats'
+ *
+ * const codec = messagePackCodec()
+ * const bytes: Uint8Array = codec.encode({id: 1, tags: ['a', 'b']})
+ * console.log(codec.decode(bytes)) //{id: 1, tags: ['a', 'b']}
+ * console.log(codec.decode(codec.encode(undefined))) //null
+ * ```
+ */
+export function messagePackCodec() {
+    return {
+        encode(d) {
+            return MessagePack.encode(JSON.parse(JSON.stringify([d])));
+        },
+        decode(a) {
+            const [res] = MessagePack.decode(a);
+            return res;
+        }
+    };
+}