kurrent-io/KurrentDB-Client-NodeJS

This system is a TypeScript client library for the KurrentDB event sourcing database, providing comprehensive tools for interacting with the server's v1 and v2 protocols. It enables core event sourcing operations such as appending events to single or multiple streams, reading event data with server-side filtering, and managing persistent subscriptions for real-time event consumption. Additionally, the library supports advanced database administration features, including the creation and management of projections, stream metadata handling, and cluster-level operations like scavenge and node priority adjustments. The package also includes built-in OpenTelemetry instrumentation for distributed tracing and a benchmarking suite to measure client performance against standardized workloads.

This change introduces a new OpenTelemetry instrumentation package for the KurrentDB client, enabling automatic distributed tracing for database interactions. It instruments key client methods including \appendToStream\, \multiStreamAppend\, \appendRecords\, and various subscription methods (\subscribeToStream\, \subscribeToAll\, \subscribeToPersistentSubscriptionToStream\, \subscribeToPersistentSubscriptionToAll\). The instrumentation creates spans with specific attributes such as stream names, server addresses, authentication kinds (basic, bearer, provider), and operation types, allowing users to monitor and debug their KurrentDB usage within their OpenTelemetry observability stack.

packages/opentelemetry/src · high confidence

The \packages/db-client/src/projections\ module now exposes a complete set of methods for managing projections via the gRPC \ProjectionsService\. Users can create continuous projections with support for the V2 engine (opt-in), update queries and emit settings, delete projections (including emitted streams and state), enable/disable/abort/reset them, and retrieve their status, result, or state. The implementation handles both gRPC and HTTP fallbacks for compatibility and maps detailed projection statistics into a structured \ProjectionDetails\ type.

packages/db-client/src/projections · high confidence

A new benchmarking package has been introduced to measure the performance of stream reading operations. It includes scripts for the KurrentDB client, the KurrentDB bridge client, and the legacy EventStoreDB client (v6.2.1), alongside a Docker Compose configuration to spin up a local EventStoreDB instance for testing. This allows users to compare the throughput and latency of different client implementations against a standardized read-stream workload.

packages/benchmark · high confidence

The db-client now includes generated TypeScript definitions and JavaScript stubs for the KurrentDB protocols v1 API. This adds client support for the Gossip service (cluster read), the Operations service (scavenge, shutdown, merge indexes, resign node, set node priority, restart persistent subscriptions), and the Persistent Subscriptions service, enabling the client to communicate with the server using the v1 protocol structure.

packages/db-client/generated, packages/db-client/protos · high confidence

This change introduces the foundational type definitions, constants, and export structure for the new KurrentDB client library. It establishes the core data models for events (including JSON and binary types, metadata handling, and link events), stream operations (such as append states, revisions, and positions), and persistent subscriptions. The update also defines system stream names, projection engine versions (v1 and v2), and credential interfaces, providing the necessary TypeScript contracts for interacting with the KurrentDB server.

packages/db-client/src/types · high confidence

The \packages/db-client/src/streams\ module now exposes new methods for managing stream lifecycle and metadata. Users can soft-delete streams with \deleteStream\ and permanently remove them with \tombstoneStream\, both supporting expected revision checks. Stream metadata can now be read via \getStreamMetadata\ and written via \setStreamMetadata\. Additionally, the \readAll\ operation now supports server-side filtering via a \filter\ option, allowing users to filter events or streams by prefix or regex directly on the server.

packages/db-client/src/streams · high confidence

This change introduces new utility classes and functions in the db-client to enhance stream interaction. The \ReadStream\ class provides a transform stream for reading events from a gRPC stream, handling confirmation and stream-not-found errors. The \Subscription\ class extends this to support subscription-based reading, emitting \caughtUp\ and \fellBehind\ events with position details, and handling checkpoint callbacks. Additionally, \streamMetadata.ts\ adds helpers to prepare and read stream metadata, including system-level settings like max age, max count, cache control, and ACLs. Finally, \systemStreams.ts\ provides utilities to identify system streams and metastreams.

packages/db-client/src/streams/utils · high confidence

The \packages/db-client/src/utils\ directory has been populated with a comprehensive set of utility modules to support the client's core operations. This includes a robust error handling system (\CommandError.ts\, \convertBridgeError.ts\) that maps gRPC and native bridge errors to specific, typed exceptions (e.g., \NotLeaderError\, \StreamNotFoundError\) with extracted metadata. Credential management is standardized via \credentials.ts\, which provides type predicates and header generation for both Basic and Bearer authentication. Event processing is supported by \convertGrpcEvent.ts\ and \convertRustEvent.ts\, which handle the translation of gRPC and Rust bridge events into the client's internal \ResolvedEvent\ format, including proper handling of JSON metadata and BigInt positions. Additional utilities cover stream identification, UUID parsing, backpressured writes, and debug logging.

