@lakutata/nats 3.0.0 → 3.1.0

package/README.md

@@ -1,10 +1,12 @@
 # @lakutata/nats
 
-The NATS component of the lakutata framework: a connection to a NATS server to publish, subscribe and send requests
-(MessagePack or JSON payloads), the service channel of an application served over NATS (`natsServiceEntrypoint`), the
-proxies invoking the actions of the other services and listening to their events (`ServiceProxy`), and the large
-payloads relayed through a JetStream object store. The umbrella package `lakutata` does not re-export it: import it
-from `@lakutata/nats`.
+English | [中文](README.zh-CN.md)
+
+The NATS component of the lakutata framework. It provides a connection to a NATS server to publish, subscribe and send
+requests (with MessagePack or JSON payloads), serves an application's service channel over NATS
+(`natsServiceEntrypoint`), offers proxies that invoke the actions of other services and listen to their events
+(`ServiceProxy`), and relays large payloads through a JetStream object store. The umbrella package `lakutata` does not
+re-export it: import it from `@lakutata/nats`.
 
 ## Installation
 
@@ -12,11 +14,11 @@ from `@lakutata/nats`.
 npm install lakutata @lakutata/nats
 ```
 
-It uses the NATS client `nats` (a dependency) and needs, on the server side:
+It uses the NATS client `nats` (installed as a dependency). On the server side, it needs:
 
-- a NATS server 2.2 or later (the message headers, which the large payloads need);
-- JetStream enabled (`nats-server -js`, or `jetstream {}` in its configuration) for the large payloads. Without it the
-  component starts anyway, prints a warning, and only the payloads over the server's `max_payload` fail.
+- a NATS server 2.2 or later (for message headers, which large payloads need);
+- JetStream enabled (`nats-server -js`, or `jetstream {}` in the server configuration) for large payloads. Without it,
+  the component still starts and prints a warning; only payloads over the server's `max_payload` then fail.
 
 ```shell
 docker run -d --name nats -p 4222:4222 nats:2.12-alpine -js
@@ -27,7 +29,9 @@ docker run -d --name nats -p 4222:4222 nats:2.12-alpine -js
 ### The NATS component
 
 Register the `NATS` component with `buildNatsClientOptions`, then get it with `getObject()` or `@Inject`. It connects
-when it is created: an unreachable server fails the application's start (after `timeout`, 20 seconds by default).
+when it is created: when no server can be reached, its creation fails after `timeout` (20 seconds by default). The
+application then fails to start if the component is created during the start (listed in `bootstrap`, or injected into
+an object that is).
 
 ```typescript
 import {Application} from 'lakutata'
@@ -55,35 +59,36 @@ Application
     })
 ```
 
-- `publish()` sends a message to every subscription of the subject (one per queue group); it is lost when nobody
-  listens.
-- `subscribe()` accepts the wildcards `*` (one token) and `>` (the remaining tokens). Its callback is called for each
-  message as it arrives, or one message after the other with `{iterator: true}`; `{max: n}` ends the subscription
+- `publish()` sends a message to every subscription of the subject (only one member of each queue group receives
+  it); the message is lost when nobody is listening.
+- `subscribe()` accepts the wildcards `*` (one token) and `>` (all remaining tokens). Its callback is called for each
+  message as it arrives, or for one message after another with `{iterator: true}`; `{max: n}` ends the subscription
   after `n` messages. It returns the NATS `Subscription` (`unsubscribe()`, `drain()`).
