@drarzter/kafka-client 0.7.2 → 0.7.4

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 (21) hide show
  1. package/README.md +137 -7
  2. package/dist/{chunk-MADAJD2F.mjs → chunk-BVWRZTMD.mjs} +858 -864
  3. package/dist/chunk-BVWRZTMD.mjs.map +1 -0
  4. package/dist/core.d.mts +36 -139
  5. package/dist/core.d.ts +36 -139
  6. package/dist/core.js +857 -863
  7. package/dist/core.js.map +1 -1
  8. package/dist/core.mjs +1 -1
  9. package/dist/index.d.mts +2 -2
  10. package/dist/index.d.ts +2 -2
  11. package/dist/index.js +853 -859
  12. package/dist/index.js.map +1 -1
  13. package/dist/index.mjs +1 -1
  14. package/dist/otel.d.mts +1 -1
  15. package/dist/otel.d.ts +1 -1
  16. package/dist/testing.d.mts +1 -1
  17. package/dist/testing.d.ts +1 -1
  18. package/dist/{types-4qWrf2aJ.d.mts → types-Db7qSbZP.d.mts} +14 -0
  19. package/dist/{types-4qWrf2aJ.d.ts → types-Db7qSbZP.d.ts} +14 -0
  20. package/package.json +1 -1
  21. package/dist/chunk-MADAJD2F.mjs.map +0 -1
package/README.md CHANGED
@@ -1866,13 +1866,143 @@ Both suites run in CI on every push to `main` and on pull requests.
1866
1866
 
