node-ts/bus
60.0
Adequate · 9 November 2026
51.6k
lines of production code
TypeScript
primary language
7
measurements over time
What this system is
This system is a TypeScript service bus library designed for handling asynchronous messaging, workflows, and distributed tracing within Node.js applications. It provides a pluggable architecture with built-in transports for RabbitMQ, AWS SQS, Redis, and PostgreSQL, alongside persistence layers for MongoDB and Postgres. The library supports complex message serialization, transactional outboxes for data consistency, and integrates with NestJS and OpenTelemetry for observability and dependency injection.
How it got here
2019 — Initial v2.0.0 release and architecture
12 changes.
This period marks the initial release of @node-ts/bus v2.0.0, establishing the foundational architecture for a TypeScript service bus with support for RabbitMQ, AWS SQS, and Postgres transports. The work involved defining core message handling patterns, implementing classless message declarations, and removing legacy Inversify dependencies to simplify the API. Infrastructure was also modernized by migrating the monorepo to pnpm and Node 24, alongside setting up CI/CD pipelines for automated releases and testing.
2021–2024 — Bus transport and persistence enhancements
7 changes.
This period focused on expanding the bus system with new transport and persistence implementations, including Redis Streams, MongoDB transactional outbox support, and AWS Lambda SQS integration. Comprehensive integration tests were added to validate message serialization, atomicity guarantees, and reliability across these new components. Development tooling was also updated to align with the migration to pnpm.
2026 — CLI tooling and observability expansion
7 changes.
This period focused on expanding the project's ecosystem with new tooling and integration packages. Key developments included the introduction of a CLI for message type generation and infrastructure provisioning, alongside a NestJS module for seamless framework integration. Additionally, OpenTelemetry support was added for comprehensive observability, supported by robust internal validation tools and test infrastructure.
Features
Add OpenTelemetry tracing and metrics middleware
The \@node-ts/bus-opentelemetry\ package introduces a middleware that automatically traces message flows and records metrics for the bus. It creates OpenTelemetry spans for every message lifecycle stage—producer (send/publish), consumer (process), and handler execution—and propagates trace context through message attributes to maintain distributed traces across different transports. The middleware also exposes metrics such as message send/consume counts, processing duration, and failure rates, allowing users to integrate their existing OpenTelemetry infrastructure with the bus for comprehensive observability.
packages/bus-opentelemetry · high confidence
Added generated message types and test helpers for serialization and transport testing
The \packages/bus-test/src/helpers\ directory now includes a generated \message-types.generated.ts\ file and a suite of test message classes (such as \TestRoundTripCommand\, \TestOutboxCommand\, and \TestFunctionRoundTripWorkflowState\) that define complex nested structures, dates, and collections. These helpers, along with the \HandleChecker\ interface, provide the necessary test fixtures to verify that message serialization, round-trip transport, and workflow state persistence correctly handle nested types and specific data formats.
packages/bus-test/src/helpers · high confidence
CLI commands for generating message types and provisioning infrastructure
The \@node-ts/bus-cli\ package now exposes two new commands: \generate-message-types\ and \provision\. The \generate-message-types\ command reads TypeScript source files to automatically generate a \message-types.generated.ts\ file that maps message classes to their field types, ensuring that complex types like Dates and nested classes are correctly restored at runtime without manual decorators. The \provision\ command allows developers to create the necessary queues, topics, tables, and indexes for the bus infrastructure at deploy time by loading a bus configuration module, rather than requiring this setup to happen on application start.
packages/bus-cli/src · high confidence
Initial release of @node-ts/bus v2.0.0
This change introduces the initial v2.0.0 release of the @node-ts/bus TypeScript service bus, establishing the foundational architecture for message handling, workflows, and pluggable transports. The release includes the core bus implementation, in-memory defaults, and initial transport adapters for RabbitMQ, AWS SQS, and Postgres, alongside persistence options for Postgres and MongoDB. It also ships with a NestJS module, an OpenTelemetry middleware for tracing, a CLI for provisioning and type generation, and a test harness for adapter conformance. The project is structured as a pnpm monorepo requiring Node.js 24, utilizing changesets for versioning and publishing, and includes comprehensive documentation hosted on GitHub Pages.
(repo-wide) · high confidence
Introduce @node-ts/bus-nestjs module for NestJS integration
Adds the @node-ts/bus-nestjs package, providing a NestJS module that integrates the bus into a Nest application. The module registers the bus via BusModule.forRoot() or forRootAsync() and allows feature modules to register handlers and workflows using BusModule.forFeature() or forFeatureAsync(), or by decorating classes with @BusHandler() and @BusWorkflow(). The bus lifecycle is managed automatically by Nest's lifecycle hooks, initializing and starting on application bootstrap and stopping/disposing on shutdown, with support for manual lifecycle control. It also includes a createBusForProvisioning() utility for CLI provisioning workflows.
packages/bus-nestjs · high confidence
Introduce AWS Lambda SQS receiver with partial batch failure support
The \bus-sqs-lambda\ package now includes a \BusSqsLambdaReceiver\ that enables processing SQS events within AWS Lambda functions. This receiver parses incoming messages and, when the \reportBatchItemFailures\ configuration option is enabled, returns an \SQSBatchResponse\ listing only the failed records, allowing Lambda to retry individual items rather than the entire batch. The implementation also maps SQS message attributes (including correlation ID, message ID, sent time, and reply-to address) into transport metadata and ensures compatibility with \bus.returnMessage()\ and \bus.failMessage()\ by providing the necessary AWS SDK-shaped fields.
packages/bus-sqs-lambda/src · high confidence
Introduce Postgres transport and persistence for the message bus
This change adds a new Postgres-based transport and persistence layer to the bus, enabling message queuing, delivery, and workflow state storage in PostgreSQL. It introduces configuration interfaces for connection pools, schema names, and transport settings like visibility timeouts and polling intervals. The implementation includes a durable transactional outbox, allowing handlers to write to the database and send messages within a single transaction, ensuring atomicity. It also features an inbox table to guarantee exactly-once message processing per endpoint, and provisions necessary database schemas, tables, and indexes at deployment time. Custom error classes are provided for validation, such as invalid schema names or transport durations.
packages/bus-postgres/src · high confidence
Introduce Redis Streams transport for @node-ts/bus
The \@node-ts/bus-redis\ package now uses Redis Streams instead of the previous list-based approach (BullMQ/modest-queue). It requires Redis 7.0+ or Valkey 7.2+ and node-redis 6, and exposes a \RedisTransport\ with configuration for \queueName\, \connection\, \keyPrefix\, \visibilityTimeoutMs\, and \deadLetterRetentionMs\. The transport manages per-queue streams, consumer groups, and delayed/dead-letter sets, and provides a provisioning plan that generates Redis ACL rules for runtime access.
packages/bus-redis · high confidence
Introduce bus CLI for message type generation and infrastructure provisioning
The @node-ts/bus-cli package is now available, providing a command-line interface with two main capabilities. First, the 'generate-message-types' command analyzes TypeScript source files to automatically generate a message-types file, enabling the bus to correctly restore complex types like Dates, Maps, Sets, and class instances without requiring decorators or reflect-metadata. Second, the 'provision' command allows users to create necessary infrastructure (queues, topics, tables, indexes) at deploy time by building a bus configuration from a module export, supporting dry-run modes and JSON reporting for permissions.
packages/bus-cli · high confidence
New defineCommand and defineEvent APIs for classless message declarations
The \packages/bus-messages/src\ module now supports declaring commands and events using the \defineCommand\ and \defineEvent\ functions instead of requiring message classes. These functions create plain objects with \$name\ and \$version\ properties, allowing developers to define message contracts without writing boilerplate class code. The package also introduces \messageAttributes\ for easier attribute handling, \mergeMessageTypes\ for combining message type libraries, and new error types (\MessageTypeReferenceNotFound\, \MessageTypesConflict\) to validate type integrity at runtime.
packages/bus-messages/src · high confidence
Transactional outbox support with durable key encoding and session access
The MongoDB persistence provider now supports a durable transactional outbox via \withOutbox()\, ensuring that workflow state changes and outgoing messages are committed atomically. This requires MongoDB to run on a replica set or sharded cluster; the provider now throws a \ReplicaSetRequired\ error if this constraint is not met. To enable handlers to write custom data within the same transaction, a new \mongoSession(ctx)\ accessor is exposed, along with \mongoTestSession\ for unit testing. Additionally, the persistence layer now safely encodes MongoDB field names (escaping \$\, \.\, and \%\) to prevent errors with complex workflow state keys, and exports \WorkflowStateNotFound\ and \ReplicaSetRequired\ errors for better error handling.
packages/bus-mongodb/src · high confidence
Behavioural changes
Migrate CI to CircleCI 2.1 with pnpm, Node 24, and changeset-driven releases
The CI pipeline has been upgraded from CircleCI 2 to 2.1, switching the runtime from Node 8.14.1 to Node 24.11.1 and replacing Yarn with pnpm 12.4.1. The workflow now includes a dedicated build job that runs unit and integration tests against MongoDB, PostgreSQL, RabbitMQ, and LocalStack, alongside a docs job for type-checking and building documentation. Deployment behavior has changed to use changesets: the pipeline now checks for pending changesets before publishing, uses \pnpm changeset publish\ instead of the previous npm script, and automatically creates GitHub Releases for each published package using a new helper script.
.circleci · high confidence
RabbitMQ transport now supports connection recovery and resource permission checks
The RabbitMQ transport now automatically reconnects when the connection or channel to the broker is lost, configurable via \connectionRecovery\ settings (enabled, initialDelay, maxDelay, factor, jitter, maxRetries). It also validates that the user has the necessary permissions to check for the existence of exchanges and queues, throwing \RabbitMqResourceCheckRefused\ if access is denied, or allowing users to disable these checks with \withResourceVerification(false)\. Additionally, the transport now throws \RabbitMqConnectionRecoveryFailed\ if it gives up reconnecting.
packages/bus-rabbitmq/src · high confidence
Removal of Inversify-based WorkflowData base class
The \WorkflowData\ abstract class, which previously served as the base for defining workflow state and relied on Inversify's \@injectable\ decorator, has been removed from the \packages/bus-workflow/src/workflow\ module. This change eliminates the hard dependency on Inversify for workflow data definitions, simplifying the API for users who define workflow states.
packages/bus-workflow/src/workflow · high confidence
Removal of Inversify-based workflow module scaffolding
The workflow module scaffolding that relied on Inversify for dependency injection has been removed. Specifically, the \WorkflowModule\ class, the \workflow-symbols\ registry, and the main \index.ts\ barrel exports have been deleted from the \packages/bus-workflow/src\ directory, eliminating the hard dependency on Inversify for this component.
packages/bus-workflow/src · high confidence
SQS transport now supports configurable visibility timeout, wait time, and dead-letter queue settings
The SQS transport configuration now exposes \visibilityTimeout\ (default 30s), \waitTimeSeconds\ (default 10s), and \maxReceiveCount\ (default 15) to allow fine-tuning of queue polling and retry behavior. Users can also configure the dead-letter queue via \deadLetterQueueName\ or \deadLetterQueueArn\, set a custom \messageRetentionPeriod\ (default 14 days), and provide a custom \queuePolicy\ or enable \verifyQueuePolicy\ to ensure SNS delivery permissions are correctly applied during provisioning.
packages/bus-sqs/src · high confidence
Structured error handling and handler context for message processing
The bus now provides a dedicated \HandlerContext\ passed to all handlers, enabling them to send, publish, reply, fail, or return messages without capturing the bus instance. This context supports request-reply patterns via \ctx.reply()\ and explicit message lifecycle control via \ctx.failMessage()\ and \ctx.returnMessage()\. To support these operations, the bus introduces specific error classes (\ReplyOutsideHandlingContext\, \ReturnAddressMissing\, \DelayedReplyNotSupported\, \FailMessageOutsideHandlingContext\) that provide clear guidance when these methods are misused. Additionally, a \ContainerAdapter\ interface allows DI containers to resolve class-based handlers, with \ClassHandlerNotResolved\ and \ContainerNotRegistered\ errors providing actionable feedback when resolution fails.
packages/bus-core/src · high confidence
Switch pre-commit hook to use pnpm
The pre-commit hook now executes formatting tasks using pnpm instead of the previous package manager. This change aligns the repository's development workflow with the migration from yarn to pnpm, ensuring that code formatting checks run correctly via the new tooling.
.husky · high confidence
Test coverage
Added package validation tool to verify ESM/CJS exports; Added test coverage for MongoDB bus persistence; Added test fixtures for the message-type generator and CLI provisioning; Added test infrastructure for message serialization and dead-letter handling; Added test infrastructure for the PostgreSQL bus adapter; New integration test suite for bus persistence and transport guarantees; Suppresses internal bus logs during test runs.
Dependencies
Migrate from Yarn to pnpm and upgrade to Node 24
The monorepo has switched its package manager from Yarn to pnpm (v12.4.1), replacing the root yarn.lock and individual package yarn.lock files with a single pnpm-lock.yaml. This migration is accompanied by a runtime requirement bump to Node.js \>=24 and a TypeScript upgrade to v6.0.3. Additionally, the build tooling has shifted from Lerna to pnpm workspaces, and the root package.json now includes ESLint, Prettier, and Husky for linting and formatting.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 53 → 60 (+7.2)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 77 → 77 (-0.0)
- Architecture 60 → 60 (+0.2)
- Maturity 44 → 64 (+20.4)
- Readiness 55 → 55 (+0.1)
- Security 63 → 64 (+0.9)
- Performance 85 → 85 (+0.0)
Resolved (92)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/handler/default-handler-registry.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/handler/handler-for.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/handler/handler-for.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/handler/handler-registry.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/handler/handler.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/service-bus/bus-configuration.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/service-bus/bus-configuration.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/testing/recorded-messages.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/testing/recorded-messages.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/testing/recorded-messages.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/define-workflow.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/define-workflow.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/define-workflow.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/define-workflow.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/define-workflow.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/error/workflow-already-handles-message.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/error/workflow-already-handles-message.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/error/workflow-already-started-by-message.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/error/workflow-already-started-by-message.ts)
- Cross-context type MessageDeclaration (bus-messages → bus-core) (packages/bus-core/src/workflow/error/workflow-does-not-handle-message.ts)
- …and 72 more
New (15)
- Low CVE: [GHSA redacted] (pnpm-lock.yaml)
- Medium CVE: [GHSA redacted] (pnpm-lock.yaml)
- Medium CVE: [GHSA redacted] (pnpm-lock.yaml)
- Medium CVE: [GHSA redacted] (pnpm-lock.yaml)
- Medium CVE: [GHSA redacted] (pnpm-lock.yaml)
- Outdated (npm): amqplib
- Outdated (npm): mongodb
- Outdated (npm): tslib
- Pass-through layer (docs/snippets/serializers.ts)
- Projects may be oversized for their cohesion
- doc comments repeat the names (packages/bus-cli/src/provision/provision-report.ts)
- doc comments repeat the names (packages/bus-core/src/handler/error/message-name-inherited.ts)
- doc comments repeat the names (packages/bus-messages/src/message-declaration.ts)
- doc comments repeat the names (packages/bus-nestjs/src/create-bus-for-provisioning.ts)
- redundant comment (packages/bus-mongodb/src/mongodb-persistence.ts)
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
node-ts/bus 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.
About this page
- The score is its most recent published measurement, taken on 9 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 6526bac7b856a8ad482e848412e9fac6492e460e — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-bb0cb800cd0f.