packages/db-client/src/utils · high confidence

The database client now exposes a comprehensive set of methods for managing persistent subscriptions, including creating, updating, and deleting subscriptions for both specific streams and the global $all stream. Users can retrieve subscription information, list existing subscriptions, and restart the subscription subsystem. Additionally, the client supports subscribing to persistent subscriptions to receive real-time event streams, with built-in support for acknowledging (ack) and negatively acknowledging (nack) events, including options to park, retry, skip, or stop processing. The implementation handles protocol versioning, automatically falling back to HTTP for older servers where gRPC is not supported, and enforces server version requirements for specific features like the PinnedByCorrelation consumer strategy.

packages/db-client/src/persistentSubscription · high confidence

The \appendToStream\ module now supports three distinct append modes: \batchAppend\ (v1 protocol, used when available for single-stream batching), \multiStreamAppend\ (v2 protocol, enabling atomic writes across multiple streams via the \appendSession\ RPC), and \appendRecords\ (v2 protocol, allowing interleaved records with cross-stream consistency checks). A key behavioral change is the enforcement of strict metadata validation for \multiStreamAppend\ and \appendRecords\: metadata must be plain objects with string keys and string values; non-string values, arrays, or raw Uint8Arrays will now throw an error rather than being silently processed or converted. Additionally, \batchAppend\ now includes a fix to prevent unhandled promise rejections and cross-stream error contamination by properly settling promises in the error handler and using correlation IDs to match responses.

packages/db-client/src/streams/appendToStream · high confidence

The database client has been rebranded to support the Kurrent database, updating connection string protocols from 'esdb' to 'kurrentdb' (with a deprecation warning for the old protocol). A new 'tlsVerifyCert' option is now honored in connection strings, allowing users to disable certificate verification without switching to a fully insecure connection. The client also introduces first-class support for bearer token credentials, enabling authentication via bearer tokens in addition to existing methods.

packages/db-client/src/Client · high confidence

Added comprehensive test coverage for streams module; Added comprehensive tests for KurrentDB client connection handling; Added integration and unit tests for the KurrentDB client; Added integration tests for persistent subscription operations; Added sample tests for KurrentDB client operations; Added test coverage for projection management operations; Added tests for OpenTelemetry instrumentation; New test infrastructure utilities for KurrentDB client testing.

This change introduces the project's documentation site (\docs/\) built with VuePress 2, Vite, and Vue 3, including dependencies for syntax highlighting, search, and Mermaid diagrams. It also establishes the root monorepo configuration using Yarn 4 and Nx, defining workspace packages for the core client (\@kurrent/kurrentdb-client\), OpenTelemetry instrumentation, benchmarking, and testing utilities.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 57 → 63 (+6.4)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 83 → 86 (+3.0)
• Architecture 89 → 91 (+1.8)
• Maturity 54 → 57 (+2.1)
• Readiness 54 → 67 (+12.9)
• Security 50 → 62 (+12.5)

• Change coupling: binaryEvent.ts ↔ jsonEvent.ts (packages/db-client/src/events/binaryEvent.ts)
• Coverage not included — suite not readable by the collector
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Further orphaned files (smaller)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• …and 52 more

• Change coupling: readAll.ts ↔ readStream.ts (packages/db-client/src/streams/readAll.ts)
• ClassTooLong: Client (packages/db-client/src/Client/index.ts)
• Client.connectionString (cognitive 32) (packages/db-client/src/Client/index.ts)
• Client.connectionString (cyclomatic 19) (packages/db-client/src/Client/index.ts)
• CommandError.convertToCommandError (cognitive 24) (packages/db-client/src/utils/CommandError.ts)
• CommandError.convertToCommandError (cyclomatic 43) (packages/db-client/src/utils/CommandError.ts)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Critical CVE: [GHSA redacted] (yarn.lock)
• Documentation: no installation or build instructions (README.md)
• Documentation: no installation or build instructions (docs/api/getting-started.md)
• Fork-triggerable workflow runs with an unscoped write token
• FunctionTooLong: CommandError.convertToCommandError (packages/db-client/src/utils/CommandError.ts)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• High CVE: [GHSA redacted] (yarn.lock)
• …and 108 more

• 2 commits — 0 feature/other, 2 fixes

• .github/workflows — 1 commit
• packages/db-client — 1 commit

• fix: Fix CI workflows for pull requests from forks (#526)
• fix: fix: prevent unhandledRejection in batchAppend (#505)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

kurrent-io/KurrentDB-Client-NodeJS was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.