@drarzter/kafka-client 0.9.3 → 0.10.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 (170) hide show
  1. package/README.md +625 -8
  2. package/dist/chunk-CMO7SMVK.mjs +4814 -0
  3. package/dist/chunk-CMO7SMVK.mjs.map +1 -0
  4. package/dist/cli/dlq.d.ts +119 -0
  5. package/dist/cli/dlq.d.ts.map +1 -0
  6. package/dist/cli/index.d.ts +3 -0
  7. package/dist/cli/index.d.ts.map +1 -0
  8. package/dist/{chunk-TPIP5VV7.mjs → cli/index.js} +965 -265
  9. package/dist/cli/index.js.map +1 -0
  10. package/dist/cli/index.mjs +355 -0
  11. package/dist/cli/index.mjs.map +1 -0
  12. package/dist/client/config/from-env.d.ts +188 -0
  13. package/dist/client/config/from-env.d.ts.map +1 -0
  14. package/dist/client/config/index.d.ts +2 -0
  15. package/dist/client/config/index.d.ts.map +1 -0
  16. package/dist/client/errors.d.ts +67 -0
  17. package/dist/client/errors.d.ts.map +1 -0
  18. package/dist/client/kafka.client/admin/ops.d.ts +114 -0
  19. package/dist/client/kafka.client/admin/ops.d.ts.map +1 -0
  20. package/dist/client/kafka.client/consumer/features/delayed.d.ts +24 -0
  21. package/dist/client/kafka.client/consumer/features/delayed.d.ts.map +1 -0
  22. package/dist/client/kafka.client/consumer/features/dlq-replay.d.ts +52 -0
  23. package/dist/client/kafka.client/consumer/features/dlq-replay.d.ts.map +1 -0
  24. package/dist/client/kafka.client/consumer/features/routed.d.ts +4 -0
  25. package/dist/client/kafka.client/consumer/features/routed.d.ts.map +1 -0
  26. package/dist/client/kafka.client/consumer/features/snapshot.d.ts +10 -0
  27. package/dist/client/kafka.client/consumer/features/snapshot.d.ts.map +1 -0
  28. package/dist/client/kafka.client/consumer/features/window.d.ts +5 -0
  29. package/dist/client/kafka.client/consumer/features/window.d.ts.map +1 -0
  30. package/dist/client/kafka.client/consumer/handler.d.ts +149 -0
  31. package/dist/client/kafka.client/consumer/handler.d.ts.map +1 -0
  32. package/dist/client/kafka.client/consumer/ops.d.ts +51 -0
  33. package/dist/client/kafka.client/consumer/ops.d.ts.map +1 -0
  34. package/dist/client/kafka.client/consumer/pipeline.d.ts +167 -0
  35. package/dist/client/kafka.client/consumer/pipeline.d.ts.map +1 -0
  36. package/dist/client/kafka.client/consumer/queue.d.ts +37 -0
  37. package/dist/client/kafka.client/consumer/queue.d.ts.map +1 -0
  38. package/dist/client/kafka.client/consumer/retry-topic.d.ts +65 -0
  39. package/dist/client/kafka.client/consumer/retry-topic.d.ts.map +1 -0
  40. package/dist/client/kafka.client/consumer/setup.d.ts +63 -0
  41. package/dist/client/kafka.client/consumer/setup.d.ts.map +1 -0
  42. package/dist/client/kafka.client/consumer/start.d.ts +7 -0
  43. package/dist/client/kafka.client/consumer/start.d.ts.map +1 -0
  44. package/dist/client/kafka.client/consumer/stop.d.ts +19 -0
  45. package/dist/client/kafka.client/consumer/stop.d.ts.map +1 -0
  46. package/dist/client/kafka.client/consumer/subscribe-retry.d.ts +4 -0
  47. package/dist/client/kafka.client/consumer/subscribe-retry.d.ts.map +1 -0
  48. package/dist/client/kafka.client/context.d.ts +72 -0
  49. package/dist/client/kafka.client/context.d.ts.map +1 -0
  50. package/dist/client/kafka.client/index.d.ts +155 -0
  51. package/dist/client/kafka.client/index.d.ts.map +1 -0
  52. package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts +61 -0
  53. package/dist/client/kafka.client/infra/circuit-breaker.manager.d.ts.map +1 -0
  54. package/dist/client/kafka.client/infra/dedup.store.d.ts +28 -0
  55. package/dist/client/kafka.client/infra/dedup.store.d.ts.map +1 -0
  56. package/dist/client/kafka.client/infra/inflight.tracker.d.ts +22 -0
  57. package/dist/client/kafka.client/infra/inflight.tracker.d.ts.map +1 -0
  58. package/dist/client/kafka.client/infra/metrics.manager.d.ts +67 -0
  59. package/dist/client/kafka.client/infra/metrics.manager.d.ts.map +1 -0
  60. package/dist/client/kafka.client/producer/lifecycle.d.ts +41 -0
  61. package/dist/client/kafka.client/producer/lifecycle.d.ts.map +1 -0
  62. package/dist/client/kafka.client/producer/ops.d.ts +70 -0
  63. package/dist/client/kafka.client/producer/ops.d.ts.map +1 -0
  64. package/dist/client/kafka.client/producer/send.d.ts +21 -0
  65. package/dist/client/kafka.client/producer/send.d.ts.map +1 -0
  66. package/dist/client/kafka.client/validate-options.d.ts +11 -0
  67. package/dist/client/kafka.client/validate-options.d.ts.map +1 -0
  68. package/dist/client/message/envelope.d.ts +105 -0
  69. package/dist/client/message/envelope.d.ts.map +1 -0
  70. package/dist/client/message/schema-registry.d.ts +105 -0
  71. package/dist/client/message/schema-registry.d.ts.map +1 -0
  72. package/dist/client/message/topic.d.ts +138 -0
  73. package/dist/client/message/topic.d.ts.map +1 -0
  74. package/dist/client/message/versioned-schema.d.ts +53 -0
  75. package/dist/client/message/versioned-schema.d.ts.map +1 -0
  76. package/dist/client/outbox/index.d.ts +4 -0
  77. package/dist/client/outbox/index.d.ts.map +1 -0
  78. package/dist/client/outbox/outbox.relay.d.ts +90 -0
  79. package/dist/client/outbox/outbox.relay.d.ts.map +1 -0
  80. package/dist/client/outbox/outbox.store.d.ts +42 -0
  81. package/dist/client/outbox/outbox.store.d.ts.map +1 -0
  82. package/dist/client/outbox/outbox.types.d.ts +144 -0
  83. package/dist/client/outbox/outbox.types.d.ts.map +1 -0
  84. package/dist/client/security/acl.d.ts +108 -0
  85. package/dist/client/security/acl.d.ts.map +1 -0
  86. package/dist/client/security/index.d.ts +5 -0
  87. package/dist/client/security/index.d.ts.map +1 -0
  88. package/dist/client/security/providers.d.ts +88 -0
  89. package/dist/client/security/providers.d.ts.map +1 -0
  90. package/dist/client/security/resolve-security.d.ts +19 -0
  91. package/dist/client/security/resolve-security.d.ts.map +1 -0
  92. package/dist/client/security/security.types.d.ts +76 -0
  93. package/dist/client/security/security.types.d.ts.map +1 -0
  94. package/dist/client/transport/confluent.transport.d.ts +32 -0
  95. package/dist/client/transport/confluent.transport.d.ts.map +1 -0
  96. package/dist/client/transport/transport.interface.d.ts +216 -0
  97. package/dist/client/transport/transport.interface.d.ts.map +1 -0
  98. package/dist/client/types/admin.interface.d.ts +174 -0
  99. package/dist/client/types/admin.interface.d.ts.map +1 -0
  100. package/dist/client/types/admin.types.d.ts +140 -0
  101. package/dist/client/types/admin.types.d.ts.map +1 -0
  102. package/dist/client/types/client.d.ts +21 -0
  103. package/dist/client/types/client.d.ts.map +1 -0
  104. package/dist/client/types/common.d.ts +84 -0
  105. package/dist/client/types/common.d.ts.map +1 -0
  106. package/dist/client/types/config.types.d.ts +150 -0
  107. package/dist/client/types/config.types.d.ts.map +1 -0
  108. package/dist/client/types/consumer.interface.d.ts +115 -0
  109. package/dist/client/types/consumer.interface.d.ts.map +1 -0
  110. package/dist/{consumer.types-fFCag3VJ.d.mts → client/types/consumer.types.d.ts} +62 -383
  111. package/dist/client/types/consumer.types.d.ts.map +1 -0
  112. package/dist/client/types/dedup.types.d.ts +50 -0
  113. package/dist/client/types/dedup.types.d.ts.map +1 -0
  114. package/dist/client/types/lifecycle.interface.d.ts +72 -0
  115. package/dist/client/types/lifecycle.interface.d.ts.map +1 -0
  116. package/dist/client/types/producer.interface.d.ts +52 -0
  117. package/dist/client/types/producer.interface.d.ts.map +1 -0
  118. package/dist/client/types/producer.types.d.ts +90 -0
  119. package/dist/client/types/producer.types.d.ts.map +1 -0
  120. package/dist/client/types.d.ts +8 -0
  121. package/dist/client/types.d.ts.map +1 -0
  122. package/dist/core.d.ts +10 -314
  123. package/dist/core.d.ts.map +1 -0
  124. package/dist/core.js +1326 -74
  125. package/dist/core.js.map +1 -1
  126. package/dist/core.mjs +39 -3
  127. package/dist/index.d.ts +7 -128
  128. package/dist/index.d.ts.map +1 -0
  129. package/dist/index.js +1343 -74
  130. package/dist/index.js.map +1 -1
  131. package/dist/index.mjs +56 -3
  132. package/dist/index.mjs.map +1 -1
  133. package/dist/nest/kafka.constants.d.ts +5 -0
  134. package/dist/nest/kafka.constants.d.ts.map +1 -0
  135. package/dist/nest/kafka.decorator.d.ts +49 -0
  136. package/dist/nest/kafka.decorator.d.ts.map +1 -0
  137. package/dist/nest/kafka.explorer.d.ts +17 -0
  138. package/dist/nest/kafka.explorer.d.ts.map +1 -0
  139. package/dist/nest/kafka.health.d.ts +7 -0
  140. package/dist/nest/kafka.health.d.ts.map +1 -0
  141. package/dist/nest/kafka.module.d.ts +61 -0
  142. package/dist/nest/kafka.module.d.ts.map +1 -0
  143. package/dist/otel.d.ts +83 -5
  144. package/dist/otel.d.ts.map +1 -0
  145. package/dist/otel.js +100 -6
  146. package/dist/otel.js.map +1 -1
  147. package/dist/otel.mjs +98 -5
  148. package/dist/otel.mjs.map +1 -1
  149. package/dist/testing/client.mock.d.ts +47 -0
  150. package/dist/testing/client.mock.d.ts.map +1 -0
  151. package/dist/testing/index.d.ts +4 -0
  152. package/dist/testing/index.d.ts.map +1 -0
  153. package/dist/testing/test.container.d.ts +63 -0
  154. package/dist/testing/test.container.d.ts.map +1 -0
  155. package/dist/{testing.d.mts → testing/transport.fake.d.ts} +7 -111
  156. package/dist/testing/transport.fake.d.ts.map +1 -0
  157. package/dist/testing.d.ts +2 -318
  158. package/dist/testing.d.ts.map +1 -0
  159. package/dist/testing.js +28 -2
  160. package/dist/testing.js.map +1 -1
  161. package/dist/testing.mjs +28 -2
  162. package/dist/testing.mjs.map +1 -1
  163. package/package.json +22 -9
  164. package/dist/chunk-TPIP5VV7.mjs.map +0 -1
  165. package/dist/client-CBBUDDtu.d.ts +0 -751
  166. package/dist/client-D-SxYV2b.d.mts +0 -751
  167. package/dist/consumer.types-fFCag3VJ.d.ts +0 -958
  168. package/dist/core.d.mts +0 -314
  169. package/dist/index.d.mts +0 -128
  170. package/dist/otel.d.mts +0 -27
