@drarzter/kafka-client 0.9.4 → 0.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.
- package/README.md +693 -8
- package/dist/chunk-OR7TPAAE.mjs +4760 -0
- package/dist/chunk-OR7TPAAE.mjs.map +1 -0
- package/dist/chunk-PQVBRDNV.mjs +149 -0
- package/dist/chunk-PQVBRDNV.mjs.map +1 -0
- package/dist/cli/dlq.d.ts +119 -0
- package/dist/cli/dlq.d.ts.map +1 -0
- package/dist/cli/index.d.ts +3 -0
- package/dist/cli/index.d.ts.map +1 -0
- package/dist/{chunk-SM4FZKAZ.mjs → cli/index.js} +1073 -309
- package/dist/cli/index.js.map +1 -0
- package/dist/cli/index.mjs +356 -0
- package/dist/cli/index.mjs.map +1 -0
- package/dist/client/config/from-env.d.ts +188 -0
- package/dist/client/config/from-env.d.ts.map +1 -0
- package/dist/client/config/index.d.ts +2 -0
- package/dist/client/config/index.d.ts.map +1 -0
- package/dist/client/errors.d.ts +67 -0
- package/dist/client/errors.d.ts.map +1 -0
- package/dist/client/kafka.client/admin/ops.d.ts +114 -0
- package/dist/client/kafka.client/admin/ops.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/features/delayed.d.ts +24 -0
- package/dist/client/kafka.client/consumer/features/delayed.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/features/dlq-replay.d.ts +52 -0
- package/dist/client/kafka.client/consumer/features/dlq-replay.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/features/routed.d.ts +4 -0
- package/dist/client/kafka.client/consumer/features/routed.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/features/snapshot.d.ts +10 -0
- package/dist/client/kafka.client/consumer/features/snapshot.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/features/window.d.ts +5 -0
- package/dist/client/kafka.client/consumer/features/window.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/handler.d.ts +163 -0
- package/dist/client/kafka.client/consumer/handler.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/ops.d.ts +64 -0
- package/dist/client/kafka.client/consumer/ops.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/pipeline.d.ts +168 -0
- package/dist/client/kafka.client/consumer/pipeline.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/queue.d.ts +37 -0
- package/dist/client/kafka.client/consumer/queue.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/retry-topic.d.ts +68 -0
- package/dist/client/kafka.client/consumer/retry-topic.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/setup.d.ts +66 -0
- package/dist/client/kafka.client/consumer/setup.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/start.d.ts +7 -0
- package/dist/client/kafka.client/consumer/start.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/stop.d.ts +19 -0
- package/dist/client/kafka.client/consumer/stop.d.ts.map +1 -0
- package/dist/client/kafka.client/consumer/subscribe-retry.d.ts +4 -0
- package/dist/client/kafka.client/consumer/subscribe-retry.d.ts.map +1 -0
- package/dist/client/kafka.client/context.d.ts +75 -0
- package/dist/client/kafka.client/context.d.ts.map +1 -0
- package/dist/client/kafka.client/index.d.ts +155 -0
- package/dist/client/kafka.client/index.d.ts.map +1 -0
- package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts +61 -0
- package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts.map +1 -0
- package/dist/client/kafka.client/infra/dedup.store.d.ts +28 -0
- package/dist/client/kafka.client/infra/dedup.store.d.ts.map +1 -0
- package/dist/client/kafka.client/infra/inflight.tracker.d.ts +22 -0
- package/dist/client/kafka.client/infra/inflight.tracker.d.ts.map +1 -0
- package/dist/client/kafka.client/infra/metrics.manager.d.ts +67 -0
- package/dist/client/kafka.client/infra/metrics.manager.d.ts.map +1 -0
- package/dist/client/kafka.client/producer/lifecycle.d.ts +41 -0
- package/dist/client/kafka.client/producer/lifecycle.d.ts.map +1 -0
- package/dist/client/kafka.client/producer/ops.d.ts +79 -0
- package/dist/client/kafka.client/producer/ops.d.ts.map +1 -0
- package/dist/client/kafka.client/producer/send.d.ts +21 -0
- package/dist/client/kafka.client/producer/send.d.ts.map +1 -0
- package/dist/client/kafka.client/validate-options.d.ts +11 -0
- package/dist/client/kafka.client/validate-options.d.ts.map +1 -0
- package/dist/client/message/envelope.d.ts +105 -0
- package/dist/client/message/envelope.d.ts.map +1 -0
- package/dist/client/message/schema-registry.d.ts +124 -0
- package/dist/client/message/schema-registry.d.ts.map +1 -0
- package/dist/client/message/serde.d.ts +68 -0
- package/dist/client/message/serde.d.ts.map +1 -0
- package/dist/client/message/topic.d.ts +159 -0
- package/dist/client/message/topic.d.ts.map +1 -0
- package/dist/client/message/versioned-schema.d.ts +53 -0
- package/dist/client/message/versioned-schema.d.ts.map +1 -0
- package/dist/client/outbox/index.d.ts +4 -0
- package/dist/client/outbox/index.d.ts.map +1 -0
- package/dist/client/outbox/outbox.relay.d.ts +90 -0
- package/dist/client/outbox/outbox.relay.d.ts.map +1 -0
- package/dist/client/outbox/outbox.store.d.ts +42 -0
- package/dist/client/outbox/outbox.store.d.ts.map +1 -0
- package/dist/client/outbox/outbox.types.d.ts +144 -0
- package/dist/client/outbox/outbox.types.d.ts.map +1 -0
- package/dist/client/security/acl.d.ts +108 -0
- package/dist/client/security/acl.d.ts.map +1 -0
- package/dist/client/security/index.d.ts +5 -0
- package/dist/client/security/index.d.ts.map +1 -0
- package/dist/client/security/providers.d.ts +88 -0
- package/dist/client/security/providers.d.ts.map +1 -0
- package/dist/client/security/resolve-security.d.ts +19 -0
- package/dist/client/security/resolve-security.d.ts.map +1 -0
- package/dist/client/security/security.types.d.ts +76 -0
- package/dist/client/security/security.types.d.ts.map +1 -0
- package/dist/client/transport/confluent.transport.d.ts +32 -0
- package/dist/client/transport/confluent.transport.d.ts.map +1 -0
- package/dist/client/transport/transport.interface.d.ts +221 -0
- package/dist/client/transport/transport.interface.d.ts.map +1 -0
- package/dist/client/types/admin.interface.d.ts +174 -0
- package/dist/client/types/admin.interface.d.ts.map +1 -0
- package/dist/client/types/admin.types.d.ts +140 -0
- package/dist/client/types/admin.types.d.ts.map +1 -0
- package/dist/client/types/client.d.ts +21 -0
- package/dist/client/types/client.d.ts.map +1 -0
- package/dist/client/types/common.d.ts +84 -0
- package/dist/client/types/common.d.ts.map +1 -0
- package/dist/client/types/config.types.d.ts +167 -0
- package/dist/client/types/config.types.d.ts.map +1 -0
- package/dist/client/types/consumer.interface.d.ts +115 -0
- package/dist/client/types/consumer.interface.d.ts.map +1 -0
- package/dist/{consumer.types-fFCag3VJ.d.mts → client/types/consumer.types.d.ts} +62 -383
- package/dist/client/types/consumer.types.d.ts.map +1 -0
- package/dist/client/types/dedup.types.d.ts +50 -0
- package/dist/client/types/dedup.types.d.ts.map +1 -0
- package/dist/client/types/lifecycle.interface.d.ts +72 -0
- package/dist/client/types/lifecycle.interface.d.ts.map +1 -0
- package/dist/client/types/producer.interface.d.ts +52 -0
- package/dist/client/types/producer.interface.d.ts.map +1 -0
- package/dist/client/types/producer.types.d.ts +90 -0
- package/dist/client/types/producer.types.d.ts.map +1 -0
- package/dist/client/types.d.ts +8 -0
- package/dist/client/types.d.ts.map +1 -0
- package/dist/core.d.ts +13 -314
- package/dist/core.d.ts.map +1 -0
- package/dist/core.js +1466 -123
- package/dist/core.js.map +1 -1
- package/dist/core.mjs +45 -3
- package/dist/index.d.ts +7 -128
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1483 -123
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +62 -3
- package/dist/index.mjs.map +1 -1
- package/dist/nest/kafka.constants.d.ts +5 -0
- package/dist/nest/kafka.constants.d.ts.map +1 -0
- package/dist/nest/kafka.decorator.d.ts +49 -0
- package/dist/nest/kafka.decorator.d.ts.map +1 -0
- package/dist/nest/kafka.explorer.d.ts +17 -0
- package/dist/nest/kafka.explorer.d.ts.map +1 -0
- package/dist/nest/kafka.health.d.ts +7 -0
- package/dist/nest/kafka.health.d.ts.map +1 -0
- package/dist/nest/kafka.module.d.ts +61 -0
- package/dist/nest/kafka.module.d.ts.map +1 -0
- package/dist/otel.d.ts +83 -5
- package/dist/otel.d.ts.map +1 -0
- package/dist/otel.js +100 -6
- package/dist/otel.js.map +1 -1
- package/dist/otel.mjs +98 -5
- package/dist/otel.mjs.map +1 -1
- package/dist/serde.d.ts +157 -0
- package/dist/serde.d.ts.map +1 -0
- package/dist/serde.js +308 -0
- package/dist/serde.js.map +1 -0
- package/dist/serde.mjs +158 -0
- package/dist/serde.mjs.map +1 -0
- package/dist/testing/client.mock.d.ts +47 -0
- package/dist/testing/client.mock.d.ts.map +1 -0
- package/dist/testing/index.d.ts +4 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/test.container.d.ts +63 -0
- package/dist/testing/test.container.d.ts.map +1 -0
- package/dist/{testing.d.mts → testing/transport.fake.d.ts} +7 -111
- package/dist/testing/transport.fake.d.ts.map +1 -0
- package/dist/testing.d.ts +2 -318
- package/dist/testing.d.ts.map +1 -0
- package/dist/testing.js +26 -0
- package/dist/testing.js.map +1 -1
- package/dist/testing.mjs +26 -0
- package/dist/testing.mjs.map +1 -1
- package/package.json +40 -8
- package/dist/chunk-SM4FZKAZ.mjs.map +0 -1
- package/dist/client-1irhGEu0.d.mts +0 -751
- package/dist/client-BpFjkHhr.d.ts +0 -751
- package/dist/consumer.types-fFCag3VJ.d.ts +0 -958
- package/dist/core.d.mts +0 -314
- package/dist/index.d.mts +0 -128
- package/dist/otel.d.mts +0 -27
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
import type { KafkaLogger } from "./common";
|
|
2
|
+
import type { KafkaInstrumentation, MessageLostContext, TtlExpiredContext } from "./consumer.types";
|
|
3
|
+
/**
|
|
4
|
+
* Options for `KafkaClient` constructor.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* const kafka = new KafkaClient(kafkaConfig, 'my-service', {
|
|
9
|
+
* transactionalId: `my-service-tx-${replicaIndex}`,
|
|
10
|
+
* lagThrottle: { maxLag: 10_000, pollIntervalMs: 3_000 },
|
|
11
|
+
* clockRecovery: { topics: ['orders.created'] },
|
|
12
|
+
* onMessageLost: (ctx) => alerting.fire('kafka.message-lost', ctx),
|
|
13
|
+
* instrumentation: [otelInstrumentation()],
|
|
14
|
+
* });
|
|
15
|
+
* ```
|
|
16
|
+
*/
|
|
17
|
+
export interface KafkaClientOptions {
|
|
18
|
+
/** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, or `transaction` for each topic. Useful for development — not recommended in production. */
|
|
19
|
+
autoCreateTopics?: boolean;
|
|
20
|
+
/** When `true`, string topic keys are validated against any schema previously registered via a TopicDescriptor. Default: `true`. */
|
|
21
|
+
strictSchemas?: boolean;
|
|
22
|
+
/** Custom logger. Defaults to console with `[KafkaClient:<clientId>]` prefix. */
|
|
23
|
+
logger?: KafkaLogger;
|
|
24
|
+
/** Number of partitions for auto-created topics. Default: `1`. */
|
|
25
|
+
numPartitions?: number;
|
|
26
|
+
/** Client-wide instrumentation hooks (e.g. OTel). Applied to both send and consume paths. */
|
|
27
|
+
instrumentation?: KafkaInstrumentation[];
|
|
28
|
+
/**
|
|
29
|
+
* Pluggable serialization for message payloads. Defaults to `JsonSerde`
|
|
30
|
+
* (`JSON.stringify` / `JSON.parse`), which is byte-identical to the client's
|
|
31
|
+
* historical behaviour.
|
|
32
|
+
*
|
|
33
|
+
* A per-topic override declared via `topic(...).serde(mySerde)` wins over
|
|
34
|
+
* this client-wide serde for that topic. Serde only touches the message
|
|
35
|
+
* value — envelope headers are unaffected.
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* ```ts
|
|
39
|
+
* const kafka = new KafkaClient(id, group, brokers, {
|
|
40
|
+
* serde: new JsonSerde(), // or a custom Avro/Protobuf serde
|
|
41
|
+
* });
|
|
42
|
+
* ```
|
|
43
|
+
*/
|
|
44
|
+
serde?: import("../message/serde").MessageSerde;
|
|
45
|
+
/**
|
|
46
|
+
* Override the transactional producer ID used by `transaction()`.
|
|
47
|
+
* Defaults to `${clientId}-tx`.
|
|
48
|
+
*
|
|
49
|
+
* The transactional ID must be **unique per producer instance** across the
|
|
50
|
+
* entire Kafka cluster. Two `KafkaClient` instances with the same ID will
|
|
51
|
+
* cause Kafka to fence one of the producers — the fenced producer will fail
|
|
52
|
+
* on the next `transaction()` call. Set a distinct value per replica when
|
|
53
|
+
* running multiple instances of the same service.
|
|
54
|
+
*/
|
|
55
|
+
transactionalId?: string;
|
|
56
|
+
/**
|
|
57
|
+
* Called when a message is dropped without being sent to a DLQ.
|
|
58
|
+
* Fires when the handler throws after all retries, or schema validation fails — and `dlq` is not enabled.
|
|
59
|
+
* Use this to alert, log to external systems, or trigger fallback logic.
|
|
60
|
+
*/
|
|
61
|
+
onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
|
|
62
|
+
/**
|
|
63
|
+
* Called when a message is dropped due to TTL expiration (`messageTtlMs`).
|
|
64
|
+
* Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
|
|
65
|
+
* When `dlq: true`, expired messages go to the DLQ and this callback is NOT called.
|
|
66
|
+
*
|
|
67
|
+
* **Client-wide fallback**: if `ConsumerOptions.onTtlExpired` is set on the consumer,
|
|
68
|
+
* it takes precedence over this client-level callback.
|
|
69
|
+
*/
|
|
70
|
+
onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
|
|
71
|
+
/**
|
|
72
|
+
* Called whenever a consumer group rebalance occurs.
|
|
73
|
+
* - `'assign'` — new partitions were granted to this instance.
|
|
74
|
+
* - `'revoke'` — partitions were taken away (e.g. another consumer joined).
|
|
75
|
+
*
|
|
76
|
+
* Applied to every consumer created by this client. If you need per-consumer
|
|
77
|
+
* rebalance handling, use separate `KafkaClient` instances.
|
|
78
|
+
*/
|
|
79
|
+
onRebalance?: (type: "assign" | "revoke", partitions: Array<{
|
|
80
|
+
topic: string;
|
|
81
|
+
partition: number;
|
|
82
|
+
}>) => void;
|
|
83
|
+
/**
|
|
84
|
+
* Recover the Lamport clock from the last message in the given topics on `connectProducer()`.
|
|
85
|
+
*
|
|
86
|
+
* On startup the producer creates a short-lived consumer, seeks each partition to its
|
|
87
|
+
* last message (`highWatermark − 1`), reads the `x-lamport-clock` header, then
|
|
88
|
+
* initialises `_lamportClock` to the maximum value found. This guarantees monotonic
|
|
89
|
+
* clock values across restarts without an external store.
|
|
90
|
+
*
|
|
91
|
+
* Topics that do not exist or are empty are silently skipped.
|
|
92
|
+
*/
|
|
93
|
+
clockRecovery?: {
|
|
94
|
+
/** Topic names to scan for the highest Lamport clock. */
|
|
95
|
+
topics: string[];
|
|
96
|
+
/**
|
|
97
|
+
* Max time to wait for recovery before proceeding with a partial result.
|
|
98
|
+
* Guards against partitions whose last message was compacted or trimmed
|
|
99
|
+
* away between the offset fetch and the seek. Default: `30000`.
|
|
100
|
+
*/
|
|
101
|
+
timeoutMs?: number;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* Delay `sendMessage` / `sendBatch` / `sendTombstone` when the observed lag of a
|
|
105
|
+
* consumer group exceeds `maxLag`. Resumes immediately when lag drops below the threshold.
|
|
106
|
+
*
|
|
107
|
+
* Lag is polled via `getConsumerLag()` every `pollIntervalMs` in the background;
|
|
108
|
+
* no admin call is made on each individual send.
|
|
109
|
+
*
|
|
110
|
+
* When `maxWaitMs` is exceeded the send is unblocked with a warning — this is
|
|
111
|
+
* best-effort throttling, not hard back-pressure.
|
|
112
|
+
*
|
|
113
|
+
* Requires `connectProducer()` to have been called to start the polling loop.
|
|
114
|
+
*/
|
|
115
|
+
lagThrottle?: {
|
|
116
|
+
/** Consumer group whose lag is monitored. Defaults to the client's default group. */
|
|
117
|
+
groupId?: string;
|
|
118
|
+
/** Lag threshold (number of messages) above which sends are delayed. */
|
|
119
|
+
maxLag: number;
|
|
120
|
+
/** How often to poll `getConsumerLag()`. Default: `5000` ms. */
|
|
121
|
+
pollIntervalMs?: number;
|
|
122
|
+
/**
|
|
123
|
+
* Maximum time (ms) a send will wait while throttled before proceeding anyway.
|
|
124
|
+
* Default: `30_000` ms.
|
|
125
|
+
*/
|
|
126
|
+
maxWaitMs?: number;
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* Custom transport implementation.
|
|
130
|
+
*
|
|
131
|
+
* By default `KafkaClient` uses `ConfluentTransport` which wraps
|
|
132
|
+
* `@confluentinc/kafka-javascript` (librdkafka). Inject a different
|
|
133
|
+
* `KafkaTransport` to target an alternative broker library, or to supply
|
|
134
|
+
* a deterministic fake in unit tests without mocking the confluentinc module.
|
|
135
|
+
*
|
|
136
|
+
* @example
|
|
137
|
+
* ```ts
|
|
138
|
+
* // In tests — no jest.mock() needed
|
|
139
|
+
* const kafka = new KafkaClient('svc', 'grp', [], {
|
|
140
|
+
* transport: new FakeTransport(),
|
|
141
|
+
* });
|
|
142
|
+
* ```
|
|
143
|
+
*/
|
|
144
|
+
transport?: import("../transport/transport.interface").KafkaTransport;
|
|
145
|
+
/**
|
|
146
|
+
* Transport security: TLS and SASL authentication.
|
|
147
|
+
*
|
|
148
|
+
* Secure by default without getting in the way:
|
|
149
|
+
* - `sasl` configured with `ssl` unset → TLS is enabled automatically.
|
|
150
|
+
* - No security at all against non-local brokers → a one-time warning
|
|
151
|
+
* (silence with `allowInsecure: true` if intentional).
|
|
152
|
+
*
|
|
153
|
+
* Supports `plain`, `scram-sha-256/512`, and `oauthbearer` — the latter
|
|
154
|
+
* enables AWS MSK IAM (`awsMskIamProvider`) and Google Cloud Managed Kafka
|
|
155
|
+
* (`gcpAccessTokenProvider`).
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* ```ts
|
|
159
|
+
* security: {
|
|
160
|
+
* sasl: { mechanism: 'scram-sha-512', username: 'svc', password: secret },
|
|
161
|
+
* // ssl: true is implied
|
|
162
|
+
* }
|
|
163
|
+
* ```
|
|
164
|
+
*/
|
|
165
|
+
security?: import("../security/security.types").KafkaSecurityOptions;
|
|
166
|
+
}
|
|
167
|
+
//# sourceMappingURL=config.types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.types.d.ts","sourceRoot":"","sources":["../../../src/client/types/config.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IACjC,yKAAyK;IACzK,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oIAAoI;IACpI,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACzC;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,EAAE,OAAO,kBAAkB,EAAE,YAAY,CAAC;IAChD;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,CACZ,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,UAAU,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,KACpD,IAAI,CAAC;IACV;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE;QACd,yDAAyD;QACzD,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB;;;;WAIG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE;QACZ,qFAAqF;QACrF,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,wEAAwE;QACxE,MAAM,EAAE,MAAM,CAAC;QACf,gEAAgE;QAChE,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB;;;WAGG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,OAAO,kCAAkC,EAAE,cAAc,CAAC;IACtE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,EAAE,OAAO,4BAA4B,EAAE,oBAAoB,CAAC;CACtE"}
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
import type { TopicMapConstraint } from "./common";
|
|
2
|
+
import type { ConsumerOptions, ConsumerHandle, BatchMeta, TransactionalHandlerContext, RoutingOptions, WindowConsumerOptions, WindowMeta } from "./consumer.types";
|
|
3
|
+
import type { TopicDescriptor } from "../message/topic";
|
|
4
|
+
import type { EventEnvelope } from "../message/envelope";
|
|
5
|
+
/** Consumer methods of `IKafkaClient`. */
|
|
6
|
+
export interface IKafkaConsumer<T extends TopicMapConstraint<T>> {
|
|
7
|
+
/**
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* const handle = await kafka.startConsumer(['orders.created'], async (envelope) => {
|
|
11
|
+
* await processOrder(envelope.payload);
|
|
12
|
+
* }, { retry: { maxRetries: 3 }, dlq: true });
|
|
13
|
+
*
|
|
14
|
+
* // on shutdown:
|
|
15
|
+
* await handle.stop();
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (envelope: EventEnvelope<T[K[number]]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
19
|
+
startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (envelope: EventEnvelope<D["__type"]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
20
|
+
/**
|
|
21
|
+
* Subscribe using regex topic patterns (or a mix of strings and patterns).
|
|
22
|
+
* Note: type-safety is reduced to the union of all topic payloads when using regex.
|
|
23
|
+
* Incompatible with `retryTopics: true`.
|
|
24
|
+
*/
|
|
25
|
+
startConsumer(topics: (string | RegExp)[], handleMessage: (envelope: EventEnvelope<T[keyof T]>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
26
|
+
/**
|
|
27
|
+
* @example
|
|
28
|
+
* ```ts
|
|
29
|
+
* await kafka.startBatchConsumer(['metrics'], async (envelopes, meta) => {
|
|
30
|
+
* await db.insertMany(envelopes.map(e => e.payload));
|
|
31
|
+
* meta.resolveOffset(envelopes.at(-1)!.offset);
|
|
32
|
+
* }, { autoCommit: false });
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
35
|
+
startBatchConsumer<K extends Array<keyof T>>(topics: K, handleBatch: (envelopes: EventEnvelope<T[K[number]]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
36
|
+
startBatchConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleBatch: (envelopes: EventEnvelope<D["__type"]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
37
|
+
/**
|
|
38
|
+
* Subscribe using regex topic patterns (or a mix of strings and patterns).
|
|
39
|
+
* Note: type-safety is reduced to the union of all topic payloads when using regex.
|
|
40
|
+
* Incompatible with `retryTopics: true`.
|
|
41
|
+
*/
|
|
42
|
+
startBatchConsumer(topics: (string | RegExp)[], handleBatch: (envelopes: EventEnvelope<T[keyof T]>[], meta: BatchMeta) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
43
|
+
/**
|
|
44
|
+
* Subscribe to a topic and accumulate messages into a window, flushing the handler
|
|
45
|
+
* when **either** `maxMessages` messages have accumulated **or** `maxMs` milliseconds
|
|
46
|
+
* have elapsed — whichever fires first. On `handle.stop()`, any remaining buffered
|
|
47
|
+
* messages are flushed before the consumer disconnects.
|
|
48
|
+
*/
|
|
49
|
+
startWindowConsumer<K extends keyof T & string>(topic: K, handler: (batch: EventEnvelope<T[K]>[], meta: WindowMeta) => Promise<void>, options: WindowConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
50
|
+
/**
|
|
51
|
+
* Subscribe to topics and dispatch each message to a handler based on a Kafka header value.
|
|
52
|
+
* Messages whose header is absent or doesn't match any route key are forwarded to `fallback`
|
|
53
|
+
* (or silently skipped when no fallback is set).
|
|
54
|
+
*/
|
|
55
|
+
startRoutedConsumer<K extends Array<keyof T>>(topics: K, routing: RoutingOptions<T[K[number]]>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
56
|
+
/**
|
|
57
|
+
* Subscribe to topics and consume messages with **exactly-once semantics** for
|
|
58
|
+
* read-process-write pipelines. Each message is processed inside a Kafka transaction;
|
|
59
|
+
* on handler success the source offset commit and all staged sends are committed
|
|
60
|
+
* atomically. Incompatible with `retryTopics: true`.
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* ```ts
|
|
64
|
+
* await kafka.startTransactionalConsumer(['orders.created'], async (envelope, tx) => {
|
|
65
|
+
* await tx.send('inventory.reserved', { orderId: envelope.payload.orderId, qty: 1 });
|
|
66
|
+
* });
|
|
67
|
+
* ```
|
|
68
|
+
*/
|
|
69
|
+
startTransactionalConsumer<K extends Array<keyof T>>(topics: K, handler: (envelope: EventEnvelope<T[K[number]]>, tx: TransactionalHandlerContext<T>) => Promise<void>, options?: ConsumerOptions<T>): Promise<ConsumerHandle>;
|
|
70
|
+
/**
|
|
71
|
+
* Stop consumer(s).
|
|
72
|
+
* - `stopConsumer(groupId)` — disconnect and remove the consumer for a specific group.
|
|
73
|
+
* - `stopConsumer()` — disconnect and remove all consumers.
|
|
74
|
+
*/
|
|
75
|
+
stopConsumer(groupId?: string): Promise<void>;
|
|
76
|
+
/**
|
|
77
|
+
* Consume messages as an async iterator. Useful for scripts, migrations, and
|
|
78
|
+
* one-off processing. Breaking out of the loop stops the consumer automatically.
|
|
79
|
+
* Does **not** support `retryTopics: true`.
|
|
80
|
+
*
|
|
81
|
+
* @example
|
|
82
|
+
* ```ts
|
|
83
|
+
* for await (const envelope of kafka.consume('orders')) {
|
|
84
|
+
* await process(envelope);
|
|
85
|
+
* }
|
|
86
|
+
* ```
|
|
87
|
+
*/
|
|
88
|
+
consume<K extends keyof T & string>(topic: K, options?: ConsumerOptions<T>): AsyncIterableIterator<EventEnvelope<T[K]>>;
|
|
89
|
+
/**
|
|
90
|
+
* Pause message delivery for specific topic-partitions. The consumer remains
|
|
91
|
+
* connected; only polling is suspended. Call `resumeConsumer` to restart.
|
|
92
|
+
*
|
|
93
|
+
* @example
|
|
94
|
+
* ```ts
|
|
95
|
+
* kafka.pauseConsumer(undefined, [{ topic: 'orders.created', partitions: [0, 1] }]);
|
|
96
|
+
* ```
|
|
97
|
+
*/
|
|
98
|
+
pauseConsumer(groupId: string | undefined, assignments: Array<{
|
|
99
|
+
topic: string;
|
|
100
|
+
partitions: number[];
|
|
101
|
+
}>): void;
|
|
102
|
+
/**
|
|
103
|
+
* Resume message delivery for previously paused topic-partitions.
|
|
104
|
+
*
|
|
105
|
+
* @example
|
|
106
|
+
* ```ts
|
|
107
|
+
* kafka.resumeConsumer(undefined, [{ topic: 'orders.created', partitions: [0, 1] }]);
|
|
108
|
+
* ```
|
|
109
|
+
*/
|
|
110
|
+
resumeConsumer(groupId: string | undefined, assignments: Array<{
|
|
111
|
+
topic: string;
|
|
112
|
+
partitions: number[];
|
|
113
|
+
}>): void;
|
|
114
|
+
}
|
|
115
|
+
//# sourceMappingURL=consumer.interface.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"consumer.interface.d.ts","sourceRoot":"","sources":["../../../src/client/types/consumer.interface.ts"],"names":[],"mappings":"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"}
|