-- `request()` waits for the first response; its timeout is in milliseconds, 1000 when omitted. A callback which throws
-  leaves the request unanswered (the requester times out) unless the subscription has an `errorResponse`.
-- A lost connection is reestablished in the background (`reconnect`, `maxReconnectAttempts`: 10 attempts per server
-  by default, `-1` for ever); the requests sent meanwhile fail when their timeout passes. Once the client gives up,
-  every call fails with the NATS client error `CONNECTION_CLOSED`.
-- When the application stops, the component drains its connections: the messages in progress are handled and the
-  outgoing ones flushed before they close.
-
-The connection options: `servers`, `codec`, `timeout`, `token`, `user`, `pass`, `debug`, `maxPingOut`,
-`maxReconnectAttempts`, `name`, `noEcho`, `noRandomize`, `pingInterval`, `reconnect`, and the large payloads'
-`bulk`, `bulkBucket`, `bulkTTL`, `bulkReplicas` (see [Large payloads](#large-payloads)).
+- `request()` waits for the first response. Its timeout is in milliseconds and defaults to 10 minutes. When a
+  responder's callback throws, the request goes unanswered and the requester times out, unless the subscription has
+  an `errorResponse`.
+- A lost connection is reestablished in the background (`reconnect`; `maxReconnectAttempts` is 10 attempts per server
+  by default, `-1` to retry forever). Requests sent in the meantime fail when their timeout expires. Once the client
+  gives up, every call fails with the NATS client error `CONNECTION_CLOSED`.
+- When the application stops, the component drains its connections: messages in progress are handled and outgoing
+  messages are flushed before the connections close.
+
+The connection options are `servers`, `codec`, `timeout`, `token`, `user`, `pass`, `debug`, `maxPingOut`,
+`maxReconnectAttempts`, `name`, `noEcho`, `noRandomize`, `pingInterval` and `reconnect`, plus the large-payload options
+`bulk`, `bulkBucket`, `bulkTTL` and `bulkReplicas` (see [Large payloads](#large-payloads)).
 
 ### The codecs
 
-Every payload is encoded with the component's `codec`, the same on both sides of a subject:
+Every payload is encoded with the component's `codec`, which must be the same on both sides of a subject:
 
 - `messagePackCodec()` (the default): MessagePack, compact and fast;
-- `jsonCodec()`: JSON text, readable and easy for the clients of other languages.
+- `jsonCodec()`: JSON text, readable and easy to handle for clients written in other languages.
 
-Both send a value as a one-element array (`[value]`) and normalize it through JSON first, so that the clients of
-other languages receive plain JSON data: a `Date` arrives as its ISO string, a `Buffer` as
-`{type: 'Buffer', data: [...]}`, a class instance as a plain object, `undefined` as `null`; a `bigint` fails the
-encoding. Any object with `encode(value): Uint8Array` and `decode(bytes)` can be given, such as `StringCodec()`
-(re-exported from `nats`) for string payloads.
+Both send a value as a one-element array (`[value]`) and first normalize it through JSON, so that clients in other
+languages receive plain JSON data: a `Date` arrives as its ISO string, a `Buffer` as `{type: 'Buffer', data: [...]}`,
+a class instance as a plain object, and `undefined` as `null`; a `bigint` cannot be encoded. Any object with
+`encode(value): Uint8Array` and `decode(bytes)` can serve as the codec, such as `StringCodec()` (re-exported from
+`nats`) for string payloads.
 
 ```typescript
 import {Application} from 'lakutata'
@@ -100,9 +105,9 @@ Application.run({
 
 ### Serving the service actions over NATS
 
-`natsServiceEntrypoint` serves the service channel of the `Entrypoint` component: the requests sent to the
-application's id are dispatched to the `@ServiceAction` methods of the controllers, and answered with a service
-response `{success, error, payload}`.
+`natsServiceEntrypoint` serves the `Entrypoint` component's service channel over NATS: requests sent to the
+application's id are dispatched to the controllers' `@ServiceAction` methods and answered with a service response
+`{success, error, payload}`.
 
 ```typescript
 import {Application, DTO} from 'lakutata'
@@ -145,26 +150,26 @@ Application
     })
 ```
 
-- The subject is the application id unless the `subject` option sets another; the proxies use it as their
-  `serviceId`. The service events stay under the application id.
-- The instances of the service join one queue group (`{subject}.serviceQueue` by default): each request is handled by
-  one instance.
-- A failed action (no matching action, invalid input, access denied, an exception) is answered with its error's
-  properties; a request which cannot be decoded is answered with an error too, so the requester never waits for its
+- The subject is the application id, unless the `subject` option sets another one; proxies use the subject as their
+  `serviceId`. The events of `NATS.emitServiceEvent()` always use the application id.
+- All instances of the service join one queue group (`{subject}.serviceQueue` by default), so each request is handled
+  by a single instance.
+- A failed action (no matching action, invalid input, access denied, an exception) is answered with the properties of
+  its error. A request that cannot be decoded is also answered with an error, so the requester never waits for its
   timeout.
-- `Entrypoint.broadcast()` publishes its events under the entrypoint's subject, to the service proxies (counted 0:
-  NATS does not tell how many receive them); `NATS.emitServiceEvent()` publishes under the application id.
-  `Entrypoint.notify()` does not reach the NATS clients (NATS has no client ids).
-- When the entrypoint stops, its subscription is drained: no new request is received (the callers retry, see below)
+- `Entrypoint.broadcast()` publishes its events to the service proxies under the entrypoint's subject, and returns 0,
+  because NATS does not tell how many clients receive them; `NATS.emitServiceEvent()` publishes under the application
+  id. `Entrypoint.notify()` does not reach NATS clients, since NATS has no client ids.
+- When the entrypoint stops, its subscription is drained: it receives no new requests (callers retry them, see below),
   and the requests in progress are answered.
-- It is `SetupNatsServiceEntrypoint` of 2.x, renamed as the functions of 3.0 (no alias): the applications of 2.x rename
-  their calls, as the ones of `BuildServiceProxy` (`buildServiceProxy`), `JSONCodec` (`jsonCodec`) and `MessagePackCodec`
-  (`messagePackCodec`).
+- In 2.x it was `SetupNatsServiceEntrypoint`. Like all functions in 3.0, it was renamed without an alias, so
+  applications written for 2.x must rename their calls, as they must for `BuildServiceProxy` (now `buildServiceProxy`),
+  `JSONCodec` (`jsonCodec`) and `MessagePackCodec` (`messagePackCodec`).
 
 ### Invoking a service: the service proxy
 
-A `ServiceProxy` invokes the actions of one remote service and listens to its events. It is a singleton provider, shared
-by the requests: declare one per service with `buildServiceProxy` in the `providers` of the application, as in 2.x.
+A `ServiceProxy` invokes the actions of one remote service and listens to its events. It is a singleton provider shared
+by all requests: declare one per service with `buildServiceProxy` in the application's `providers`, as in 2.x.
 
 ```typescript
 import {Application} from 'lakutata'
@@ -201,41 +206,44 @@ Application
     })
 ```
 
-- `invoke(input, timeout)` returns the action's result. Its timeout defaults to 10 minutes: a service which is not
-  running fails at once, so the timeout only bounds an action which is too slow.
-- A request nobody received (`NatsNoRespondersAvailableException`: the service is not running, or restarting) is sent
-  again, `maxRetries` times (3 by default) every `retryDelay` milliseconds (100 by default), then thrown. A timeout and
-  a failure of the service are never retried: the action may have run, and a non-idempotent action never runs twice.
-- A failed action is thrown as a `ServiceInvokeException`: its message is the remote error's, its `errno`,
-  `statusCode` and other properties are copied from it, and its `service` is the service id.
-- `on(event, listener)`, `once(event, listener)` and `off(event, listener?)` listen to the events the service emits
-  with `NATS.emitServiceEvent()`. With `on(event, listener, true)`, each event goes to one listener among those
-  registered so, across the applications (a queue group). The events are delivered at most once: an application not
-  connected when one is emitted misses it. The listeners registered through a proxy are removed when it is
-  destroyed.
+- `invoke(input, timeout)` returns the action's result. Its timeout defaults to 10 minutes: a call to a service that is
+  not running fails at once, so the timeout only limits actions that are too slow.
+- A request that no instance received (`NatsNoRespondersAvailableException`: the service is not running, or is
+  restarting) is sent again up to `maxRetries` times (3 by default), every `retryDelay` milliseconds (100 by default);
+  after that, the exception is thrown. Timeouts and failures of the service are never retried, because the action may
+  already have run: this way, a non-idempotent action never runs twice.
+- A failed action is thrown as a `ServiceInvokeException`. Its message is that of the remote error, its `errno`,
+  `statusCode` and other properties are copied from the remote error, and its `service` is the service id.
+- `on(event, listener)`, `once(event, listener)` and `off(event, listener?)` manage listeners for the events that the
+  service emits with `NATS.emitServiceEvent()`. With `on(event, listener, true)`, each event goes to only one of the
+  listeners registered this way, across all applications (a queue group). Events are delivered at most once: an
+  application that is not connected when an event is emitted misses it. The listeners registered through a proxy are
+  removed when the proxy is destroyed.
 
 ### Large payloads
 
-A NATS message cannot exceed the server's `max_payload` (1 MiB by default). The component relays the requests and the
-responses of 90% of `max_payload` or more through a JetStream object store, over a second connection, so the large
-transfers never delay the small messages: the sender stores the encoded payload and sends a small reference, the
-receiver reads the object and deletes it. The callbacks, the actions and `invoke()` see the whole value.
+A NATS message cannot exceed the server's `max_payload` (1 MiB by default). The component relays requests and
+responses of 90% of `max_payload` or more through a JetStream object store, over a second connection, so that large
+transfers never delay small messages: the sender stores the encoded payload and sends a small reference, and the
+receiver reads the object, then deletes it. Callbacks, actions and `invoke()` always see the whole value.
 
-- It is on by default (`bulk: true`) and needs JetStream. When it cannot start (no JetStream, the bucket refused), the
-  component prints a warning and starts without it.
-- The applications exchanging large payloads must share their bucket: set the same `bulkBucket` on all of them. The
-  default bucket depends on the `name` option (`lkt-bulk-{name}`, `lkt-bulk-default` without it), so two applications
+- This bulk channel is on by default (`bulk: true`) and needs JetStream. When it cannot start (no JetStream, or the
+  server refuses the bucket), the component prints a warning and starts without it.
+- Applications that exchange large payloads must share a bucket: set the same `bulkBucket` on all of them. The default
+  bucket depends on the `name` option (`lkt-bulk-{name}`, or `lkt-bulk-default` without a name), so two applications
   with different names cannot read each other's objects (`NatsBulkException`).
-- The objects not read (a requester gone, a response lost) expire after `bulkTTL` (5 minutes by default);
-  `bulkReplicas` sets the bucket's replicas in a cluster. Both apply when the bucket is created.
-- A large response is relayed when the requester declared the bulk channel (its requests carry it). A large request
-  is relayed when the responders support it: learned from a previous response on the same subject, else asked once by
-  a probe of the subject (`_LKT.BULK.<subject>`), which the responders with the bulk channel answer and the older
-  versions ignore (the request is then sent as a message, and fails over `max_payload`).
-- The applications without the bulk channel (`bulk: false`, or the versions before it) keep working with the others:
-  they receive the payloads themselves, and a payload over `max_payload` fails.
-- The published messages and the service events are never relayed: over `max_payload`, `publish()` and
-  `emitServiceEvent()` throw the NATS client error `MAX_PAYLOAD_EXCEEDED`.
+- Objects that are never read (the requester has gone, a response was lost) expire after `bulkTTL` (5 minutes by
+  default); `bulkReplicas` sets the number of replicas of the bucket in a cluster. Both apply when the bucket is
+  created.
+- A large response is relayed when the requester has declared the bulk channel (its requests carry this declaration). A
+  large request is relayed when the responders support it. The component learns this from an earlier response on the
+  same subject, or else asks once with a probe of the subject (`_LKT.BULK.<subject>`): responders with the bulk channel
+  answer it and older versions ignore it, in which case the request is sent as a plain message and fails if it exceeds
+  `max_payload`.
+- Applications without the bulk channel (`bulk: false`, or versions that predate it) keep working with the others: they
+  receive the payloads directly, and a payload over `max_payload` fails.
+- Published messages and service events are never relayed: over `max_payload`, `publish()` and `emitServiceEvent()`
+  throw the NATS client error `MAX_PAYLOAD_EXCEEDED`.
 
 ```typescript
 import {Application} from 'lakutata'