@@ -0,0 +1,150 @@
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
+ * Override the transactional producer ID used by `transaction()`.
30
+ * Defaults to `${clientId}-tx`.
31
+ *
32
+ * The transactional ID must be **unique per producer instance** across the
33
+ * entire Kafka cluster. Two `KafkaClient` instances with the same ID will
34
+ * cause Kafka to fence one of the producers — the fenced producer will fail
35
+ * on the next `transaction()` call. Set a distinct value per replica when
36
+ * running multiple instances of the same service.
37
+ */
38
+ transactionalId?: string;
39
+ /**
40
+ * Called when a message is dropped without being sent to a DLQ.
41
+ * Fires when the handler throws after all retries, or schema validation fails — and `dlq` is not enabled.
42
+ * Use this to alert, log to external systems, or trigger fallback logic.
43
+ */
44
+ onMessageLost?: (ctx: MessageLostContext) => void | Promise<void>;
45
+ /**
46
+ * Called when a message is dropped due to TTL expiration (`messageTtlMs`).
47
+ * Fires instead of `onMessageLost` for expired messages when `dlq` is not enabled.
48
+ * When `dlq: true`, expired messages go to the DLQ and this callback is NOT called.
49
+ *
50
+ * **Client-wide fallback**: if `ConsumerOptions.onTtlExpired` is set on the consumer,
51
+ * it takes precedence over this client-level callback.
52
+ */
53
+ onTtlExpired?: (ctx: TtlExpiredContext) => void | Promise<void>;
54
+ /**
55
+ * Called whenever a consumer group rebalance occurs.
56
+ * - `'assign'` — new partitions were granted to this instance.
57
+ * - `'revoke'` — partitions were taken away (e.g. another consumer joined).
58
+ *
59
+ * Applied to every consumer created by this client. If you need per-consumer
60
+ * rebalance handling, use separate `KafkaClient` instances.
61
+ */
62
+ onRebalance?: (type: "assign" | "revoke", partitions: Array<{
63
+ topic: string;
64
+ partition: number;
65
+ }>) => void;
66
+ /**
67
+ * Recover the Lamport clock from the last message in the given topics on `connectProducer()`.
68
+ *
69
+ * On startup the producer creates a short-lived consumer, seeks each partition to its
70
+ * last message (`highWatermark − 1`), reads the `x-lamport-clock` header, then
71
+ * initialises `_lamportClock` to the maximum value found. This guarantees monotonic
72
+ * clock values across restarts without an external store.
73
+ *
74
+ * Topics that do not exist or are empty are silently skipped.
75
+ */
76
+ clockRecovery?: {
77
+ /** Topic names to scan for the highest Lamport clock. */
78
+ topics: string[];
79
+ /**
80
+ * Max time to wait for recovery before proceeding with a partial result.
81
+ * Guards against partitions whose last message was compacted or trimmed
82
+ * away between the offset fetch and the seek. Default: `30000`.
83
+ */
84
+ timeoutMs?: number;
85
+ };
86
+ /**
87
+ * Delay `sendMessage` / `sendBatch` / `sendTombstone` when the observed lag of a
88
+ * consumer group exceeds `maxLag`. Resumes immediately when lag drops below the threshold.
89
+ *
90
+ * Lag is polled via `getConsumerLag()` every `pollIntervalMs` in the background;
91
+ * no admin call is made on each individual send.
92
+ *
93
+ * When `maxWaitMs` is exceeded the send is unblocked with a warning — this is
94
+ * best-effort throttling, not hard back-pressure.
95
+ *
96
+ * Requires `connectProducer()` to have been called to start the polling loop.
97
+ */
98
+ lagThrottle?: {
99
+ /** Consumer group whose lag is monitored. Defaults to the client's default group. */
100
+ groupId?: string;
101
+ /** Lag threshold (number of messages) above which sends are delayed. */
102
+ maxLag: number;
103
+ /** How often to poll `getConsumerLag()`. Default: `5000` ms. */
104
+ pollIntervalMs?: number;
105
+ /**
106
+ * Maximum time (ms) a send will wait while throttled before proceeding anyway.
107
+ * Default: `30_000` ms.
108
+ */
109
+ maxWaitMs?: number;
110
+ };
111
+ /**
112
+ * Custom transport implementation.
113
+ *
114
+ * By default `KafkaClient` uses `ConfluentTransport` which wraps
115
+ * `@confluentinc/kafka-javascript` (librdkafka). Inject a different
116
+ * `KafkaTransport` to target an alternative broker library, or to supply
117
+ * a deterministic fake in unit tests without mocking the confluentinc module.
118
+ *
119
+ * @example
120
+ * ```ts
121
+ * // In tests — no jest.mock() needed
122
+ * const kafka = new KafkaClient('svc', 'grp', [], {
123
+ * transport: new FakeTransport(),
124
+ * });
125
+ * ```
126
+ */
127
+ transport?: import("../transport/transport.interface").KafkaTransport;
128
+ /**
129
+ * Transport security: TLS and SASL authentication.
130
+ *
131
+ * Secure by default without getting in the way:
132
+ * - `sasl` configured with `ssl` unset → TLS is enabled automatically.
133
+ * - No security at all against non-local brokers → a one-time warning
134
+ * (silence with `allowInsecure: true` if intentional).
135
+ *
136
+ * Supports `plain`, `scram-sha-256/512`, and `oauthbearer` — the latter
137
+ * enables AWS MSK IAM (`awsMskIamProvider`) and Google Cloud Managed Kafka
138
+ * (`gcpAccessTokenProvider`).
139
+ *
140
+ * @example
141
+ * ```ts
142
+ * security: {
143
+ * sasl: { mechanism: 'scram-sha-512', username: 'svc', password: secret },
144
+ * // ssl: true is implied
145
+ * }
146
+ * ```
147
+ */
148
+ security?: import("../security/security.types").KafkaSecurityOptions;
149
+ }
150
+ //# 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;;;;;;;;;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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"}