@nimbus-cqrs/hono 2.0.0-beta.0 → 2.0.2

package/README.md

@@ -5,10 +5,136 @@
 
 # Nimbus Hono
 
-Adapters and useful functionality to bridge Nimbus and [Hono](https://hono.dev/).
+Adapters and middleware that bridge [Hono](https://hono.dev/) and the Nimbus framework. The package gives your Hono app a correlation ID per request, structured request/response logging with OpenTelemetry tracing, and a single error handler that turns Nimbus exceptions into clean HTTP responses.
 
 Refer to the [Nimbus main repository](https://github.com/overlap-dev/Nimbus) or the [Nimbus documentation](https://nimbus.overlap.at) for more information about the Nimbus framework.
 
+## Install
+
+```bash
+# Deno
+deno add jsr:@nimbus-cqrs/hono
+
+# NPM
+npm install @nimbus-cqrs/hono
+
+# Bun
+bun add @nimbus-cqrs/hono
+```
+
+`hono` itself is a peer dependency — install it (or use one of the runtimes that ship it via `npm:`/`jsr:` specifiers).
+
+# Examples
+
+For detailed documentation, please refer to the [Nimbus documentation](https://nimbus.overlap.at).
+
+## Quick start
+
+A typical setup wires up all three pieces together: the correlation ID middleware first (so the logger and downstream handlers can read it), the logger second, your routes, and the error handler last.
+
+```typescript
+import { Hono } from 'hono';
+import { correlationId, handleError, logger } from '@nimbus-cqrs/hono';
+
+const app = new Hono();
+
+app.use(correlationId());
+app.use(logger({ enableTracing: true }));
+
+app.get('/hello', (c) => c.json({ hello: 'world' }));
+
+app.onError(handleError);
+
+export default app;
+```
+
+## correlationId
+
+`correlationId()` is a Hono middleware that ensures every request carries a stable correlation ID. It reads one from the incoming headers (`x-correlation-id`, `x-request-id` or `request-id`, in that order), or generates a fresh [ULID](https://github.com/ulid/spec) if none is present. The ID is stored on the Hono context and — by default — echoed back in the response as `x-correlation-id`.
+
+```typescript
+import { Hono } from 'hono';
+import { correlationId, getCorrelationId } from '@nimbus-cqrs/hono';
+
+const app = new Hono();
+
+app.use(correlationId());
+
+app.get('/whoami', (c) => {
+    const cid = getCorrelationId(c);
+    return c.json({ correlationId: cid });
+});
+```
+
+Use `getCorrelationId(c)` anywhere you have a Hono context (route handlers, downstream middleware, …) to forward the ID into log entries, outgoing requests, or messages you publish through Nimbus.
+
+You can opt out of the response header or rename it:
+
+```typescript
+app.use(correlationId({
+    addToResponseHeaders: true,
+    responseHeaderName: 'x-trace-id',
+}));
+```
+
+## logger
+
+`logger()` writes one structured log line when a request comes in and one when it leaves (with the elapsed time), using the Nimbus logger so every entry is automatically tagged with the current correlation ID.
+
+When `enableTracing` is on (default), it also:
+
+-   extracts W3C trace context (`traceparent` / `tracestate`) from incoming headers, so spans created in your handlers stitch into the upstream trace,
+-   creates a server span named `HTTP <METHOD> <PATH>` for each request,
+-   records `http.method`, `url.path`, `http.target`, `http.status_code` and the correlation ID as span attributes,
+-   marks the span as errored on `5xx`/`4xx` responses or thrown exceptions.
+
+```typescript
+import { Hono } from 'hono';
+import { correlationId, logger } from '@nimbus-cqrs/hono';
+
+const app = new Hono();
+
+app.use(correlationId());
+app.use(logger({
+    enableTracing: true,
+    tracerName: 'api',
+}));
+```
+
+Set `enableTracing: false` if you only want the request/response log lines and don't run an OpenTelemetry SDK.
+
+## handleError
+
+`handleError` is a drop-in handler for `app.onError(...)`. It maps any `Exception` thrown anywhere in the request pipeline (a Nimbus core exception or one of its subclasses such as `NotFoundException`, `InvalidInputException`, `UnauthorizedException`, `ForbiddenException`, …) to a JSON response using the exception's `statusCode`, `name`, `message` and optional `details`. Anything else falls back to a generic `500 INTERNAL_SERVER_ERROR` and is logged at `critical` level.
+
+```typescript
+import { Hono } from 'hono';
+import { NotFoundException } from '@nimbus-cqrs/core';
+import { handleError } from '@nimbus-cqrs/hono';
+
+const app = new Hono();
+
+app.get('/todos/:id', (c) => {
+    throw new NotFoundException('Todo not found', { id: c.req.param('id') });
+});
+
+app.onError(handleError);
+```
+
+A request to `/todos/42` then responds with HTTP `404` and body:
+
+```json
+{
+    "error": "NOT_FOUND",
+    "message": "Todo not found",
+    "details": {
+        "id": "42"
+    }
+}
+```
+
+This means your domain code can stay framework-agnostic — throw Nimbus exceptions where they belong (in command/query handlers) and the HTTP layer converts them consistently for you.
+
 # License
 
 Copyright 2024-present Overlap GmbH & Co KG (https://overlap.at)

package/esm/lib/middleware/correlationId.d.ts

@@ -33,7 +33,7 @@ export type CorrelationIdOptions = {
  * @example
  * ```ts
  * import { Hono } from 'hono';
- * import { correlationId, getCorrelationId } from '@nimbus/hono';
+ * import { correlationId, getCorrelationId } from '@nimbus-cqrs/hono';
  *
  * const app = new Hono();
  * app.use(correlationId());

package/esm/lib/middleware/correlationId.js

@@ -27,7 +27,7 @@ export const CORRELATION_ID_KEY = 'correlationId';
  * @example
  * ```ts
  * import { Hono } from 'hono';
- * import { correlationId, getCorrelationId } from '@nimbus/hono';
+ * import { correlationId, getCorrelationId } from '@nimbus-cqrs/hono';
  *
  * const app = new Hono();
  * app.use(correlationId());

package/esm/lib/middleware/logger.d.ts

@@ -27,7 +27,7 @@ export type LoggerOptions = {
  * @example
  * ```ts
  * import { Hono } from 'hono';
- * import { logger } from '@nimbus/hono';
+ * import { logger } from '@nimbus-cqrs/hono';
  *
  * const app = new Hono();
  * app.use(logger({ enableTracing: true }));

package/esm/lib/middleware/logger.js

@@ -1,4 +1,4 @@
-import { getLogger } from '../../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { getLogger } from '@nimbus-cqrs/core';
 import { context, propagation, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
 import { getCorrelationId } from './correlationId.js';
 const humanize = (times) => {
@@ -24,7 +24,7 @@ const time = (start) => {
  * @example
  * ```ts
  * import { Hono } from 'hono';
- * import { logger } from '@nimbus/hono';
+ * import { logger } from '@nimbus-cqrs/hono';
  *
  * const app = new Hono();
  * app.use(logger({ enableTracing: true }));

package/esm/lib/onError.d.ts

@@ -10,7 +10,7 @@ import type { HTTPResponseError } from 'hono/types';
  *
  * @example
  * ```ts
- * import { handleError } from '@nimbus/hono';
+ * import { handleError } from '@nimbus-cqrs/hono';
  *
  * const app = new Hono();
  * app.onError(handleError);

package/esm/lib/onError.js

@@ -1,4 +1,4 @@
-import { Exception, getLogger } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { Exception, getLogger } from '@nimbus-cqrs/core';
 /**
  * An error handler for Hono applications that maps
  * Nimbus exceptions to HTTP responses and handles
@@ -9,7 +9,7 @@ import { Exception, getLogger } from '../deps/jsr.io/@nimbus/core/2.0.0/src/inde
  *
  * @example
  * ```ts
- * import { handleError } from '@nimbus/hono';
+ * import { handleError } from '@nimbus-cqrs/hono';
  *
  * const app = new Hono();
  * app.onError(handleError);

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@nimbus-cqrs/hono",
-  "version": "2.0.0-beta.0",
-  "description": "Hono integration for the Nimbus CQRS framework.",
+  "version": "2.0.2",
+  "description": "Simplify Event-Driven Applications - Hono integration for the Nimbus framework.",
+  "keywords": [
+    "nimbus",
+    "cqrs",
+    "event-sourcing",
+    "event-driven",
+    "typescript",
+    "hono",
+    "http",
+    "middleware",
+    "api"
+  ],
   "author": "Daniel Gördes <d.goerdes@overlap.at> (https://overlap.at)",
   "homepage": "https://nimbus.overlap.at",
   "repository": {
@@ -26,7 +37,7 @@
     "@opentelemetry/api": "^1.9.1",
     "hono": "^4.12.14",
     "zod": "^4.3.6",
-    "@nimbus-cqrs/core": "^2.0.0-beta.0"
+    "@nimbus-cqrs/core": "^2.0.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"