@horizon-republic/nestjs-jetstream 2.10.0 → 2.11.1
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.
- package/README.md +58 -71
- package/dist/index.cjs +988 -290
- package/dist/index.d.cts +209 -46
- package/dist/index.d.ts +209 -46
- package/dist/index.js +973 -281
- package/package.json +25 -20
package/README.md
CHANGED
|
@@ -1,103 +1,90 @@
|
|
|
1
|
-
<
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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>
|
|
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>
|
|
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>
|
|
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>
|
|
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>
|
|
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>
|
|
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
|
+
·
|
|
26
|
+
<a href="https://nestjs-jetstream.horizon-republic.dev/docs/getting-started/quick-start">Quick Start</a>
|
|
27
|
+
·
|
|
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
|
|
33
|
+
## Why this exists
|
|
22
34
|
|
|
23
|
-
NestJS
|
|
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
|
-
|
|
37
|
+
**This library is the swap.** Same `@EventPattern`, same `@MessagePattern`, same `client.emit()`. Durability, retries, and tracing underneath.
|
|
26
38
|
|
|
27
|
-
## What
|
|
39
|
+
## What you get
|
|
28
40
|
|
|
29
|
-
**
|
|
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
|
-
|
|
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
|
|
52
|
+
npm i @horizon-republic/nestjs-jetstream
|
|
39
53
|
```
|
|
40
54
|
|
|
41
|
-
|
|
55
|
+
## Quick Start
|
|
56
|
+
|
|
57
|
+
```ts
|
|
42
58
|
// app.module.ts
|
|
43
59
|
@Module({
|
|
44
60
|
imports: [
|
|
45
|
-
JetstreamModule.forRoot({
|
|
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
|
-
|
|
55
|
-
|
|
56
|
-
|
|
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
|
-
|
|
78
|
+
That's it. At-least-once. Retries on throw. Traced end-to-end.
|
|
82
79
|
|
|
83
|
-
|
|
80
|
+
The full configuration surface, every pattern, and the production checklist live in the [documentation](https://nestjs-jetstream.horizon-republic.dev/).
|
|
84
81
|
|
|
85
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
88
|
+
---
|
|
102
89
|
|
|
103
|
-
MIT
|
|
90
|
+
MIT · © 2026 Horizon Republic · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
|