@@ -256,47 +264,52 @@ Application.run({
 })
 ```
 
-`NATS.bulkEnabled`, `bulkThreshold`, `bulkStatus()` and `headersSupported` tell the state of the bulk channel;
-`putBulk()`, `getBulk()` and `deleteBulk()` use its object store directly. The design is described in
-`docs/large-payload-design.md` (Chinese).
+`NATS.bulkEnabled`, `bulkThreshold`, `bulkStatus()` and `headersSupported` report the state of the bulk channel;
+`putBulk()`, `getBulk()` and `deleteBulk()` access its object store directly. The design is described in
+`docs/large-payload-design.md` (in Chinese).
 
 ## API
 
 | Export | What it is |
 |---|---|
-| `NATS` | The component: `publish`, `request`, `subscribe`, `emitServiceEvent`, `onServiceEvent`, `onceServiceEvent`, `offServiceEvent`, the bulk channel (`bulkEnabled`, `bulkThreshold`, `headersSupported`, `putBulk`, `getBulk`, `deleteBulk`, `bulkStatus`), the event `error` |
-| `buildNatsClientOptions` | Builds the component options of a `NATS` component |
+| `NATS` | The component: `publish`, `request`, `subscribe`, `emitServiceEvent`, `onServiceEvent`, `onceServiceEvent`, `offServiceEvent`, the bulk channel (`bulkEnabled`, `bulkThreshold`, `headersSupported`, `putBulk`, `getBulk`, `deleteBulk`, `bulkStatus`); the `error` event |
+| `buildNatsClientOptions` | Builds the component options for a `NATS` component |
 | `NatsClientOptions` | Its options: the connection, the codec and the bulk channel |
 | `SubscribeOptions` | The options of `subscribe()`: `queue`, `max`, `iterator`, `errorResponse` |
-| `messagePackCodec`, `jsonCodec` | The codecs of the payloads |
+| `messagePackCodec`, `jsonCodec` | The payload codecs |
 | `StringCodec`, `Codec`, `Subscription`, `RetentionPolicy` | Re-exported from `nats` |
-| `natsServiceEntrypoint` | The service adapter of an entrypoint served over NATS |
+| `natsServiceEntrypoint` | The entrypoint's service adapter over NATS |
 | `NatsServiceEntrypointOptions` | Its options: `subject`, `queue`, `name`, `middlewares` |
-| `ServiceProxy` | The singleton provider invoking the actions of a remote service and listening to its events |
-| `buildServiceProxy` | Builds the provider options of a `ServiceProxy` |
+| `ServiceProxy` | The singleton provider that invokes the actions of a remote service and listens to its events |
+| `buildServiceProxy` | Builds the provider options for a `ServiceProxy` |
 | `BuildServiceProxyOptions` | Its options: `natsComponentName`, `serviceId`, `maxRetries`, `retryDelay` |
 | `ServiceInvokeException` and the `Nats*Exception` classes | See [Errors](#errors) |
 
-The typings document each declaration with examples.
+The typings document every declaration, with examples.
 
 ## Errors
 
 | Exception | Thrown when |
 |---|---|
 | `ServiceInvokeException` (`E_SERVICE_INVOKE`, or the remote error's `errno`) | `ServiceProxy.invoke()`: the remote action failed; it carries the remote error's properties and the `service` id. Re-exported from `@lakutata/entrypoint` |
-| `NatsNoRespondersAvailableException` (`E_NATS_NO_RESPONDERS_AVAILABLE`, 503) | `request()`: nobody listens on the subject; `invoke()` after its retries |
+| `NatsNoRespondersAvailableException` (`E_NATS_NO_RESPONDERS_AVAILABLE`, 503) | `request()`: nobody is listening on the subject; `invoke()`, after its retries |
 | `NatsRequestTimeoutException` (`E_NATS_REQUEST_TIMEOUT`, 408) | `request()`, `invoke()`: no response in time |
-| `NatsBulkException` (`E_NATS_BULK`, 502) | The bulk channel failed: disabled, the object store refused a write or a read, an object expired or in another bucket. On the service side, the requester receives it as a `ServiceInvokeException` whose `errno` is `E_NATS_BULK` |
-| `NatsBadRequestException` (400), `NatsForbiddenException` (403), `NatsNotFoundException` (404), `NatsInternalServerException` (500) | `request()`: an error of the NATS client with that code; the core requests do not produce them |
-| `InvalidValueException` (from `lakutata`) | The component options are invalid, when the component is created |
+| `NatsBulkException` (`E_NATS_BULK`, 502) | The bulk channel failed: it is disabled, the object store refused a write or a read, or an object expired or is in another bucket. When this happens on the service side, the requester receives a `ServiceInvokeException` whose `errno` is `E_NATS_BULK` |
+| `NatsBadRequestException` (400), `NatsForbiddenException` (403), `NatsNotFoundException` (404), `NatsInternalServerException` (500) | `request()`: a NATS client error with that code; core NATS requests do not produce them |
+| `InvalidObjectOptionsException` (from `lakutata`) | An option of the component has an invalid value; the application fails to start |
+| `InvalidValueException` (from `lakutata`) | The component is created without `servers` |
 
-The other failures are the NATS client's errors (`NatsError`, with a `code`): `MAX_PAYLOAD_EXCEEDED` for a payload
-over `max_payload` which is not relayed, `CONNECTION_CLOSED` once the connection is closed, `CONNECTION_REFUSED` or a
-connection timeout when no server can be reached at the start. The codec's errors (a `bigint`, a circular value) are thrown as they are.
+Other failures are errors of the NATS client (`NatsError`, with a `code`): `MAX_PAYLOAD_EXCEEDED` for a payload over
+`max_payload` that is not relayed, `CONNECTION_CLOSED` once the connection is closed, and `CONNECTION_REFUSED` or a
+connection timeout when no server can be reached at the start. Codec errors (a `bigint`, a circular value) are thrown
+as they are.
 
 ## See also
 
-- `@lakutata/entrypoint` (`lakutata/com/entrypoint`, `lakutata/decorator/ctrl`): the controllers, `@ServiceAction` and
-  the other transports; `doc/en/ActionPattern.md` of the package `lakutata` (Chinese in `doc/zh`) for the patterns.
+- The guide on the website: [NATS](https://lakutata.com/guide/NATS).
+- `doc/en/NATS.md` in the `lakutata` package (Chinese version in `doc/zh`): the guide to NATS.
+- `@lakutata/entrypoint` (`lakutata/com/entrypoint`, `lakutata/decorator/ctrl`): controllers, `@ServiceAction` and the
+  other transports; for patterns, see section 2 of `doc/en/ServiceCalls.md` in the `lakutata` package (Chinese version
+  in `doc/zh`).
 - `@lakutata/grpc/service`: the same service channel and proxy over gRPC.
 - `docs/large-payload-design.md`: the design of the large payloads.

package/README.zh-CN.md

@@ -0,0 +1,251 @@
+# @lakutata/nats
+
+[English](README.md) | 中文
+
+lakutata 框架的 NATS 组件。它连接 NATS 服务器，用来发布、订阅和发送请求（数据为 MessagePack 或 JSON 格式）；通过 NATS 提供应用的服务通道（`natsServiceEntrypoint`）；提供服务代理，用来调用其他服务的动作并监听它们的事件（`ServiceProxy`）；还会通过 JetStream 的对象存储转发大数据。`lakutata` 包没有重新导出它：请从 `@lakutata/nats` 导入。
+
+## 安装
+
+```shell
+npm install lakutata @lakutata/nats
+```
+
+它使用 NATS 客户端 `nats`（作为依赖一起安装）。服务器方面，它需要：
+
+- NATS 服务器 2.2 或更高版本（大数据传输要用到消息头）；
+- 为大数据传输启用 JetStream（`nats-server -js`，或者在服务器配置中写 `jetstream {}`）。没有 JetStream 时，组件仍然会启动，并打印一条警告；这时只有超过服务器 `max_payload` 的数据会失败。
+
+```shell
+docker run -d --name nats -p 4222:4222 nats:2.12-alpine -js
+```
+
+## 用法
+
+### NATS 组件
+
+用 `buildNatsClientOptions` 注册 `NATS` 组件，然后通过 `getObject()` 或 `@Inject` 获取它。组件在创建时连接服务器：所有服务器都连不上时，创建会在 `timeout`（默认 20 秒）之后失败。如果组件是在应用启动过程中创建的（列在 `bootstrap` 里，或者注入到了这样的对象中），应用的启动也会随之失败。
+
+```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', error))
+        //应答者：返回值就是请求的响应；同一个队列组里的实例分担请求
+        nats.subscribe('price.get', async (input: {sku: string}): Promise<number> => input.sku.length * 10, {queue: 'pricing'})
+        //带通配符的订阅者：第二个参数是消息到达的主题
+        nats.subscribe('price.changed.*', (price: number, subject: string): void => console.log(subject, price))
+        nats.publish('price.changed.eu', 42)
+        //返回响应；没有应答者时立即抛出 NatsNoRespondersAvailableException，5 秒内没有响应时抛出 NatsRequestTimeoutException
+        console.log(await nats.request('price.get', {sku: 'ABC'}, 5000)) //30
+    })
+```
+
+- `publish()` 把消息发给该主题的所有订阅（每个队列组只有一个成员收到）；没有人监听时，消息就丢失了。
+- `subscribe()` 支持通配符 `*`（一段）和 `>`（剩下的所有段）。每条消息一到达就调用回调；设置 `{iterator: true}` 时则逐条依次处理；`{max: n}` 在收到 `n` 条消息后结束订阅。它返回 NATS 的 `Subscription`（`unsubscribe()`、`drain()`）。
+- `request()` 等待第一个响应。超时以毫秒为单位，默认 10 分钟。应答者的回调抛出错误时，请求得不到响应，请求方最终超时；除非订阅设置了 `errorResponse`。
+- 连接断开后会在后台重新连接（`reconnect`；`maxReconnectAttempts` 默认每个服务器 10 次，`-1` 表示一直重试）。在此期间发送的请求会在超时后失败。客户端放弃重连之后，所有调用都以 NATS 客户端错误 `CONNECTION_CLOSED` 失败。
+- 应用停止时，组件会排空它的连接：在连接关闭之前，正在处理的消息处理完，待发送的消息发送出去。
+
+连接选项有 `servers`、`codec`、`timeout`、`token`、`user`、`pass`、`debug`、`maxPingOut`、`maxReconnectAttempts`、`name`、`noEcho`、`noRandomize`、`pingInterval` 和 `reconnect`，以及大数据传输的选项 `bulk`、`bulkBucket`、`bulkTTL` 和 `bulkReplicas`（见[大数据传输](#大数据传输)）。
+
+### 编码方式
+
+所有数据都用组件的 `codec` 编码，同一个主题的两端必须相同：
+
+- `messagePackCodec()`（默认）：MessagePack，紧凑而且快；
+- `jsonCodec()`：JSON 文本，可以直接阅读，也方便其他语言写的客户端处理。
+
+两者都把值放进只有一个元素的数组（`[value]`）发送，并且先把值转成 JSON，让其他语言的客户端收到的都是普通的 JSON 数据：`Date` 变成 ISO 字符串，`Buffer` 变成 `{type: 'Buffer', data: [...]}`，类的实例变成普通对象，`undefined` 变成 `null`；`bigint` 无法编码。任何带有 `encode(value): Uint8Array` 和 `decode(bytes)` 的对象都可以作为编码方式，比如用于字符串数据的 `StringCodec()`（从 `nats` 重新导出）。
+
+```typescript
+import {Application} from 'lakutata'
+import {buildNatsClientOptions, jsonCodec} from '@lakutata/nats'
+
+Application.run({
+    id: 'json.app',
+    name: 'JSON',
+    components: {
+        nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222', codec: jsonCodec()})
+    }
+})
+```
+
+### 通过 NATS 提供服务动作
+
+`natsServiceEntrypoint` 通过 NATS 提供 `Entrypoint` 组件的服务通道：发给应用 id 的请求会分派给控制器的 `@ServiceAction` 方法，并以封套 `{success, error, payload}` 响应。
+
+```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, type NATS} from '@lakutata/nats'
+
+class GetOrderDTO extends DTO {
+    @Expect(DTO.Number().integer().required())
+    public id!: number
+}
+
+class OrderController extends Controller {
+    @ServiceAction({cmd: 'order.get'}, GetOrderDTO)
+    public async get(input: GetOrderDTO): Promise<{ id: number, total: number }> {
+        return {id: input.id, total: 42}
+    }
+}
+
+Application
+    .run({
+        //请求的主题，也是调用这个服务的代理所用的 serviceId
+        id: 'order.service',
+        name: 'OrderService',
+        components: {
+            nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'}),
+            entrypoint: buildEntrypoints({
+                controllers: [OrderController],
+                //主题为 "order.service"（应用 id），队列组为 "order.service.serviceQueue"
+                service: natsServiceEntrypoint('nats')
+            })
+        },
+        bootstrap: ['entrypoint']
+    })
+    .onLaunched(async (app: Application): Promise<void> => {
+        //服务事件：这个服务的代理如果监听了 "orderPaid"，就会收到它
+        const nats: NATS = await app.getObject('nats')
+        nats.emitServiceEvent('orderPaid', 1, 42)
+    })
+```
+
+- 主题是应用 id，`subject` 选项可以换成别的主题；代理把这个主题作为自己的 `serviceId`。`NATS.emitServiceEvent()` 的事件始终使用应用 id。
+- 服务的所有实例加入同一个队列组（默认为 `{subject}.serviceQueue`），所以每个请求只由一个实例处理。
+- 动作失败时（没有匹配的动作、输入不合法、访问被拒绝、抛出异常），响应中带有错误的各个属性。无法解码的请求也会得到错误响应，所以请求方不会一直等到超时。
+- `Entrypoint.broadcast()` 在入口的主题下把事件发布给服务代理，并返回 0，因为 NATS 不会告诉发送方有多少客户端收到了事件；`NATS.emitServiceEvent()` 则在应用 id 下发布。`Entrypoint.notify()` 到达不了 NATS 客户端，因为 NATS 没有客户端 id。
+- 入口停止时，它的订阅会被排空：不再接收新请求（调用方会重试，见下文），正在处理的请求会得到响应。
+- 它在 2.x 中叫 `SetupNatsServiceEntrypoint`。与 3.0 中的所有函数一样，它改了名字，没有保留别名，所以为 2.x 编写的应用必须修改调用处的名字；`BuildServiceProxy`（现在是 `buildServiceProxy`）、`JSONCodec`（`jsonCodec`）和 `MessagePackCodec`（`messagePackCodec`）也是如此。
+
+### 调用服务：服务代理
+
+`ServiceProxy` 用来调用某个远端服务的动作，并监听它的事件。它是所有请求共用的单例提供者：每个服务用 `buildServiceProxy` 在应用的 `providers` 中声明一个，与 2.x 相同。
+
+```typescript
+import {Application} from 'lakutata'
+import {
+    buildNatsClientOptions,
+    buildServiceProxy,
+    NatsRequestTimeoutException,
+    ServiceInvokeException,
+    type ServiceProxy
+} from '@lakutata/nats'
+
+Application
+    .run({
+        id: 'billing.app',
+        name: 'Billing',
+        components: {
+            nats: buildNatsClientOptions({servers: 'nats://127.0.0.1:4222'})
+        },
+        providers: {
+            orderService: buildServiceProxy({natsComponentName: 'nats', serviceId: 'order.service'})
+        }
+    })
+    .onLaunched(async (app: Application): Promise<void> => {
+        const orderService: ServiceProxy = await app.getObject('orderService')
+        orderService.on('orderPaid', (id: number, total: number): void => console.log(`Order ${id} paid: ${total}`))
+        try {
+            //动作的模式和输入放在同一个对象里，最多等待 30 秒
+            console.log(await orderService.invoke({cmd: 'order.get', id: 1}, 30000))
+        } catch (error) {
+            if (error instanceof ServiceInvokeException) console.error(error.service, error.errno, error.message)
+            else if (error instanceof NatsRequestTimeoutException) console.error('No response in time')
+            else throw error
+        }
+    })
+```
+
+- `invoke(input, timeout)` 返回动作的结果。timeout 默认 10 分钟：服务没有运行时调用会立即失败，所以 timeout 只用来限制太慢的动作。
+- 如果服务没有任何实例收到请求（`NatsNoRespondersAvailableException`：服务没有运行，或者正在重启），代理会重新发送，最多 `maxRetries` 次（默认 3 次），每次间隔 `retryDelay` 毫秒（默认 100）；之后抛出这个异常。超时和服务端的失败从不重试，因为动作可能已经执行过了：这样，非幂等的动作就不会执行两次。
+- 动作失败时，代理抛出 `ServiceInvokeException`。它的消息就是远端错误的消息，`errno`、`statusCode` 和其他属性都从远端错误复制而来，`service` 是服务 id。
+- 服务用 `NATS.emitServiceEvent()` 发出事件，`on(event, listener)`、`once(event, listener)` 和 `off(event, listener?)` 用来添加和移除这些事件的监听器。用 `on(event, listener, true)` 注册时，在所有应用中这样注册的监听器里，每个事件只发给其中一个（队列组）。事件最多送达一次：发送时没有连接的应用会错过它。代理被销毁时，通过它注册的监听器也会被移除。
+
+### 大数据传输
+
+一条 NATS 消息的大小不能超过服务器的 `max_payload`（默认 1 MiB）。达到 `max_payload` 90% 的请求和响应，组件会通过 JetStream 的对象存储转发，并且使用第二条连接，这样大数据的传输就不会拖慢小消息：发送方存入编码后的数据，只发送一个很小的引用；接收方读取对象后把它删除。回调、动作和 `invoke()` 拿到的始终是完整的值。
+
+- 这个大数据通道默认开启（`bulk: true`），需要 JetStream。通道无法启动时（没有 JetStream，或者服务器拒绝了这个对象存储），组件会打印一条警告，然后不带它启动。
+- 互相传输大数据的应用必须使用同一个对象存储：给它们设置相同的 `bulkBucket`。默认的对象存储取决于 `name` 选项（`lkt-bulk-{name}`，没有 name 时是 `lkt-bulk-default`），所以 name 不同的两个应用读不到对方的对象（`NatsBulkException`）。
+- 一直没有被读取的对象（请求方已经离开，或者响应丢失）会在 `bulkTTL`（默认 5 分钟）后过期；`bulkReplicas` 设置对象存储在集群中的副本数。这两项在创建对象存储时生效。
+- 只有请求方声明了大数据通道（它的请求带有这个声明），大的响应才会转发。只有应答者支持时，大的请求才会转发。组件从同一主题上之前的响应得知应答者是否支持；不知道时，就向这个主题发送一次探测（`_LKT.BULK.<subject>`）：有大数据通道的应答者会回答，旧版本则会忽略。后一种情况下，请求作为普通消息发送，超过 `max_payload` 就会失败。
+- 没有大数据通道的应用（`bulk: false`，或者更早的版本）仍然可以和其他应用一起工作：它们直接收到数据，超过 `max_payload` 的数据会失败。
+- 发布的消息和服务事件从不经过对象存储：超过 `max_payload` 时，`publish()` 和 `emitServiceEvent()` 抛出 NATS 客户端错误 `MAX_PAYLOAD_EXCEEDED`。
+
+```typescript
+import {Application} from 'lakutata'
+import {buildNatsClientOptions} from '@lakutata/nats'
+
+Application.run({
+    id: 'report.service',
+    name: 'ReportService',
+    components: {
+        nats: buildNatsClientOptions({
+            servers: 'nats://127.0.0.1:4222',
+            //所有互相传输大数据的应用使用同一个对象存储
+            bulkBucket: 'lkt-bulk-shared',
+            bulkTTL: 10 * 60 * 1000,
+            bulkReplicas: 3
+        })
+    }
+})
+```
+
+`NATS.bulkEnabled`、`bulkThreshold`、`bulkStatus()` 和 `headersSupported` 反映大数据通道的状态；`putBulk()`、`getBulk()` 和 `deleteBulk()` 直接访问它的对象存储。设计见 `docs/large-payload-design.md`。
+
+## API
+
+| 导出 | 说明 |
+|---|---|
+| `NATS` | 组件：`publish`、`request`、`subscribe`、`emitServiceEvent`、`onServiceEvent`、`onceServiceEvent`、`offServiceEvent`，大数据通道（`bulkEnabled`、`bulkThreshold`、`headersSupported`、`putBulk`、`getBulk`、`deleteBulk`、`bulkStatus`）；`error` 事件 |
+| `buildNatsClientOptions` | 构建 `NATS` 组件的选项 |
+| `NatsClientOptions` | 它的选项：连接、编码方式和大数据通道 |
+| `SubscribeOptions` | `subscribe()` 的选项：`queue`、`max`、`iterator`、`errorResponse` |
+| `messagePackCodec`、`jsonCodec` | 数据的编码方式 |
+| `StringCodec`、`Codec`、`Subscription`、`RetentionPolicy` | 从 `nats` 重新导出 |
+| `natsServiceEntrypoint` | 入口的 NATS 服务适配器 |
+| `NatsServiceEntrypointOptions` | 它的选项：`subject`、`queue`、`name`、`middlewares` |
+| `ServiceProxy` | 单例提供者，调用远端服务的动作并监听它的事件 |
+| `buildServiceProxy` | 构建 `ServiceProxy` 的提供者选项 |
+| `BuildServiceProxyOptions` | 它的选项：`natsComponentName`、`serviceId`、`maxRetries`、`retryDelay` |
+| `ServiceInvokeException` 和各个 `Nats*Exception` 类 | 见[错误](#错误) |
+
+类型声明中的每一项都附有说明和示例。
+
+## 错误
+
+| 异常 | 什么时候抛出 |
+|---|---|
+| `ServiceInvokeException`（`E_SERVICE_INVOKE`，或远端错误的 `errno`） | `ServiceProxy.invoke()`：远端动作失败；它带有远端错误的属性和服务 id `service`。从 `@lakutata/entrypoint` 重新导出 |
+| `NatsNoRespondersAvailableException`（`E_NATS_NO_RESPONDERS_AVAILABLE`，503） | `request()`：没有人监听这个主题；`invoke()`：重试之后仍然如此 |
+| `NatsRequestTimeoutException`（`E_NATS_REQUEST_TIMEOUT`，408） | `request()`、`invoke()`：超时前没有收到响应 |
+| `NatsBulkException`（`E_NATS_BULK`，502） | 大数据通道失败：通道已禁用，对象存储拒绝了写入或读取，或者对象已过期、在另一个对象存储中。在服务端发生时，请求方收到 `errno` 为 `E_NATS_BULK` 的 `ServiceInvokeException` |
+| `NatsBadRequestException`（400）、`NatsForbiddenException`（403）、`NatsNotFoundException`（404）、`NatsInternalServerException`（500） | `request()`：带有对应错误码的 NATS 客户端错误；核心 NATS 的请求不会产生它们 |
+| `InvalidObjectOptionsException`（来自 `lakutata`） | 组件的某个选项值不合法；应用启动失败 |
+| `InvalidValueException`（来自 `lakutata`） | 创建组件时没有给出 `servers` |
+
+其他失败都是 NATS 客户端的错误（`NatsError`，带有 `code`）：数据超过 `max_payload` 又没有经过对象存储转发时为 `MAX_PAYLOAD_EXCEEDED`，连接关闭之后为 `CONNECTION_CLOSED`，启动时连不上任何服务器则为 `CONNECTION_REFUSED` 或连接超时。编码方式的错误（`bigint`、带循环引用的值）原样抛出。
+
+## 另见
+
+- 网站上的指南：[NATS](https://lakutata.com/zh/guide/NATS)。
+- `lakutata` 包中的 `doc/zh/NATS.md`：NATS 指南。
+- `@lakutata/entrypoint`（`lakutata/com/entrypoint`、`lakutata/decorator/ctrl`）：控制器、`@ServiceAction` 和其他传输方式；模式见 `lakutata` 包中 `doc/zh/ServiceCalls.md` 的第 2 节。
+- `@lakutata/grpc/service`：同样的服务通道和代理，基于 gRPC。
+- `docs/large-payload-design.md`：大数据传输的设计。

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

@@ -342,8 +342,8 @@ export declare class NATS extends Component {
     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.
+     * {@link NATS.onceServiceEvent}) is ignored. A listener which throws, or an asynchronous listener which rejects, is
+     * reported as an `'error'` event.
      * @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.

package/dist/cjs/components/NATS.js

@@ -615,8 +615,8 @@ class NATS extends core_1.Component {
     }
     /**
      * 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.
+     * {@link NATS.onceServiceEvent}) is ignored. A listener which throws, or an asynchronous listener which rejects, is
+     * reported as an `'error'` event.
      * @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.

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsBadRequestException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Bad Request" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Bad Request" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/dist/cjs/exceptions/NatsBadRequestException.js

@@ -8,10 +8,15 @@ const core_1 = require("@lakutata/core");
  * requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_BAD_REQUEST`, its `statusCode` 400.
  */
 class NatsBadRequestException extends core_1.Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Bad Request" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Bad Request" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Bad Request'), ...params);
         this.errno = 'E_NATS_BAD_REQUEST';
