@lakutata/nats 2.3.0 → 3.0.0-beta.0

package/dist/types/interfaces/NatsClientOptions.d.ts

@@ -0,0 +1,106 @@
+import { Codec } from 'nats';
+/**
+ * The options of the {@link NATS} component, given to {@link buildNatsClientOptions}. They are validated when the
+ * component is created: an invalid value fails it.
+ */
+export interface NatsClientOptions {
+    /**
+     * The NATS server, or the servers of a cluster, to connect to: `host:port` or a URL (`nats://user:pass@host:4222`).
+     * The client connects to one of them (in random order unless `noRandomize`) and moves to another on a disconnect.
+     */
+    servers: string | string[];
+    /**
+     * The codec encoding and decoding every payload: {@link messagePackCodec}, {@link jsonCodec}, or any object with
+     * `encode(value)` and `decode(bytes)`. All the applications exchanging messages on a subject must use the same one.
+     * @default messagePackCodec()
+     */
+    codec?: Codec<unknown>;
+    /**
+     * The time to wait for the connection to a server to be established, in milliseconds.
+     * @default 20000
+     */
+    timeout?: number;
+    /**
+     * The token of the server's token authentication.
+     * @default none
+     */
+    token?: string;
+    /**
+     * The user name of the server's user/password authentication.
+     * @default none
+     */
+    user?: string;
+    /**
+     * The password of the server's user/password authentication, with `user`.
+     * @default none
+     */
+    pass?: string;
+    /**
+     * Whether the client prints the protocol messages it sends and receives (to debug a connection).
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * The number of pings left unanswered after which the connection is considered stale and the client reconnects.
+     * @default 2
+     */
+    maxPingOut?: number;
+    /**
+     * The number of reconnection attempts to each server before giving up, `-1` never giving up. Once given up, the
+     * connection is closed for good: the calls fail with the NATS client error `CONNECTION_CLOSED` until the application
+     * restarts.
+     * @default 10
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * The client name shown by the server's monitoring. It also names the default object store bucket of the bulk
+     * channel (`lkt-bulk-{name}`), and the bulk connection (`{name}-bulk`).
+     * @default none
+     */
+    name?: string;
+    /**
+     * Whether the messages this client publishes are never delivered to its own subscriptions.
+     * @default false
+     */
+    noEcho?: boolean;
+    /**
+     * Whether the servers are tried in the order given, instead of a random order.
+     * @default false
+     */
+    noRandomize?: boolean;
+    /**
+     * The interval between the pings the client sends to check the connection, in milliseconds.
+     * @default 120000
+     */
+    pingInterval?: number;
+    /**
+     * Whether the client reconnects after losing its connection (see `maxReconnectAttempts`). While it reconnects, the
+     * outgoing messages are buffered and the requests wait, failing when their timeout passes.
+     * @default true
+     */
+    reconnect?: boolean;
+    /**
+     * Whether the bulk channel is enabled: the payloads too large for the server's `max_payload` are relayed through a
+     * JetStream object store, using a second connection. It needs JetStream on the server; when the channel cannot
+     * start (no JetStream, bucket rejected…), a warning is printed and the component starts without it.
+     * @default true
+     */
+    bulk?: boolean;
+    /**
+     * The object store bucket of the bulk channel, created when missing. The applications exchanging large payloads
+     * must use the same bucket: a reference to an object of another bucket fails with {@link NatsBulkException}.
+     * @default `lkt-bulk-{name}`, `lkt-bulk-default` without `name`
+     */
+    bulkBucket?: string;
+    /**
+     * The time to live of the objects of the bulk channel, in milliseconds. An object is deleted once read; this removes
+     * the ones never read (a requester gone, a response lost). It applies when the bucket is created.
+     * @default 300000 (5 minutes)
+     */
+    bulkTTL?: number;
+    /**
+     * The number of replicas of the bulk bucket in a JetStream cluster, applied when the bucket is created.
+     * @default none: the server's default (one replica)
+     */
+    bulkReplicas?: number;
+}

package/dist/types/lib/ServiceEventCodec.d.ts

@@ -0,0 +1,9 @@
+export interface ServiceEventData {
+    readonly args: any[];
+}
+export declare class ServiceEventCodec {
+    protected static hashEventName(serviceId: string, eventName: string): string;
+    static encode(args: any[]): ServiceEventData;
+    static decode(eventData: ServiceEventData): any[];
+    static formatSubject(serviceId: string, eventName: string): string;
+}

package/dist/types/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/types/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/package.json

@@ -1,42 +1,51 @@
 {
   "name": "@lakutata/nats",
-  "version": "2.3.0",
-  "description": "Lakutata NATS Client",
-  "keywords": [
-    "lakutata",
-    "NATS",
-    "client"
-  ],
-  "author": "myq1991 <myq1991@gmail.com>",
-  "homepage": "https://github.com/lakutata/lakutata-packages",
-  "license": "Apache-2.0",
-  "main": "./dist/CommonExports.js",
-  "types": "./dist/CommonExports.d.ts",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lakutata/lakutata-packages.git"
+  "version": "3.0.0-beta.0",
+  "description": "The NATS component of the lakutata framework: messaging, service proxies, service entrypoint and large payloads.",
+  "type": "module",
+  "main": "./dist/cjs/exports/Nats.js",
+  "types": "./dist/cjs/exports/Nats.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/exports/Nats.d.ts",
+        "default": "./dist/esm/exports/Nats.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Nats.d.ts",
+        "default": "./dist/cjs/exports/Nats.js"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
-    "clean": "shx rm -rf ./dist",
-    "build": "tsc",
-    "rebuild": "npm run clean && npm run build",
-    "test": "npm run test:unit && npm run test:integration",
-    "test:unit": "bun test test/unit",
-    "test:integration": "bun test/run-integration.ts"
-  },
-  "bugs": {
-    "url": "https://github.com/lakutata/lakutata-packages/issues"
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs-pkg": "node ../../scripts/package-build/cjs-package.mjs",
+    "build:js": "npm run build:cjs && npm run build:esm && npm run build:cjs-pkg",
+    "rebuild": "npm run clean && npm run build:js",
+    "compile": "npm run rebuild",
+    "test:unit": "npm run compile && node --test \"dist/esm/tests/unit/*.spec.js\"",
+    "test:integration": "npm run compile && node --test --test-concurrency=1 \"dist/esm/tests/integration/*.spec.js\""
   },
   "dependencies": {
-    "lakutata": "^2.0.121",
     "nats": "^2.29.3"
   },
-  "gitHead": "bb53c6145756661f4cc84b7dd1e62bf41fa0b590",
-  "devDependencies": {
-    "@types/bun": "^1.3.14",
-    "testcontainers": "^12.0.3"
-  }
+  "peerDependencies": {
+    "@lakutata/core": "3.0.0-beta.0",
+    "@lakutata/entrypoint": "3.0.0-beta.0",
+    "@lakutata/utils": "3.0.0-beta.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "!dist/*/tests",
+    "*.md",
+    "LICENSE",
+    "package.json",
+    "THIRD_PARTY_NOTICES.md"
+  ]
 }