@drarzter/kafka-client 0.5.5 → 0.5.7
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 +33 -17
- package/dist/chunk-TD2AE774.mjs +1231 -0
- package/dist/chunk-TD2AE774.mjs.map +1 -0
- package/dist/core.d.mts +14 -41
- package/dist/core.d.ts +14 -41
- package/dist/core.js +652 -511
- package/dist/core.js.map +1 -1
- package/dist/core.mjs +1 -1
- package/dist/index.d.mts +17 -23
- package/dist/index.d.ts +17 -23
- package/dist/index.js +692 -569
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +41 -59
- package/dist/index.mjs.map +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/otel.d.ts +1 -1
- package/dist/otel.js +9 -4
- package/dist/otel.js.map +1 -1
- package/dist/otel.mjs +9 -4
- package/dist/otel.mjs.map +1 -1
- package/dist/testing.d.mts +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +6 -6
- package/dist/testing.js.map +1 -1
- package/dist/testing.mjs +6 -6
- package/dist/testing.mjs.map +1 -1
- package/dist/{envelope-BpyKN_WL.d.mts → types-DwERZ6ql.d.mts} +99 -83
- package/dist/{envelope-BpyKN_WL.d.ts → types-DwERZ6ql.d.ts} +99 -83
- package/package.json +1 -1
- package/dist/chunk-Z3O5GTS7.mjs +0 -1090
- package/dist/chunk-Z3O5GTS7.mjs.map +0 -1
|
@@ -32,8 +32,8 @@ interface TopicDescriptor<N extends string = string, M extends Record<string, an
|
|
|
32
32
|
*
|
|
33
33
|
* @example
|
|
34
34
|
* ```ts
|
|
35
|
-
* // Without schema — type
|
|
36
|
-
* const OrderCreated = topic('order.created')<{ orderId: string; amount: number }>();
|
|
35
|
+
* // Without schema — explicit type via .type<T>():
|
|
36
|
+
* const OrderCreated = topic('order.created').type<{ orderId: string; amount: number }>();
|
|
37
37
|
*
|
|
38
38
|
* // With schema — type inferred from schema:
|
|
39
39
|
* const OrderCreated = topic('order.created').schema(z.object({
|
|
@@ -50,16 +50,17 @@ interface TopicDescriptor<N extends string = string, M extends Record<string, an
|
|
|
50
50
|
* ```
|
|
51
51
|
*/
|
|
52
52
|
declare function topic<N extends string>(name: N): {
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
/** Provide an explicit message type without a runtime schema. */
|
|
54
|
+
type: <M extends Record<string, any>>() => TopicDescriptor<N, M>;
|
|
55
|
+
schema: <S extends SchemaLike<Record<string, any>>>(schema: S) => TopicDescriptor<N, InferSchema<S>>;
|
|
55
56
|
};
|
|
56
57
|
/**
|
|
57
58
|
* Build a topic-message map type from a union of TopicDescriptors.
|
|
58
59
|
*
|
|
59
60
|
* @example
|
|
60
61
|
* ```ts
|
|
61
|
-
* const OrderCreated = topic('order.created')<{ orderId: string }>();
|
|
62
|
-
* const OrderCompleted = topic('order.completed')<{ completedAt: string }>();
|
|
62
|
+
* const OrderCreated = topic('order.created').type<{ orderId: string }>();
|
|
63
|
+
* const OrderCompleted = topic('order.completed').type<{ completedAt: string }>();
|
|
63
64
|
*
|
|
64
65
|
* type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
|
|
65
66
|
* // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
|
|
@@ -69,6 +70,77 @@ type TopicsFrom<D extends TopicDescriptor<any, any>> = {
|
|
|
69
70
|
[K in D as K["__topic"]]: K["__type"];
|
|
70
71
|
};
|
|
71
72
|
|
|
73
|
+
declare const HEADER_EVENT_ID = "x-event-id";
|
|
74
|
+
declare const HEADER_CORRELATION_ID = "x-correlation-id";
|
|
75
|
+
declare const HEADER_TIMESTAMP = "x-timestamp";
|
|
76
|
+
declare const HEADER_SCHEMA_VERSION = "x-schema-version";
|
|
77
|
+
declare const HEADER_TRACEPARENT = "traceparent";
|
|
78
|
+
/**
|
|
79
|
+
* Typed wrapper combining a parsed message payload with Kafka metadata
|
|
80
|
+
* and envelope headers.
|
|
81
|
+
*
|
|
82
|
+
* On **send**, the library auto-generates envelope headers
|
|
83
|
+
* (`x-event-id`, `x-correlation-id`, `x-timestamp`, `x-schema-version`).
|
|
84
|
+
*
|
|
85
|
+
* On **consume**, the library extracts those headers and assembles
|
|
86
|
+
* an `EventEnvelope` that is passed to the handler.
|
|
87
|
+
*/
|
|
88
|
+
interface EventEnvelope<T> {
|
|
89
|
+
/** Deserialized + validated message body. */
|
|
90
|
+
payload: T;
|
|
91
|
+
/** Topic the message was produced to / consumed from. */
|
|
92
|
+
topic: string;
|
|
93
|
+
/** Kafka partition (consume-side only, `-1` on send). */
|
|
94
|
+
partition: number;
|
|
95
|
+
/** Kafka offset (consume-side only, empty string on send). */
|
|
96
|
+
offset: string;
|
|
97
|
+
/** ISO-8601 timestamp set by the producer. */
|
|
98
|
+
timestamp: string;
|
|
99
|
+
/** Unique ID for this event (UUID v4). */
|
|
100
|
+
eventId: string;
|
|
101
|
+
/** Correlation ID — auto-propagated via AsyncLocalStorage. */
|
|
102
|
+
correlationId: string;
|
|
103
|
+
/** Schema version of the payload. */
|
|
104
|
+
schemaVersion: number;
|
|
105
|
+
/** W3C Trace Context `traceparent` header (set by OTel instrumentation). */
|
|
106
|
+
traceparent?: string;
|
|
107
|
+
/** All decoded Kafka headers for extensibility. */
|
|
108
|
+
headers: MessageHeaders;
|
|
109
|
+
}
|
|
110
|
+
interface EnvelopeCtx {
|
|
111
|
+
correlationId: string;
|
|
112
|
+
traceparent?: string;
|
|
113
|
+
}
|
|
114
|
+
/** Read the current envelope context (correlationId / traceparent) from ALS. */
|
|
115
|
+
declare function getEnvelopeContext(): EnvelopeCtx | undefined;
|
|
116
|
+
/** Execute `fn` inside an envelope context so nested sends inherit correlationId. */
|
|
117
|
+
declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
|
|
118
|
+
/** Options accepted by `buildEnvelopeHeaders`. */
|
|
119
|
+
interface EnvelopeHeaderOptions {
|
|
120
|
+
correlationId?: string;
|
|
121
|
+
schemaVersion?: number;
|
|
122
|
+
eventId?: string;
|
|
123
|
+
headers?: MessageHeaders;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Generate envelope headers for the send path.
|
|
127
|
+
*
|
|
128
|
+
* Priority for `correlationId`:
|
|
129
|
+
* explicit option → ALS context → new UUID.
|
|
130
|
+
*/
|
|
131
|
+
declare function buildEnvelopeHeaders(options?: EnvelopeHeaderOptions): MessageHeaders;
|
|
132
|
+
/**
|
|
133
|
+
* Decode kafkajs headers (`Record<string, Buffer | string | undefined>`)
|
|
134
|
+
* into plain `Record<string, string>`.
|
|
135
|
+
*/
|
|
136
|
+
declare function decodeHeaders(raw: Record<string, Buffer | string | (Buffer | string)[] | undefined> | undefined): MessageHeaders;
|
|
137
|
+
/**
|
|
138
|
+
* Build an `EventEnvelope` from a consumed kafkajs message.
|
|
139
|
+
* Tolerates missing envelope headers — generates defaults so messages
|
|
140
|
+
* from non-envelope producers still work.
|
|
141
|
+
*/
|
|
142
|
+
declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic: string, partition: number, offset: string): EventEnvelope<T>;
|
|
143
|
+
|
|
72
144
|
/**
|
|
73
145
|
* Mapping of topic names to their message types.
|
|
74
146
|
* Define this interface to get type-safe publish/subscribe across your app.
|
|
@@ -165,6 +237,12 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
|
|
|
165
237
|
* On exhaustion, messages go to `<topic>.dlq` (if `dlq: true`) or `onMessageLost`.
|
|
166
238
|
*/
|
|
167
239
|
retryTopics?: boolean;
|
|
240
|
+
/**
|
|
241
|
+
* Timeout (ms) for waiting until each retry level consumer receives partition
|
|
242
|
+
* assignments after `startConsumer` connects. Default: `10000`.
|
|
243
|
+
* Increase this when the broker is slow to rebalance.
|
|
244
|
+
*/
|
|
245
|
+
retryTopicAssignmentTimeoutMs?: number;
|
|
168
246
|
/**
|
|
169
247
|
* Log a warning if the message handler has not resolved within this window (ms).
|
|
170
248
|
* The handler is not cancelled — this is a diagnostic aid to surface stuck handlers
|
|
@@ -226,13 +304,19 @@ interface ConsumerHandle {
|
|
|
226
304
|
/** Stop this consumer. Equivalent to calling `client.stopConsumer(groupId)`. */
|
|
227
305
|
stop(): Promise<void>;
|
|
228
306
|
}
|
|
307
|
+
/** Result returned by `KafkaClient.checkStatus()`. */
|
|
308
|
+
type KafkaHealthResult = {
|
|
309
|
+
status: "up";
|
|
310
|
+
clientId: string;
|
|
311
|
+
topics: string[];
|
|
312
|
+
} | {
|
|
313
|
+
status: "down";
|
|
314
|
+
clientId: string;
|
|
315
|
+
error: string;
|
|
316
|
+
};
|
|
229
317
|
/** Interface describing all public methods of the Kafka client. */
|
|
230
318
|
interface IKafkaClient<T extends TopicMapConstraint<T>> {
|
|
231
|
-
checkStatus(): Promise<
|
|
232
|
-
status: "up";
|
|
233
|
-
clientId: string;
|
|
234
|
-
topics: string[];
|
|
235
|
-
}>;
|
|
319
|
+
checkStatus(): Promise<KafkaHealthResult>;
|
|
236
320
|
/**
|
|
237
321
|
* Query the consumer group lag per partition using the admin API.
|
|
238
322
|
* Lag = (broker high-watermark offset) − (last committed offset).
|
|
@@ -263,11 +347,14 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
|
|
|
263
347
|
/**
|
|
264
348
|
* Logger interface for KafkaClient.
|
|
265
349
|
* Compatible with NestJS Logger, console, winston, pino, or any custom logger.
|
|
350
|
+
*
|
|
351
|
+
* `debug` is optional — omit it to suppress debug output in production.
|
|
266
352
|
*/
|
|
267
353
|
interface KafkaLogger {
|
|
268
354
|
log(message: string): void;
|
|
269
355
|
warn(message: string, ...args: any[]): void;
|
|
270
356
|
error(message: string, ...args: any[]): void;
|
|
357
|
+
debug?(message: string, ...args: any[]): void;
|
|
271
358
|
}
|
|
272
359
|
/**
|
|
273
360
|
* Context passed to `onMessageLost` when a message is silently dropped
|
|
@@ -322,75 +409,4 @@ interface SubscribeRetryOptions {
|
|
|
322
409
|
backoffMs?: number;
|
|
323
410
|
}
|
|
324
411
|
|
|
325
|
-
|
|
326
|
-
declare const HEADER_CORRELATION_ID = "x-correlation-id";
|
|
327
|
-
declare const HEADER_TIMESTAMP = "x-timestamp";
|
|
328
|
-
declare const HEADER_SCHEMA_VERSION = "x-schema-version";
|
|
329
|
-
declare const HEADER_TRACEPARENT = "traceparent";
|
|
330
|
-
/**
|
|
331
|
-
* Typed wrapper combining a parsed message payload with Kafka metadata
|
|
332
|
-
* and envelope headers.
|
|
333
|
-
*
|
|
334
|
-
* On **send**, the library auto-generates envelope headers
|
|
335
|
-
* (`x-event-id`, `x-correlation-id`, `x-timestamp`, `x-schema-version`).
|
|
336
|
-
*
|
|
337
|
-
* On **consume**, the library extracts those headers and assembles
|
|
338
|
-
* an `EventEnvelope` that is passed to the handler.
|
|
339
|
-
*/
|
|
340
|
-
interface EventEnvelope<T> {
|
|
341
|
-
/** Deserialized + validated message body. */
|
|
342
|
-
payload: T;
|
|
343
|
-
/** Topic the message was produced to / consumed from. */
|
|
344
|
-
topic: string;
|
|
345
|
-
/** Kafka partition (consume-side only, `-1` on send). */
|
|
346
|
-
partition: number;
|
|
347
|
-
/** Kafka offset (consume-side only, empty string on send). */
|
|
348
|
-
offset: string;
|
|
349
|
-
/** ISO-8601 timestamp set by the producer. */
|
|
350
|
-
timestamp: string;
|
|
351
|
-
/** Unique ID for this event (UUID v4). */
|
|
352
|
-
eventId: string;
|
|
353
|
-
/** Correlation ID — auto-propagated via AsyncLocalStorage. */
|
|
354
|
-
correlationId: string;
|
|
355
|
-
/** Schema version of the payload. */
|
|
356
|
-
schemaVersion: number;
|
|
357
|
-
/** W3C Trace Context `traceparent` header (set by OTel instrumentation). */
|
|
358
|
-
traceparent?: string;
|
|
359
|
-
/** All decoded Kafka headers for extensibility. */
|
|
360
|
-
headers: MessageHeaders;
|
|
361
|
-
}
|
|
362
|
-
interface EnvelopeCtx {
|
|
363
|
-
correlationId: string;
|
|
364
|
-
traceparent?: string;
|
|
365
|
-
}
|
|
366
|
-
/** Read the current envelope context (correlationId / traceparent) from ALS. */
|
|
367
|
-
declare function getEnvelopeContext(): EnvelopeCtx | undefined;
|
|
368
|
-
/** Execute `fn` inside an envelope context so nested sends inherit correlationId. */
|
|
369
|
-
declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
|
|
370
|
-
/** Options accepted by `buildEnvelopeHeaders`. */
|
|
371
|
-
interface EnvelopeHeaderOptions {
|
|
372
|
-
correlationId?: string;
|
|
373
|
-
schemaVersion?: number;
|
|
374
|
-
eventId?: string;
|
|
375
|
-
headers?: MessageHeaders;
|
|
376
|
-
}
|
|
377
|
-
/**
|
|
378
|
-
* Generate envelope headers for the send path.
|
|
379
|
-
*
|
|
380
|
-
* Priority for `correlationId`:
|
|
381
|
-
* explicit option → ALS context → new UUID.
|
|
382
|
-
*/
|
|
383
|
-
declare function buildEnvelopeHeaders(options?: EnvelopeHeaderOptions): MessageHeaders;
|
|
384
|
-
/**
|
|
385
|
-
* Decode kafkajs headers (`Record<string, Buffer | string | undefined>`)
|
|
386
|
-
* into plain `Record<string, string>`.
|
|
387
|
-
*/
|
|
388
|
-
declare function decodeHeaders(raw: Record<string, Buffer | string | (Buffer | string)[] | undefined> | undefined): MessageHeaders;
|
|
389
|
-
/**
|
|
390
|
-
* Build an `EventEnvelope` from a consumed kafkajs message.
|
|
391
|
-
* Tolerates missing envelope headers — generates defaults so messages
|
|
392
|
-
* from non-envelope producers still work.
|
|
393
|
-
*/
|
|
394
|
-
declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic: string, partition: number, offset: string): EventEnvelope<T>;
|
|
395
|
-
|
|
396
|
-
export { type BatchMessageItem as B, type ClientId as C, type EnvelopeHeaderOptions as E, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, type KafkaInstrumentation as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type ConsumerOptions as a, type TopicDescriptor as b, type BatchMeta as c, type ConsumerHandle as d, type ConsumerInterceptor as e, type EventEnvelope as f, HEADER_EVENT_ID as g, HEADER_SCHEMA_VERSION as h, HEADER_TIMESTAMP as i, HEADER_TRACEPARENT as j, type InferSchema as k, type KafkaClientOptions as l, type KafkaLogger as m, type MessageLostContext as n, type SendOptions as o, type SubscribeRetryOptions as p, type TTopicMessageMap as q, type TopicsFrom as r, type TransactionContext as s, buildEnvelopeHeaders as t, decodeHeaders as u, extractEnvelope as v, getEnvelopeContext as w, runWithEnvelopeContext as x, topic as y };
|
|
412
|
+
export { type BatchMessageItem as B, type ClientId as C, type EnvelopeHeaderOptions as E, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, type KafkaInstrumentation as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type KafkaClientOptions as a, type ConsumerOptions as b, type TopicDescriptor as c, type KafkaHealthResult as d, type BatchMeta as e, type ConsumerHandle as f, type ConsumerInterceptor as g, type EventEnvelope as h, HEADER_EVENT_ID as i, HEADER_SCHEMA_VERSION as j, HEADER_TIMESTAMP as k, HEADER_TRACEPARENT as l, type InferSchema as m, type KafkaLogger as n, type MessageLostContext as o, type SendOptions as p, type SubscribeRetryOptions as q, type TTopicMessageMap as r, type TopicsFrom as s, type TransactionContext as t, buildEnvelopeHeaders as u, decodeHeaders as v, extractEnvelope as w, getEnvelopeContext as x, runWithEnvelopeContext as y, topic as z };
|
|
@@ -32,8 +32,8 @@ interface TopicDescriptor<N extends string = string, M extends Record<string, an
|
|
|
32
32
|
*
|
|
33
33
|
* @example
|
|
34
34
|
* ```ts
|
|
35
|
-
* // Without schema — type
|
|
36
|
-
* const OrderCreated = topic('order.created')<{ orderId: string; amount: number }>();
|
|
35
|
+
* // Without schema — explicit type via .type<T>():
|
|
36
|
+
* const OrderCreated = topic('order.created').type<{ orderId: string; amount: number }>();
|
|
37
37
|
*
|
|
38
38
|
* // With schema — type inferred from schema:
|
|
39
39
|
* const OrderCreated = topic('order.created').schema(z.object({
|
|
@@ -50,16 +50,17 @@ interface TopicDescriptor<N extends string = string, M extends Record<string, an
|
|
|
50
50
|
* ```
|
|
51
51
|
*/
|
|
52
52
|
declare function topic<N extends string>(name: N): {
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
/** Provide an explicit message type without a runtime schema. */
|
|
54
|
+
type: <M extends Record<string, any>>() => TopicDescriptor<N, M>;
|
|
55
|
+
schema: <S extends SchemaLike<Record<string, any>>>(schema: S) => TopicDescriptor<N, InferSchema<S>>;
|
|
55
56
|
};
|
|
56
57
|
/**
|
|
57
58
|
* Build a topic-message map type from a union of TopicDescriptors.
|
|
58
59
|
*
|
|
59
60
|
* @example
|
|
60
61
|
* ```ts
|
|
61
|
-
* const OrderCreated = topic('order.created')<{ orderId: string }>();
|
|
62
|
-
* const OrderCompleted = topic('order.completed')<{ completedAt: string }>();
|
|
62
|
+
* const OrderCreated = topic('order.created').type<{ orderId: string }>();
|
|
63
|
+
* const OrderCompleted = topic('order.completed').type<{ completedAt: string }>();
|
|
63
64
|
*
|
|
64
65
|
* type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
|
|
65
66
|
* // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
|
|
@@ -69,6 +70,77 @@ type TopicsFrom<D extends TopicDescriptor<any, any>> = {
|
|
|
69
70
|
[K in D as K["__topic"]]: K["__type"];
|
|
70
71
|
};
|
|
71
72
|
|
|
73
|
+
declare const HEADER_EVENT_ID = "x-event-id";
|
|
74
|
+
declare const HEADER_CORRELATION_ID = "x-correlation-id";
|
|
75
|
+
declare const HEADER_TIMESTAMP = "x-timestamp";
|
|
76
|
+
declare const HEADER_SCHEMA_VERSION = "x-schema-version";
|
|
77
|
+
declare const HEADER_TRACEPARENT = "traceparent";
|
|
78
|
+
/**
|
|
79
|
+
* Typed wrapper combining a parsed message payload with Kafka metadata
|
|
80
|
+
* and envelope headers.
|
|
81
|
+
*
|
|
82
|
+
* On **send**, the library auto-generates envelope headers
|
|
83
|
+
* (`x-event-id`, `x-correlation-id`, `x-timestamp`, `x-schema-version`).
|
|
84
|
+
*
|
|
85
|
+
* On **consume**, the library extracts those headers and assembles
|
|
86
|
+
* an `EventEnvelope` that is passed to the handler.
|
|
87
|
+
*/
|
|
88
|
+
interface EventEnvelope<T> {
|
|
89
|
+
/** Deserialized + validated message body. */
|
|
90
|
+
payload: T;
|
|
91
|
+
/** Topic the message was produced to / consumed from. */
|
|
92
|
+
topic: string;
|
|
93
|
+
/** Kafka partition (consume-side only, `-1` on send). */
|
|
94
|
+
partition: number;
|
|
95
|
+
/** Kafka offset (consume-side only, empty string on send). */
|
|
96
|
+
offset: string;
|
|
97
|
+
/** ISO-8601 timestamp set by the producer. */
|
|
98
|
+
timestamp: string;
|
|
99
|
+
/** Unique ID for this event (UUID v4). */
|
|
100
|
+
eventId: string;
|
|
101
|
+
/** Correlation ID — auto-propagated via AsyncLocalStorage. */
|
|
102
|
+
correlationId: string;
|
|
103
|
+
/** Schema version of the payload. */
|
|
104
|
+
schemaVersion: number;
|
|
105
|
+
/** W3C Trace Context `traceparent` header (set by OTel instrumentation). */
|
|
106
|
+
traceparent?: string;
|
|
107
|
+
/** All decoded Kafka headers for extensibility. */
|
|
108
|
+
headers: MessageHeaders;
|
|
109
|
+
}
|
|
110
|
+
interface EnvelopeCtx {
|
|
111
|
+
correlationId: string;
|
|
112
|
+
traceparent?: string;
|
|
113
|
+
}
|
|
114
|
+
/** Read the current envelope context (correlationId / traceparent) from ALS. */
|
|
115
|
+
declare function getEnvelopeContext(): EnvelopeCtx | undefined;
|
|
116
|
+
/** Execute `fn` inside an envelope context so nested sends inherit correlationId. */
|
|
117
|
+
declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
|
|
118
|
+
/** Options accepted by `buildEnvelopeHeaders`. */
|
|
119
|
+
interface EnvelopeHeaderOptions {
|
|
120
|
+
correlationId?: string;
|
|
121
|
+
schemaVersion?: number;
|
|
122
|
+
eventId?: string;
|
|
123
|
+
headers?: MessageHeaders;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Generate envelope headers for the send path.
|
|
127
|
+
*
|
|
128
|
+
* Priority for `correlationId`:
|
|
129
|
+
* explicit option → ALS context → new UUID.
|
|
130
|
+
*/
|
|
131
|
+
declare function buildEnvelopeHeaders(options?: EnvelopeHeaderOptions): MessageHeaders;
|
|
132
|
+
/**
|
|
133
|
+
* Decode kafkajs headers (`Record<string, Buffer | string | undefined>`)
|
|
134
|
+
* into plain `Record<string, string>`.
|
|
135
|
+
*/
|
|
136
|
+
declare function decodeHeaders(raw: Record<string, Buffer | string | (Buffer | string)[] | undefined> | undefined): MessageHeaders;
|
|
137
|
+
/**
|
|
138
|
+
* Build an `EventEnvelope` from a consumed kafkajs message.
|
|
139
|
+
* Tolerates missing envelope headers — generates defaults so messages
|
|
140
|
+
* from non-envelope producers still work.
|
|
141
|
+
*/
|
|
142
|
+
declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic: string, partition: number, offset: string): EventEnvelope<T>;
|
|
143
|
+
|
|
72
144
|
/**
|
|
73
145
|
* Mapping of topic names to their message types.
|
|
74
146
|
* Define this interface to get type-safe publish/subscribe across your app.
|
|
@@ -165,6 +237,12 @@ interface ConsumerOptions<T extends TopicMapConstraint<T> = TTopicMessageMap> {
|
|
|
165
237
|
* On exhaustion, messages go to `<topic>.dlq` (if `dlq: true`) or `onMessageLost`.
|
|
166
238
|
*/
|
|
167
239
|
retryTopics?: boolean;
|
|
240
|
+
/**
|
|
241
|
+
* Timeout (ms) for waiting until each retry level consumer receives partition
|
|
242
|
+
* assignments after `startConsumer` connects. Default: `10000`.
|
|
243
|
+
* Increase this when the broker is slow to rebalance.
|
|
244
|
+
*/
|
|
245
|
+
retryTopicAssignmentTimeoutMs?: number;
|
|
168
246
|
/**
|
|
169
247
|
* Log a warning if the message handler has not resolved within this window (ms).
|
|
170
248
|
* The handler is not cancelled — this is a diagnostic aid to surface stuck handlers
|
|
@@ -226,13 +304,19 @@ interface ConsumerHandle {
|
|
|
226
304
|
/** Stop this consumer. Equivalent to calling `client.stopConsumer(groupId)`. */
|
|
227
305
|
stop(): Promise<void>;
|
|
228
306
|
}
|
|
307
|
+
/** Result returned by `KafkaClient.checkStatus()`. */
|
|
308
|
+
type KafkaHealthResult = {
|
|
309
|
+
status: "up";
|
|
310
|
+
clientId: string;
|
|
311
|
+
topics: string[];
|
|
312
|
+
} | {
|
|
313
|
+
status: "down";
|
|
314
|
+
clientId: string;
|
|
315
|
+
error: string;
|
|
316
|
+
};
|
|
229
317
|
/** Interface describing all public methods of the Kafka client. */
|
|
230
318
|
interface IKafkaClient<T extends TopicMapConstraint<T>> {
|
|
231
|
-
checkStatus(): Promise<
|
|
232
|
-
status: "up";
|
|
233
|
-
clientId: string;
|
|
234
|
-
topics: string[];
|
|
235
|
-
}>;
|
|
319
|
+
checkStatus(): Promise<KafkaHealthResult>;
|
|
236
320
|
/**
|
|
237
321
|
* Query the consumer group lag per partition using the admin API.
|
|
238
322
|
* Lag = (broker high-watermark offset) − (last committed offset).
|
|
@@ -263,11 +347,14 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
|
|
|
263
347
|
/**
|
|
264
348
|
* Logger interface for KafkaClient.
|
|
265
349
|
* Compatible with NestJS Logger, console, winston, pino, or any custom logger.
|
|
350
|
+
*
|
|
351
|
+
* `debug` is optional — omit it to suppress debug output in production.
|
|
266
352
|
*/
|
|
267
353
|
interface KafkaLogger {
|
|
268
354
|
log(message: string): void;
|
|
269
355
|
warn(message: string, ...args: any[]): void;
|
|
270
356
|
error(message: string, ...args: any[]): void;
|
|
357
|
+
debug?(message: string, ...args: any[]): void;
|
|
271
358
|
}
|
|
272
359
|
/**
|
|
273
360
|
* Context passed to `onMessageLost` when a message is silently dropped
|
|
@@ -322,75 +409,4 @@ interface SubscribeRetryOptions {
|
|
|
322
409
|
backoffMs?: number;
|
|
323
410
|
}
|
|
324
411
|
|
|
325
|
-
|
|
326
|
-
declare const HEADER_CORRELATION_ID = "x-correlation-id";
|
|
327
|
-
declare const HEADER_TIMESTAMP = "x-timestamp";
|
|
328
|
-
declare const HEADER_SCHEMA_VERSION = "x-schema-version";
|
|
329
|
-
declare const HEADER_TRACEPARENT = "traceparent";
|
|
330
|
-
/**
|
|
331
|
-
* Typed wrapper combining a parsed message payload with Kafka metadata
|
|
332
|
-
* and envelope headers.
|
|
333
|
-
*
|
|
334
|
-
* On **send**, the library auto-generates envelope headers
|
|
335
|
-
* (`x-event-id`, `x-correlation-id`, `x-timestamp`, `x-schema-version`).
|
|
336
|
-
*
|
|
337
|
-
* On **consume**, the library extracts those headers and assembles
|
|
338
|
-
* an `EventEnvelope` that is passed to the handler.
|
|
339
|
-
*/
|
|
340
|
-
interface EventEnvelope<T> {
|
|
341
|
-
/** Deserialized + validated message body. */
|
|
342
|
-
payload: T;
|
|
343
|
-
/** Topic the message was produced to / consumed from. */
|
|
344
|
-
topic: string;
|
|
345
|
-
/** Kafka partition (consume-side only, `-1` on send). */
|
|
346
|
-
partition: number;
|
|
347
|
-
/** Kafka offset (consume-side only, empty string on send). */
|
|
348
|
-
offset: string;
|
|
349
|
-
/** ISO-8601 timestamp set by the producer. */
|
|
350
|
-
timestamp: string;
|
|
351
|
-
/** Unique ID for this event (UUID v4). */
|
|
352
|
-
eventId: string;
|
|
353
|
-
/** Correlation ID — auto-propagated via AsyncLocalStorage. */
|
|
354
|
-
correlationId: string;
|
|
355
|
-
/** Schema version of the payload. */
|
|
356
|
-
schemaVersion: number;
|
|
357
|
-
/** W3C Trace Context `traceparent` header (set by OTel instrumentation). */
|
|
358
|
-
traceparent?: string;
|
|
359
|
-
/** All decoded Kafka headers for extensibility. */
|
|
360
|
-
headers: MessageHeaders;
|
|
361
|
-
}
|
|
362
|
-
interface EnvelopeCtx {
|
|
363
|
-
correlationId: string;
|
|
364
|
-
traceparent?: string;
|
|
365
|
-
}
|
|
366
|
-
/** Read the current envelope context (correlationId / traceparent) from ALS. */
|
|
367
|
-
declare function getEnvelopeContext(): EnvelopeCtx | undefined;
|
|
368
|
-
/** Execute `fn` inside an envelope context so nested sends inherit correlationId. */
|
|
369
|
-
declare function runWithEnvelopeContext<R>(ctx: EnvelopeCtx, fn: () => R): R;
|
|
370
|
-
/** Options accepted by `buildEnvelopeHeaders`. */
|
|
371
|
-
interface EnvelopeHeaderOptions {
|
|
372
|
-
correlationId?: string;
|
|
373
|
-
schemaVersion?: number;
|
|
374
|
-
eventId?: string;
|
|
375
|
-
headers?: MessageHeaders;
|
|
376
|
-
}
|
|
377
|
-
/**
|
|
378
|
-
* Generate envelope headers for the send path.
|
|
379
|
-
*
|
|
380
|
-
* Priority for `correlationId`:
|
|
381
|
-
* explicit option → ALS context → new UUID.
|
|
382
|
-
*/
|
|
383
|
-
declare function buildEnvelopeHeaders(options?: EnvelopeHeaderOptions): MessageHeaders;
|
|
384
|
-
/**
|
|
385
|
-
* Decode kafkajs headers (`Record<string, Buffer | string | undefined>`)
|
|
386
|
-
* into plain `Record<string, string>`.
|
|
387
|
-
*/
|
|
388
|
-
declare function decodeHeaders(raw: Record<string, Buffer | string | (Buffer | string)[] | undefined> | undefined): MessageHeaders;
|
|
389
|
-
/**
|
|
390
|
-
* Build an `EventEnvelope` from a consumed kafkajs message.
|
|
391
|
-
* Tolerates missing envelope headers — generates defaults so messages
|
|
392
|
-
* from non-envelope producers still work.
|
|
393
|
-
*/
|
|
394
|
-
declare function extractEnvelope<T>(payload: T, headers: MessageHeaders, topic: string, partition: number, offset: string): EventEnvelope<T>;
|
|
395
|
-
|
|
396
|
-
export { type BatchMessageItem as B, type ClientId as C, type EnvelopeHeaderOptions as E, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, type KafkaInstrumentation as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type ConsumerOptions as a, type TopicDescriptor as b, type BatchMeta as c, type ConsumerHandle as d, type ConsumerInterceptor as e, type EventEnvelope as f, HEADER_EVENT_ID as g, HEADER_SCHEMA_VERSION as h, HEADER_TIMESTAMP as i, HEADER_TRACEPARENT as j, type InferSchema as k, type KafkaClientOptions as l, type KafkaLogger as m, type MessageLostContext as n, type SendOptions as o, type SubscribeRetryOptions as p, type TTopicMessageMap as q, type TopicsFrom as r, type TransactionContext as s, buildEnvelopeHeaders as t, decodeHeaders as u, extractEnvelope as v, getEnvelopeContext as w, runWithEnvelopeContext as x, topic as y };
|
|
412
|
+
export { type BatchMessageItem as B, type ClientId as C, type EnvelopeHeaderOptions as E, type GroupId as G, HEADER_CORRELATION_ID as H, type IKafkaClient as I, type KafkaInstrumentation as K, type MessageHeaders as M, type RetryOptions as R, type SchemaLike as S, type TopicMapConstraint as T, type KafkaClientOptions as a, type ConsumerOptions as b, type TopicDescriptor as c, type KafkaHealthResult as d, type BatchMeta as e, type ConsumerHandle as f, type ConsumerInterceptor as g, type EventEnvelope as h, HEADER_EVENT_ID as i, HEADER_SCHEMA_VERSION as j, HEADER_TIMESTAMP as k, HEADER_TRACEPARENT as l, type InferSchema as m, type KafkaLogger as n, type MessageLostContext as o, type SendOptions as p, type SubscribeRetryOptions as q, type TTopicMessageMap as r, type TopicsFrom as s, type TransactionContext as t, buildEnvelopeHeaders as u, decodeHeaders as v, extractEnvelope as w, getEnvelopeContext as x, runWithEnvelopeContext as y, topic as z };
|