-        this.message = 'Bad Request';
         this.statusCode = 400;
     }
 }

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsForbiddenException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Forbidden" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Forbidden" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/dist/cjs/exceptions/NatsForbiddenException.js

@@ -8,10 +8,15 @@ const core_1 = require("@lakutata/core");
  * core requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_FORBIDDEN`, its `statusCode` 403.
  */
 class NatsForbiddenException extends core_1.Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Forbidden" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Forbidden" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Forbidden'), ...params);
         this.errno = 'E_NATS_FORBIDDEN';
-        this.message = 'Forbidden';
         this.statusCode = 403;
     }
 }

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

@@ -7,6 +7,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsInternalServerException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Internal Server Error" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Internal Server Error" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/dist/cjs/exceptions/NatsInternalServerException.js

@@ -9,10 +9,15 @@ const core_1 = require("@lakutata/core");
  * `statusCode` 500.
  */
 class NatsInternalServerException extends core_1.Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Internal Server Error" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Internal Server Error" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Internal Server Error'), ...params);
         this.errno = 'E_NATS_INTERNAL_SERVER';
-        this.message = 'Internal Server Error';
         this.statusCode = 500;
     }
 }

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

@@ -7,6 +7,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsNoRespondersAvailableException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "No Responders Available" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "No Responders Available" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/dist/cjs/exceptions/NatsNoRespondersAvailableException.js

@@ -9,10 +9,15 @@ const core_1 = require("@lakutata/core");
  * `E_NATS_NO_RESPONDERS_AVAILABLE`, its `statusCode` 503.
  */
 class NatsNoRespondersAvailableException extends core_1.Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "No Responders Available" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "No Responders Available" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'No Responders Available'), ...params);
         this.errno = 'E_NATS_NO_RESPONDERS_AVAILABLE';
-        this.message = 'No Responders Available';
         this.statusCode = 503;
     }
 }

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsNotFoundException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Subject Not Found" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Subject Not Found" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/dist/cjs/exceptions/NatsNotFoundException.js

@@ -8,10 +8,15 @@ const core_1 = require("@lakutata/core");
  * core requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_NOT_FOUND`, its `statusCode` 404.
  */
 class NatsNotFoundException extends core_1.Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Subject Not Found" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Subject Not Found" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Subject Not Found'), ...params);
         this.errno = 'E_NATS_NOT_FOUND';
