@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.
Files changed (180) hide show
  1. package/README.md +693 -8
  2. package/dist/chunk-OR7TPAAE.mjs +4760 -0
  3. package/dist/chunk-OR7TPAAE.mjs.map +1 -0
  4. package/dist/chunk-PQVBRDNV.mjs +149 -0
  5. package/dist/chunk-PQVBRDNV.mjs.map +1 -0
  6. package/dist/cli/dlq.d.ts +119 -0
  7. package/dist/cli/dlq.d.ts.map +1 -0
  8. package/dist/cli/index.d.ts +3 -0
  9. package/dist/cli/index.d.ts.map +1 -0
  10. package/dist/{chunk-SM4FZKAZ.mjs → cli/index.js} +1073 -309
  11. package/dist/cli/index.js.map +1 -0
  12. package/dist/cli/index.mjs +356 -0
  13. package/dist/cli/index.mjs.map +1 -0
  14. package/dist/client/config/from-env.d.ts +188 -0
  15. package/dist/client/config/from-env.d.ts.map +1 -0
  16. package/dist/client/config/index.d.ts +2 -0
  17. package/dist/client/config/index.d.ts.map +1 -0
  18. package/dist/client/errors.d.ts +67 -0
  19. package/dist/client/errors.d.ts.map +1 -0
  20. package/dist/client/kafka.client/admin/ops.d.ts +114 -0
  21. package/dist/client/kafka.client/admin/ops.d.ts.map +1 -0
  22. package/dist/client/kafka.client/consumer/features/delayed.d.ts +24 -0
  23. package/dist/client/kafka.client/consumer/features/delayed.d.ts.map +1 -0
  24. package/dist/client/kafka.client/consumer/features/dlq-replay.d.ts +52 -0
  25. package/dist/client/kafka.client/consumer/features/dlq-replay.d.ts.map +1 -0
  26. package/dist/client/kafka.client/consumer/features/routed.d.ts +4 -0
  27. package/dist/client/kafka.client/consumer/features/routed.d.ts.map +1 -0
  28. package/dist/client/kafka.client/consumer/features/snapshot.d.ts +10 -0
  29. package/dist/client/kafka.client/consumer/features/snapshot.d.ts.map +1 -0
  30. package/dist/client/kafka.client/consumer/features/window.d.ts +5 -0
  31. package/dist/client/kafka.client/consumer/features/window.d.ts.map +1 -0
  32. package/dist/client/kafka.client/consumer/handler.d.ts +163 -0
  33. package/dist/client/kafka.client/consumer/handler.d.ts.map +1 -0
  34. package/dist/client/kafka.client/consumer/ops.d.ts +64 -0
  35. package/dist/client/kafka.client/consumer/ops.d.ts.map +1 -0
  36. package/dist/client/kafka.client/consumer/pipeline.d.ts +168 -0
  37. package/dist/client/kafka.client/consumer/pipeline.d.ts.map +1 -0
  38. package/dist/client/kafka.client/consumer/queue.d.ts +37 -0
  39. package/dist/client/kafka.client/consumer/queue.d.ts.map +1 -0
  40. package/dist/client/kafka.client/consumer/retry-topic.d.ts +68 -0
  41. package/dist/client/kafka.client/consumer/retry-topic.d.ts.map +1 -0
  42. package/dist/client/kafka.client/consumer/setup.d.ts +66 -0
  43. package/dist/client/kafka.client/consumer/setup.d.ts.map +1 -0
  44. package/dist/client/kafka.client/consumer/start.d.ts +7 -0
  45. package/dist/client/kafka.client/consumer/start.d.ts.map +1 -0
  46. package/dist/client/kafka.client/consumer/stop.d.ts +19 -0
  47. package/dist/client/kafka.client/consumer/stop.d.ts.map +1 -0
  48. package/dist/client/kafka.client/consumer/subscribe-retry.d.ts +4 -0
  49. package/dist/client/kafka.client/consumer/subscribe-retry.d.ts.map +1 -0
  50. package/dist/client/kafka.client/context.d.ts +75 -0
  51. package/dist/client/kafka.client/context.d.ts.map +1 -0
  52. package/dist/client/kafka.client/index.d.ts +155 -0
  53. package/dist/client/kafka.client/index.d.ts.map +1 -0
  54. package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts +61 -0
  55. package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts.map +1 -0
  56. package/dist/client/kafka.client/infra/dedup.store.d.ts +28 -0
  57. package/dist/client/kafka.client/infra/dedup.store.d.ts.map +1 -0
  58. package/dist/client/kafka.client/infra/inflight.tracker.d.ts +22 -0
  59. package/dist/client/kafka.client/infra/inflight.tracker.d.ts.map +1 -0
  60. package/dist/client/kafka.client/infra/metrics.manager.d.ts +67 -0
  61. package/dist/client/kafka.client/infra/metrics.manager.d.ts.map +1 -0
  62. package/dist/client/kafka.client/producer/lifecycle.d.ts +41 -0
  63. package/dist/client/kafka.client/producer/lifecycle.d.ts.map +1 -0
  64. package/dist/client/kafka.client/producer/ops.d.ts +79 -0
  65. package/dist/client/kafka.client/producer/ops.d.ts.map +1 -0
  66. package/dist/client/kafka.client/producer/send.d.ts +21 -0
  67. package/dist/client/kafka.client/producer/send.d.ts.map +1 -0
  68. package/dist/client/kafka.client/validate-options.d.ts +11 -0
  69. package/dist/client/kafka.client/validate-options.d.ts.map +1 -0
  70. package/dist/client/message/envelope.d.ts +105 -0
  71. package/dist/client/message/envelope.d.ts.map +1 -0
  72. package/dist/client/message/schema-registry.d.ts +124 -0
  73. package/dist/client/message/schema-registry.d.ts.map +1 -0
  74. package/dist/client/message/serde.d.ts +68 -0
  75. package/dist/client/message/serde.d.ts.map +1 -0
  76. package/dist/client/message/topic.d.ts +159 -0
  77. package/dist/client/message/topic.d.ts.map +1 -0
  78. package/dist/client/message/versioned-schema.d.ts +53 -0
  79. package/dist/client/message/versioned-schema.d.ts.map +1 -0
  80. package/dist/client/outbox/index.d.ts +4 -0
  81. package/dist/client/outbox/index.d.ts.map +1 -0
  82. package/dist/client/outbox/outbox.relay.d.ts +90 -0
  83. package/dist/client/outbox/outbox.relay.d.ts.map +1 -0
  84. package/dist/client/outbox/outbox.store.d.ts +42 -0
  85. package/dist/client/outbox/outbox.store.d.ts.map +1 -0
  86. package/dist/client/outbox/outbox.types.d.ts +144 -0
  87. package/dist/client/outbox/outbox.types.d.ts.map +1 -0
  88. package/dist/client/security/acl.d.ts +108 -0
  89. package/dist/client/security/acl.d.ts.map +1 -0
  90. package/dist/client/security/index.d.ts +5 -0
  91. package/dist/client/security/index.d.ts.map +1 -0
  92. package/dist/client/security/providers.d.ts +88 -0
  93. package/dist/client/security/providers.d.ts.map +1 -0
  94. package/dist/client/security/resolve-security.d.ts +19 -0
  95. package/dist/client/security/resolve-security.d.ts.map +1 -0
  96. package/dist/client/security/security.types.d.ts +76 -0
  97. package/dist/client/security/security.types.d.ts.map +1 -0
  98. package/dist/client/transport/confluent.transport.d.ts +32 -0
  99. package/dist/client/transport/confluent.transport.d.ts.map +1 -0
  100. package/dist/client/transport/transport.interface.d.ts +221 -0
  101. package/dist/client/transport/transport.interface.d.ts.map +1 -0
  102. package/dist/client/types/admin.interface.d.ts +174 -0
  103. package/dist/client/types/admin.interface.d.ts.map +1 -0
  104. package/dist/client/types/admin.types.d.ts +140 -0
  105. package/dist/client/types/admin.types.d.ts.map +1 -0
  106. package/dist/client/types/client.d.ts +21 -0
  107. package/dist/client/types/client.d.ts.map +1 -0
  108. package/dist/client/types/common.d.ts +84 -0
  109. package/dist/client/types/common.d.ts.map +1 -0
  110. package/dist/client/types/config.types.d.ts +167 -0
  111. package/dist/client/types/config.types.d.ts.map +1 -0
  112. package/dist/client/types/consumer.interface.d.ts +115 -0
  113. package/dist/client/types/consumer.interface.d.ts.map +1 -0
  114. package/dist/{consumer.types-fFCag3VJ.d.mts → client/types/consumer.types.d.ts} +62 -383
  115. package/dist/client/types/consumer.types.d.ts.map +1 -0
  116. package/dist/client/types/dedup.types.d.ts +50 -0
  117. package/dist/client/types/dedup.types.d.ts.map +1 -0
  118. package/dist/client/types/lifecycle.interface.d.ts +72 -0
  119. package/dist/client/types/lifecycle.interface.d.ts.map +1 -0
  120. package/dist/client/types/producer.interface.d.ts +52 -0
  121. package/dist/client/types/producer.interface.d.ts.map +1 -0
  122. package/dist/client/types/producer.types.d.ts +90 -0
  123. package/dist/client/types/producer.types.d.ts.map +1 -0
  124. package/dist/client/types.d.ts +8 -0
  125. package/dist/client/types.d.ts.map +1 -0
  126. package/dist/core.d.ts +13 -314
  127. package/dist/core.d.ts.map +1 -0
  128. package/dist/core.js +1466 -123
  129. package/dist/core.js.map +1 -1
  130. package/dist/core.mjs +45 -3
  131. package/dist/index.d.ts +7 -128
  132. package/dist/index.d.ts.map +1 -0
  133. package/dist/index.js +1483 -123
  134. package/dist/index.js.map +1 -1
  135. package/dist/index.mjs +62 -3
  136. package/dist/index.mjs.map +1 -1
  137. package/dist/nest/kafka.constants.d.ts +5 -0
  138. package/dist/nest/kafka.constants.d.ts.map +1 -0
  139. package/dist/nest/kafka.decorator.d.ts +49 -0
  140. package/dist/nest/kafka.decorator.d.ts.map +1 -0
  141. package/dist/nest/kafka.explorer.d.ts +17 -0
  142. package/dist/nest/kafka.explorer.d.ts.map +1 -0
  143. package/dist/nest/kafka.health.d.ts +7 -0
  144. package/dist/nest/kafka.health.d.ts.map +1 -0
  145. package/dist/nest/kafka.module.d.ts +61 -0
  146. package/dist/nest/kafka.module.d.ts.map +1 -0
  147. package/dist/otel.d.ts +83 -5
  148. package/dist/otel.d.ts.map +1 -0
  149. package/dist/otel.js +100 -6
  150. package/dist/otel.js.map +1 -1
  151. package/dist/otel.mjs +98 -5
  152. package/dist/otel.mjs.map +1 -1
  153. package/dist/serde.d.ts +157 -0
  154. package/dist/serde.d.ts.map +1 -0
  155. package/dist/serde.js +308 -0
  156. package/dist/serde.js.map +1 -0
  157. package/dist/serde.mjs +158 -0
  158. package/dist/serde.mjs.map +1 -0
  159. package/dist/testing/client.mock.d.ts +47 -0
  160. package/dist/testing/client.mock.d.ts.map +1 -0
  161. package/dist/testing/index.d.ts +4 -0
  162. package/dist/testing/index.d.ts.map +1 -0
  163. package/dist/testing/test.container.d.ts +63 -0
  164. package/dist/testing/test.container.d.ts.map +1 -0
  165. package/dist/{testing.d.mts → testing/transport.fake.d.ts} +7 -111
  166. package/dist/testing/transport.fake.d.ts.map +1 -0
  167. package/dist/testing.d.ts +2 -318
  168. package/dist/testing.d.ts.map +1 -0
  169. package/dist/testing.js +26 -0
  170. package/dist/testing.js.map +1 -1
  171. package/dist/testing.mjs +26 -0
  172. package/dist/testing.mjs.map +1 -1
  173. package/package.json +40 -8
  174. package/dist/chunk-SM4FZKAZ.mjs.map +0 -1
  175. package/dist/client-1irhGEu0.d.mts +0 -751
  176. package/dist/client-BpFjkHhr.d.ts +0 -751
  177. package/dist/consumer.types-fFCag3VJ.d.ts +0 -958
  178. package/dist/core.d.mts +0 -314
  179. package/dist/index.d.mts +0 -128
  180. 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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"}