Knowledge Catalog

This catalog maps the ten HeronJS 4.0.0 packages to their responsibilities, source submodules, and usage guides. Use it to identify which package owns a capability before selecting an API or reading its implementation.

Scope: submodules below are feature directories under packages/<package>/src. They describe source organization, not additional npm packages or supported import paths. Import public APIs from package entrypoints. The documented @heronjs/common/thread entrypoint provides the worker-local DI bridge.

For concepts and lifecycle rules, read Framework Knowledge. For package dependencies and submodule ownership, see the Knowledge Graph.

Package index

Package	Responsibility	Guide
`@heronjs/common`	Shared contracts and dependency injection	Usage guide
`@heronjs/core`	Application composition and resource ownership	Usage guide
`@heronjs/thread`	Worker execution and scheduling	Usage guide
`@heronjs/express`	HTTP routing and request handling	Usage guide
`@heronjs/gql`	GraphQL schemas and resolvers	Usage guide
`@heronjs/ebs`	Message publishing and consumption	Usage guide
`@heronjs/websocket`	Connections and event handlers	Usage guide
`@heronjs/trpc`	Procedure endpoints and subscriptions	Usage guide
`@heronjs/mcp`	Tools, resources, and prompt catalogs	Usage guide
`@heronjs/acp`	Agent endpoints and session execution	Usage guide

common

@heronjs/common — Shared contracts and dependency injection. Usage guide · Release source .

Source submodule	Responsibility
`di`	Containers, typed tokens, provider registration, scopes, and injection decorators.
`metadata`	Typed metadata keys, reflection access, and metadata decorators.
`modules`	Module declarations, component metadata, and registry contracts.
`lifecycle`	Shared lifecycle and resource-disposal contracts.
`protocols`	Protocol-neutral extension and HTTP contracts.
`security`	Authentication contracts and shared guard evaluation.
`services`	Service declarations, modes, and lifecycle-hook metadata.
`cache`	Cache configuration, store contracts, and caching metadata.
`persistence`	Datasource configuration, persistence contracts, and declarations.
`messaging`	Command, query, event, and messaging contracts.
`configuration`	Explicit environment and configuration access.
`collections`	Collection types and data structures.
`validation`	Runtime type predicates and validation helpers.
`resilience`	Rate-limiter and circuit-breaker configuration and metadata.
`errors`	Framework error types, codes, and error contracts.
`logging`	Logger configuration, reviewed events, and redaction.
`integrations`	Framework integration contracts and bridges: `datetime`, `tracing`, and `thread`.

core

@heronjs/core — Application composition and resource ownership. Usage guide · Release source .

Source submodule	Responsibility
`application`	Application creation, context, runtime selection, and configuration.
`modules`	Module traversal, metadata snapshots, and registration plans.
`lifecycle`	Lifecycle execution and owned cleanup.
`extensions`	Protocol-extension composition and lifecycle coordination.
`http`	The shared HTTP host and listener ownership.
`services`	Execution of initialization, interval, and daemon services.
`cache`	Cache resource creation and `memory`, `redis`, and `disk` stores.
`datasources`	SQL connection ownership and standalone, tenant, and repository implementations.
`cqrs`	Application-owned command, query, and event execution.
`errors`	Core-specific error handling.

thread

@heronjs/thread — Worker execution and scheduling. Usage guide · Release source .

Source submodule	Responsibility
`execution`	Reactive result normalization and execution utilities.
`protocol`	Worker message contracts, validation, and parent/worker communication.
`pools`	Bounded job queues and worker-pool scheduling.
`runtime`	Worker bootstrap, task execution, and dedicated worker services.
`metadata`	Worker task and service metadata.
`errors`	Worker execution and lifecycle errors.

express

@heronjs/express — HTTP routing and request handling. Usage guide · Release source .

Source submodule	Responsibility
`routing`	Controller routes, HTTP methods, route options, and server registration.
`parameters`	Request parameter binding and route interceptors.
`security`	HTTP authentication and authorization integration.
`runtime`	HTTP adapter execution, native hooks, plugins, and configuration.
`metadata`	HTTP route and controller metadata.

gql

@heronjs/gql — GraphQL schemas and resolvers. Usage guide · Release source .

Source submodule	Responsibility
`schema`	Schema declarations and schema construction.
`resolvers`	Resolver discovery, parameter binding, and execution.
`security`	GraphQL authorization integration.
`runtime`	GraphQL extension and HTTP adapter lifecycle.
`metadata`	Schema and resolver metadata.
`errors`	GraphQL-specific errors and response formatting.

ebs

@heronjs/ebs — Message publishing and consumption. Usage guide · Release source .

Source submodule	Responsibility
`subscriptions`	Consumer and stream declarations, handler discovery, and parameter binding.
`publishers`	Message publishing and stream publishing.
`transports`	HeronJS transport implementations: `kafka`, `nats`, and `amqp`.
`metadata`	Messaging declaration metadata.
`enums`	Messaging-specific enumerations.
`errors`	Messaging and transport errors.

websocket

@heronjs/websocket — Connections and event handlers. Usage guide · Release source .

Source submodule	Responsibility
`handlers`	Event and lifecycle decorators, parameter binding, and handler execution.
`connections`	Connection state and peer operations.
`runtime`	WebSocket extension lifecycle, upgrades, and server integration.
`metadata`	Namespace and handler metadata.
`errors`	WebSocket-specific errors.

trpc

@heronjs/trpc — Procedure endpoints and subscriptions. Usage guide · Release source .

Source submodule	Responsibility
`procedures`	Procedure declarations, validation, and endpoint grouping.
`security`	Procedure authorization.
`runtime`	Router construction, HTTP integration, and subscription lifecycle.
`metadata`	Procedure and endpoint metadata.
`errors`	Procedure and transport errors.

mcp

@heronjs/mcp — Tools, resources, and prompt catalogs. Usage guide · Release source .

Source submodule	Responsibility
`catalog`	Tool, resource, and prompt declarations and catalog construction.
`endpoints`	Independent catalog endpoints and endpoint configuration.
`transports`	HTTP and stdio transport integration.
`metadata`	Catalog and handler metadata.
`errors`	MCP-specific errors.

acp

@heronjs/acp — Agent endpoints and session execution. Usage guide · Release source .

Source submodule	Responsibility
`agents`	Agent declarations, session contracts, and agent execution.
`endpoints`	Independent agent endpoints and endpoint configuration.
`transports`	HTTP and stdio transport integration.
`metadata`	Agent declaration metadata.
`errors`	ACP-specific errors.

Selecting a capability

Requirement	Start with
Compose an application and manage resource cleanup	`core` and `common`
Declare modules and inject providers	`common/modules` and `common/di`
Implement an HTTP API	`express/routing` and `express/parameters`
Add a schema or procedure API	`gql/schema`, `gql/resolvers`, or `trpc/procedures`
Handle realtime connections	`websocket/handlers` and `websocket/connections`
Publish or consume broker messages	`ebs/publishers`, `ebs/subscriptions`, and `ebs/transports`
Expose tools, resources, or prompts	`mcp/catalog` and `mcp/endpoints`
Implement an agent with sessions	`acp/agents` and `acp/endpoints`
Execute work in worker threads	`thread/pools`, `thread/runtime`, and the common worker bridge
Configure application data resources	`common/cache`, `common/persistence`, `core/cache`, and `core/datasources`

This inventory is verified against release commit cfb0ea5.