-        this.message = 'Subject Not Found';
         this.statusCode = 404;
     }
 }

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsRequestTimeoutException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Request Timeout" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Request Timeout" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/dist/cjs/exceptions/NatsRequestTimeoutException.js

@@ -8,10 +8,15 @@ const core_1 = require("@lakutata/core");
  * `E_NATS_REQUEST_TIMEOUT`, its `statusCode` 408.
  */
 class NatsRequestTimeoutException extends core_1.Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Request Timeout" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Request Timeout" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Request Timeout'), ...params);
         this.errno = 'E_NATS_REQUEST_TIMEOUT';
-        this.message = 'Request Timeout';
         this.statusCode = 408;
     }
 }

package/dist/esm/components/NATS.js

@@ -611,8 +611,8 @@ export class NATS extends Component {
     }
     /**
      * 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.
+     * {@link NATS.onceServiceEvent}) is ignored. A listener which throws, or an asynchronous listener which rejects, is
+     * reported as an `'error'` event.
      * @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.

package/dist/esm/exceptions/NatsBadRequestException.js

@@ -5,10 +5,15 @@ import { Exception } from '@lakutata/core';
  * requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_BAD_REQUEST`, its `statusCode` 400.
  */
 export class NatsBadRequestException extends Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Bad Request" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Bad Request" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Bad Request'), ...params);
         this.errno = 'E_NATS_BAD_REQUEST';