1867
1867
  ```text
1868
1868
  src/
1869
- ├── client/ # Core — KafkaClient, types, envelope, consumer pipeline, topic(), errors (0 framework deps)
1870
- ├── nest/ # NestJS adapter — Module, Explorer, decorators, health
1871
- ├── testing/ # Testing utilities — mock client, testcontainer wrapper
1872
- ├── core.ts # Standalone entrypoint (@drarzter/kafka-client/core)
1873
- ├── otel.ts # OpenTelemetry entrypoint (@drarzter/kafka-client/otel)
1874
- ├── testing.ts # Testing entrypoint (@drarzter/kafka-client/testing)
1875
- └── index.ts # Full entrypoint — core + NestJS adapter
1869
+ ├── index.ts # Full entrypoint — core + NestJS adapter
1870
+ ├── core.ts # Standalone entrypoint (@drarzter/kafka-client/core)
1871
+ ├── otel.ts # OpenTelemetry entrypoint (@drarzter/kafka-client/otel)
1872
+ ├── testing.ts # Testing entrypoint (@drarzter/kafka-client/testing)
1873
+ │
1874
+ ├── client/ # Core library — zero framework dependencies
1875
+ │ ├── types.ts # All public interfaces: KafkaClientOptions, ConsumerOptions,
1876
+ │ │ # SendOptions, EventEnvelope, ConsumerHandle, BatchMeta,
1877
+ │ │ # KafkaInstrumentation, ConsumerInterceptor, SchemaLike, …
1878
+ │ ├── errors.ts # KafkaProcessingError, KafkaRetryExhaustedError, KafkaValidationError
1879
+ │ │
1880
+ │ ├── message/
1881
+ │ │ ├── envelope.ts # extractEnvelope() — Buffer → EventEnvelope; buildHeaders()
1882
+ │ │ └── topic.ts # topic() builder → TopicDescriptor; global schema registry;
1883
+ │ │ # TopicsFrom<T> utility type
1884
+ │ │
1885
+ │ ├── kafka.client/
1886
+ │ │ ├── index.ts # KafkaClient class — public API, producer/consumer lifecycle,
1887
+ │ │ │ # Lamport clock, ALS correlation ID, graceful shutdown,
1888
+ │ │ │ # Lamport clock recovery (clockRecovery option)
1889
+ │ │ │
1890
+ │ │ ├── admin/
1891
+ │ │ │ └── ops.ts # AdminOps: listConsumerGroups(), describeTopics(),
1892
+ │ │ │ # deleteRecords(), resetOffsets(), seekToOffset(),
1893
+ │ │ │ # seekToTimestamp(), getConsumerLag(), ensureTopic()
1894
+ │ │ │
1895
+ │ │ ├── producer/
1896
+ │ │ │ └── ops.ts # buildPayload() — JSON serialise + schema.parse();
1897
+ │ │ │ # sendMessage / sendBatch / transaction / sendTombstone;
1898
+ │ │ │ # schema registry lookup for strictSchemas mode
1899
+ │ │ │
1900
+ │ │ ├── consumer/
1901
+ │ │ │ ├── ops.ts # setupConsumer() — librdkafka Consumer factory, rebalance
1902
+ │ │ │ │ # hooks, subscribe with retries, autoCommit config;
1903
+ │ │ │ │ # startConsumer() / startBatchConsumer() orchestration
1904
+ │ │ │ ├── handler.ts # handleEachMessage() / handleEachBatch() — top-level
1905
+ │ │ │ │ # eachMessage/eachBatch callbacks wired to pipeline;
1906
+ │ │ │ │ # EOS main-consumer context for retryTopics mode
1907
+ │ │ │ ├── pipeline.ts # executeWithRetry() — dedup → TTL → interceptors →
1908
+ │ │ │ │ # handler → retry/DLQ/lost; sendToDlq(); sendToRetryTopic()
1909
+ │ │ │ ├── retry-topic.ts # startRetryTopicConsumers() — spins up N level consumers;
1910
+ │ │ │ │ # startLevelConsumer() — pause/sleep/resume per partition;
1911
+ │ │ │ │ # EOS routing via sendOffsetsToTransaction
1912
+ │ │ │ ├── subscribe-retry.ts # subscribeWithRetry() — retries consumer.subscribe() when
1913
+ │ │ │ │ # topic doesn't exist yet (subscribeRetry option)
1914
+ │ │ │ ├── dlq-replay.ts # replayDlq() — temp consumer reads DLQ up to high-watermark,
1915
+ │ │ │ │ # strips x-dlq-* headers, re-publishes to original topic
1916
+ │ │ │ └── queue.ts # AsyncQueue — bounded async iterator used by consume();
1917
+ │ │ │ # backpressure via queueHighWaterMark (pause/resume)
1918
+ │ │ │
1919
+ │ │ └── infra/
1920
+ │ │ ├── circuit-breaker.ts # CircuitBreakerManager — per groupId:topic:partition state
1921
+ │ │ │ # machine (CLOSED → OPEN → HALF_OPEN); sliding failure window
1922
+ │ │ ├── metrics-manager.ts # MetricsManager — in-process counters (processed / retry /
1923
+ │ │ │ # dlq / dedup) per topic; getMetrics() / resetMetrics()
1924
+ │ │ └── inflight-tracker.ts # InFlightTracker — tracks running handlers for graceful
1925
+ │ │ # shutdown drain (disconnect waits for all to settle)
1926
+ │ │
1927
+ │ └── __tests__/ # Unit tests — mocked @confluentinc/kafka-javascript
1928
+ │ ├── helpers.ts # buildMockMessage(), mock setup, spy exports (mockSend, …)
1929
+ │ ├── consumer.spec.ts # Legacy top-level consumer tests
1930
+ │ ├── consumer/
1931
+ │ │ ├── consumer.spec.ts # startConsumer() core behaviour
1932
+ │ │ ├── batch-consumer.spec.ts # startBatchConsumer(), BatchMeta, autoCommit
1933
+ │ │ ├── consumer-groups.spec.ts # Multiple groupId, eachMessage/eachBatch conflict guard
1934
+ │ │ ├── consumer-handle.spec.ts # ConsumerHandle.stop()
1935
+ │ │ ├── consume-iterator.spec.ts # consume() iterator, backpressure, break/return
1936
+ │ │ ├── retry.spec.ts # In-process retry, backoff, maxRetries
1937
+ │ │ ├── retry-topic.spec.ts # Retry topic chain, EOS routing, level consumers
1938
+ │ │ ├── deduplication.spec.ts # Lamport clock dedup, strategies (drop/dlq/topic)
1939
+ │ │ ├── interceptors.spec.ts # ConsumerInterceptor before/after/onError hooks
1940
+ │ │ ├── dlq-replay.spec.ts # replayDlq(), dryRun, filter, targetTopic
1941
+ │ │ ├── ttl.spec.ts # messageTtlMs, onTtlExpired, TTL→DLQ routing
1942
+ │ │ ├── message-lost.spec.ts # onMessageLost — handler error, validation, DLQ failure
1943
+ │ │ ├── handler-timeout.spec.ts # handlerTimeoutMs warning
1944
+ │ │ └── rebalance.spec.ts # onRebalance assign/revoke callbacks
1945
+ │ ├── producer/
1946
+ │ │ ├── producer.spec.ts # sendMessage(), sendBatch(), sendTombstone(), compression
1947
+ │ │ ├── transaction.spec.ts # transaction(), tx.send(), tx.sendBatch(), rollback
1948
+ │ │ ├── schema.spec.ts # Schema validation on send/consume, strictSchemas
1949
+ │ │ └── topic.spec.ts # topic() descriptor, TopicsFrom, schema registry
1950
+ │ ├── admin/
1951
+ │ │ ├── admin.spec.ts # listConsumerGroups(), describeTopics(), deleteRecords(),
1952
+ │ │ │ # resetOffsets(), seekToOffset(), seekToTimestamp()
1953
+ │ │ └── consumer-lag.spec.ts # getConsumerLag()
1954
+ │ └── infra/
1955
+ │ ├── circuit-breaker.spec.ts # CircuitBreaker state machine, getCircuitState()
1956
+ │ ├── errors.spec.ts # Error class hierarchy and properties
1957
+ │ ├── instrumentation.spec.ts # KafkaInstrumentation hooks, wrap/cleanup composition
1958
+ │ ├── otel.spec.ts # otelInstrumentation(), traceparent propagation
1959
+ │ ├── metrics-counters.spec.ts # getMetrics(), resetMetrics(), per-topic counters
1960
+ │ └── metrics-observability.spec.ts # onMessage/onRetry/onDlq/onDuplicate hooks
1961
+ │
1962
+ ├── nest/ # NestJS adapter — depends on @nestjs/common, reflect-metadata
1963
+ │ ├── kafka.module.ts # KafkaModule.register() / registerAsync(); DynamicModule,
1964
+ │ │ # isGlobal, named clients; onModuleInit / onModuleDestroy
1965
+ │ ├── kafka.explorer.ts # Auto-discovers @SubscribeTo() methods across all providers
1966
+ │ │ # at startup and calls startConsumer / startBatchConsumer
1967
+ │ ├── kafka.decorator.ts # @SubscribeTo(topic, options) method decorator;
1968
+ │ │ # @InjectKafkaClient(name?) parameter decorator
1969
+ │ ├── kafka.health.ts # KafkaHealthIndicator.check() — wraps kafka.checkStatus()
1970
+ │ ├── kafka.constants.ts # DI token constants (KAFKA_CLIENT, KAFKA_OPTIONS)
1971
+ │ └── __tests__/
1972
+ │ ├── kafka.decorator.spec.ts # @SubscribeTo / @InjectKafkaClient metadata
1973
+ │ ├── kafka.explorer.spec.ts # Explorer discovery and subscription wiring
1974
+ │ └── kafka.health.spec.ts # KafkaHealthIndicator up/down responses
1975
+ │
1976
+ ├── testing/ # Testing utilities — no runtime Kafka deps
1977
+ │ ├── index.ts # Re-exports createMockKafkaClient, KafkaTestContainer
1978
+ │ ├── mock-client.ts # createMockKafkaClient<T>() — jest.fn() on every
1979
+ │ │ # IKafkaClient method with sensible defaults
1980
+ │ ├── test-container.ts # KafkaTestContainer — thin @testcontainers/kafka wrapper;
1981
+ │ │ # transaction coordinator warmup, topic pre-creation
1982
+ │ └── __tests__/
1983
+ │ ├── mock-client.spec.ts # Mock client method stubs and overrides
1984
+ │ └── test-container.spec.ts # Container start/stop lifecycle
1985
+ │
1986
+ ├── integration/ # Integration tests — require Docker (testcontainers)
1987
+ │ ├── global-setup.ts # Start shared Kafka container before all suites
1988
+ │ ├── global-teardown.ts # Stop container after all suites
1989
+ │ ├── helpers.ts # createClient(), waitForMessages(), unique topic names
1990
+ │ ├── basic.integration.spec.ts # Send/receive, headers, batch, fromBeginning
1991
+ │ ├── consumer.integration.spec.ts # startConsumer(), pause/resume, stopConsumer()
1992
+ │ ├── transaction.integration.spec.ts # Atomic sends, rollback on error
1993
+ │ ├── retry.integration.spec.ts # In-process retry, retryTopics chain, DLQ
1994
+ │ ├── deduplication.integration.spec.ts # Lamport clock dedup with real broker
1995
+ │ ├── consumer-lag.integration.spec.ts # getConsumerLag() against real offsets
1996
+ │ ├── consumer-handle.integration.spec.ts # ConsumerHandle.stop() lifecycle
1997
+ │ ├── graceful-shutdown.integration.spec.ts # disconnect() drains in-flight handlers
1998
+ │ ├── schema.integration.spec.ts # Schema validation send+consume round-trip
1999
+ │ ├── otel.integration.spec.ts # OpenTelemetry span propagation end-to-end
2000
+ │ └── chaos.integration.spec.ts # Fault injection — broker restarts, rebalances
2001
+ │
2002
+ └── __mocks__/
2003
+ └── @confluentinc/
2004
+ └── kafka-javascript.ts # Manual Jest mock — Kafka, Producer, Consumer stubs;
2005
+ # mockSend, mockTxSend, mockCommit, mockSeek, …
1876
2006
  ```
1877
2007
 
1878
2008
  All exported types and methods have JSDoc comments — your IDE will show inline docs and autocomplete.