@horizon-republic/nestjs-jetstream 2.10.0 → 2.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +58 -71
  2. package/dist/index.cjs +985 -290
  3. package/dist/index.d.cts +214 -45
  4. package/dist/index.d.ts +214 -45
  5. package/dist/index.js +970 -281
  6. package/package.json +25 -20
package/README.md CHANGED
@@ -1,103 +1,90 @@
1
- <div align="center">
2
-
3
- # @horizon-republic/nestjs-jetstream
4
-
5
- **Ship reliable microservices with NATS JetStream and NestJS.**
6
- Events, broadcast, ordered delivery, and RPC — with two lines of config.
7
-
8
- [![npm version](https://img.shields.io/npm/v/@horizon-republic/nestjs-jetstream.svg)](https://www.npmjs.com/package/@horizon-republic/nestjs-jetstream)
9
- [![codecov](https://codecov.io/github/HorizonRepublic/nestjs-jetstream/graph/badge.svg?token=40IPSWFMT4)](https://codecov.io/github/HorizonRepublic/nestjs-jetstream)
10
- [![CI](https://github.com/HorizonRepublic/nestjs-jetstream/actions/workflows/coverage.yml/badge.svg)](https://github.com/HorizonRepublic/nestjs-jetstream/actions)
11
- [![Documentation](https://img.shields.io/badge/docs-online-brightgreen.svg)](https://horizonrepublic.github.io/nestjs-jetstream/)
12
-
13
- [![Node.js](https://img.shields.io/node/v/@horizon-republic/nestjs-jetstream.svg)](https://nodejs.org)
14
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.7%2B-blue.svg)](https://www.typescriptlang.org)
15
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
16
-
17
- </div>
1
+ <p align="center">
2
+ <img src="website/static/img/logo.svg" width="80" alt="nestjs-jetstream"/>
3
+ </p>
4
+
5
+ <h1 align="center">nestjs-jetstream</h1>
6
+
7
+ <p align="center">
8
+ The NATS JetStream transport NestJS microservices need —
9
+ durable, retried, traced — under the same <code>@EventPattern</code>
10
+ and <code>@MessagePattern</code> decorators you already use.
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://www.npmjs.com/package/@horizon-republic/nestjs-jetstream"><img src="https://img.shields.io/npm/v/@horizon-republic/nestjs-jetstream?style=flat&color=f5f5f5&labelColor=CB3837&logo=npm&logoColor=white" alt="npm"/></a>&nbsp;
15
+ <a href="https://www.npmjs.com/package/@horizon-republic/nestjs-jetstream"><img src="https://img.shields.io/npm/dm/@horizon-republic/nestjs-jetstream?style=flat&color=f5f5f5&labelColor=CB3837&logo=npm&logoColor=white" alt="npm downloads"/></a>&nbsp;
16
+ <a href="https://github.com/HorizonRepublic/nestjs-jetstream/actions/workflows/coverage.yml"><img src="https://img.shields.io/github/actions/workflow/status/HorizonRepublic/nestjs-jetstream/coverage.yml?branch=main&style=flat&color=f5f5f5&labelColor=181717&logo=githubactions&logoColor=white&label=ci" alt="CI"/></a>&nbsp;
17
+ <a href="https://codecov.io/github/HorizonRepublic/nestjs-jetstream"><img src="https://img.shields.io/codecov/c/github/HorizonRepublic/nestjs-jetstream?style=flat&color=f5f5f5&labelColor=F01F7A&token=40IPSWFMT4&logo=codecov&logoColor=white" alt="coverage"/></a>&nbsp;
18
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%E2%89%A5%2020-f5f5f5?style=flat&labelColor=339933&logo=nodedotjs&logoColor=white" alt="node"/></a>&nbsp;
19
+ <a href="https://nestjs.com/"><img src="https://img.shields.io/badge/nestjs-10%2B-f5f5f5?style=flat&labelColor=E0234E&logo=nestjs&logoColor=white" alt="nestjs"/></a>&nbsp;
20
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-f5f5f5?style=flat&labelColor=3DA639&logo=opensourceinitiative&logoColor=white" alt="license"/></a>
21
+ </p>
22
+
23
+ <p align="center">
24
+ <a href="https://nestjs-jetstream.horizon-republic.dev/"><b>Documentation</b></a>
25
+ &nbsp;·&nbsp;
26
+ <a href="https://nestjs-jetstream.horizon-republic.dev/docs/getting-started/quick-start">Quick Start</a>
27
+ &nbsp;·&nbsp;
28
+ <a href="https://nestjs-jetstream.horizon-republic.dev/docs/reference/api">API Reference</a>
29
+ </p>
18
30
 
19
31
  ---
20
32
 
21
- ## Why this library?
33
+ ## Why this exists
22
34
 
23
- NestJS ships with a NATS transport, but it's fire-and-forget. Messages vanish if no one's listening. This library adds JetStream — so your messages **survive restarts**, **retry on failure**, and **replay for new consumers**.
35
+ NestJS' [built-in NATS transport](https://docs.nestjs.com/microservices/nats) loses messages on pod restart, doesn't retry on failure, and gives you nothing to debug with. JetStream fixes all three — but wiring it into NestJS by hand is a project on its own.
24
36
 
25
- You keep writing `@EventPattern()` and `@MessagePattern()`. The library handles streams, consumers, and subjects automatically.
37
+ **This library is the swap.** Same `@EventPattern`, same `@MessagePattern`, same `client.emit()`. Durability, retries, and tracing underneath.
26
38
 
27
- ## What's inside
39
+ ## What you get
28
40
 
29
- **Delivery modes** — workqueue (one consumer), broadcast (all consumers), ordered (sequential), and dual-mode RPC (Core or JetStream-backed).
41
+ - **At-least-once delivery** — every event acked after the handler resolves; bounded retries with exponential backoff.
42
+ - **Broadcast** — one message reaches every running pod via per-service durable consumers.
43
+ - **Ordered delivery** — sequential per partition key without giving up horizontal scale.
44
+ - **RPC** — Core for speed, JetStream for durability — same @MessagePattern either way.
45
+ - **DLQ** — typed sink with original headers preserved after retries are exhausted.
46
+ - **Scheduled messages, per-message TTL, health checks, graceful shutdown** — all the production levers.
47
+ - **OpenTelemetry-compatible** — W3C `traceparent` propagated through every hop.
30
48
 
31
- **Operations** — dead letter queue stream, health indicator for Kubernetes probes, graceful shutdown with drain, lifecycle hooks for observability.
32
-
33
- **Flexible** — pluggable codecs (JSON/MsgPack/Protobuf), per-stream configuration, publisher-only mode for API gateways.
34
-
35
- ## Quick Start
49
+ ## Install
36
50
 
37
51
  ```bash
38
- npm install @horizon-republic/nestjs-jetstream
52
+ npm i @horizon-republic/nestjs-jetstream
39
53
  ```
40
54
 
41
- ```typescript
55
+ ## Quick Start
56
+
57
+ ```ts
42
58
  // app.module.ts
43
59
  @Module({
44
60
  imports: [
45
- JetstreamModule.forRoot({ name: 'orders', servers: ['nats://localhost:4222'] }),
46
- JetstreamModule.forFeature({ name: 'orders' }),
61
+ JetstreamModule.forRoot({ servers: ['nats://localhost:4222'] }),
47
62
  ],
48
63
  })
49
64
  export class AppModule {}
65
+ ```
50
66
 
67
+ ```ts
51
68
  // orders.controller.ts
52
69
  @Controller()
53
70
  export class OrdersController {
54
- constructor(@Inject('orders') private client: ClientProxy) {}
55
-
56
- @EventPattern('order.created')
57
- handle(@Payload() data: { orderId: number }) {
58
- console.log('Order created:', data.orderId);
59
- }
60
-
61
- @Get('emit')
62
- emit() {
63
- return this.client.emit('order.created', { orderId: 42 });
71
+ @EventPattern('orders.created')
72
+ async onCreated(@Payload() order: Order) {
73
+ await this.billing.charge(order);
64
74
  }
65
75
  }
66
-
67
- // main.ts — wire the JetStream microservice transport into the HTTP app
68
- async function bootstrap() {
69
- const app = await NestFactory.create(AppModule);
70
- app.connectMicroservice(
71
- { strategy: app.get(JetstreamStrategy) },
72
- { inheritAppConfig: true },
73
- );
74
- app.enableShutdownHooks();
75
- await app.startAllMicroservices();
76
- await app.listen(3000);
77
- }
78
- void bootstrap();
79
76
  ```
80
77
 
81
- ## Documentation
78
+ That's it. At-least-once. Retries on throw. Traced end-to-end.
82
79
 
83
- **[Read the full documentation →](https://horizonrepublic.github.io/nestjs-jetstream/)**
80
+ The full configuration surface, every pattern, and the production checklist live in the [documentation](https://nestjs-jetstream.horizon-republic.dev/).
84
81
 
85
- | Section | What you'll learn |
86
- |---------|-------------------|
87
- | [Getting Started](https://horizonrepublic.github.io/nestjs-jetstream/docs/getting-started/installation) | Installation, module setup, first handler |
88
- | [Messaging Patterns](https://horizonrepublic.github.io/nestjs-jetstream/docs/patterns/rpc) | RPC, Events, Broadcast, Ordered Events |
89
- | [Guides](https://horizonrepublic.github.io/nestjs-jetstream/docs/guides/record-builder) | Handler context, DLQ, health checks, performance tuning |
90
- | [Migration](https://horizonrepublic.github.io/nestjs-jetstream/docs/guides/migration) | From built-in NATS transport or between versions |
91
- | [API Reference](https://horizonrepublic.github.io/nestjs-jetstream/docs/reference/api/) | Full TypeDoc-generated API |
82
+ ## Quality
92
83
 
93
- ## Links
84
+ The transport is covered by an extensive test suite (unit and integration) — see the [Codecov report](https://codecov.io/github/HorizonRepublic/nestjs-jetstream) above.
94
85
 
95
- - [npm](https://www.npmjs.com/package/@horizon-republic/nestjs-jetstream)
96
- - [GitHub](https://github.com/HorizonRepublic/nestjs-jetstream)
97
- - [Documentation](https://horizonrepublic.github.io/nestjs-jetstream/)
98
- - [Issues](https://github.com/HorizonRepublic/nestjs-jetstream/issues)
99
- - [Discussions](https://github.com/HorizonRepublic/nestjs-jetstream/discussions)
86
+ Runnable demos for most supported patterns live under [`examples/`](./examples).
100
87
 
101
- ## License
88
+ ---
102
89
 
103
- MIT
90
+ MIT · © 2026 Horizon Republic · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)