-        this.message = 'Bad Request';
         this.statusCode = 400;
     }
 }

package/dist/esm/exceptions/NatsForbiddenException.js

@@ -5,10 +5,15 @@ import { Exception } from '@lakutata/core';
  * core requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_FORBIDDEN`, its `statusCode` 403.
  */
 export class NatsForbiddenException extends Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Forbidden" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Forbidden" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Forbidden'), ...params);
         this.errno = 'E_NATS_FORBIDDEN';
-        this.message = 'Forbidden';
         this.statusCode = 403;
     }
 }

package/dist/esm/exceptions/NatsInternalServerException.js

@@ -6,10 +6,15 @@ import { Exception } from '@lakutata/core';
  * `statusCode` 500.
  */
 export class NatsInternalServerException extends Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Internal Server Error" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Internal Server Error" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Internal Server Error'), ...params);
         this.errno = 'E_NATS_INTERNAL_SERVER';
-        this.message = 'Internal Server Error';
         this.statusCode = 500;
     }
 }

package/dist/esm/exceptions/NatsNoRespondersAvailableException.js

@@ -6,10 +6,15 @@ import { Exception } from '@lakutata/core';
  * `E_NATS_NO_RESPONDERS_AVAILABLE`, its `statusCode` 503.
  */
 export class NatsNoRespondersAvailableException extends Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "No Responders Available" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "No Responders Available" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'No Responders Available'), ...params);
         this.errno = 'E_NATS_NO_RESPONDERS_AVAILABLE';
-        this.message = 'No Responders Available';
         this.statusCode = 503;
     }
 }

package/dist/esm/exceptions/NatsNotFoundException.js

@@ -5,10 +5,15 @@ import { Exception } from '@lakutata/core';
  * core requests the component sends, so it is rarely seen. Its `errno` is `E_NATS_NOT_FOUND`, its `statusCode` 404.
  */
 export class NatsNotFoundException extends Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Subject Not Found" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Subject Not Found" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Subject Not Found'), ...params);
         this.errno = 'E_NATS_NOT_FOUND';
-        this.message = 'Subject Not Found';
         this.statusCode = 404;
     }
 }

package/dist/esm/exceptions/NatsRequestTimeoutException.js

@@ -5,10 +5,15 @@ import { Exception } from '@lakutata/core';
  * `E_NATS_REQUEST_TIMEOUT`, its `statusCode` 408.
  */
 export class NatsRequestTimeoutException extends Exception {
-    constructor() {
-        super(...arguments);
+    /**
+     * Create the exception: its message is "Request Timeout" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Request Timeout" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template, ...params) {
+        super((template ?? 'Request Timeout'), ...params);
         this.errno = 'E_NATS_REQUEST_TIMEOUT';
-        this.message = 'Request Timeout';
         this.statusCode = 408;
     }
 }

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

@@ -342,8 +342,8 @@ export declare class NATS extends Component {
     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.
+     * {@link NATS.onceServiceEvent}) is ignored. A listener which throws, or an asynchronous listener which rejects, is
+     * reported as an `'error'` event.
      * @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.

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsBadRequestException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Bad Request" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Bad Request" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsForbiddenException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Forbidden" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Forbidden" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

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

@@ -7,6 +7,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsInternalServerException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Internal Server Error" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Internal Server Error" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

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

@@ -7,6 +7,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsNoRespondersAvailableException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "No Responders Available" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "No Responders Available" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsNotFoundException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Subject Not Found" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Subject Not Found" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

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

@@ -6,6 +6,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class NatsRequestTimeoutException extends Exception {
     errno: string | number;
-    message: string;
     statusCode: number;
+    /**
+     * Create the exception: its message is "Request Timeout" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Request Timeout" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@lakutata/nats",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "The NATS component of the lakutata framework: messaging, service proxies, service entrypoint and large payloads.",
+  "keywords": [
+    "lakutata",
+    "nats",
+    "messaging",
+    "pubsub",
+    "microservices",
+    "rpc",
+    "typescript"
+  ],
+  "homepage": "https://lakutata.com/packages/nats",
+  "bugs": {
+    "url": "https://github.com/lakutata/lakutata/issues",
+    "email": "admin@lakutata.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lakutata/lakutata.git",
+    "directory": "packages/nats"
+  },
+  "author": "alex.ma",
+  "license": "MIT",
   "type": "module",
   "main": "./dist/cjs/exports/Nats.js",
   "types": "./dist/cjs/exports/Nats.d.ts",
@@ -33,12 +54,12 @@
     "nats": "^2.29.3"
   },
   "peerDependencies": {
-    "@lakutata/core": "3.0.0",
-    "@lakutata/entrypoint": "3.0.0",
-    "@lakutata/utils": "3.0.0"
+    "@lakutata/core": "3.1.0",
+    "@lakutata/entrypoint": "3.1.0",
+    "@lakutata/utils": "3.1.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.13.0 || >=24.11.0"
   },
   "files": [
     "dist",