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

package/README.md

@@ -5,40 +5,185 @@
 
 # Nimbus Core
 
-The core package of the Nimbus framework.
+The core package of the Nimbus framework — a small, [CloudEvents](https://cloudevents.io/)-based CQRS toolkit for TypeScript. It provides typed **Commands**, **Queries** and **Events**, a validating **Router** and an in-process **EventBus** with retries and OpenTelemetry instrumentation.
 
 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/core
+
+# NPM
+npm install @nimbus-cqrs/core
+
+# Bun
+bun add @nimbus-cqrs/core
+```
+
 # Examples
 
-These are some quick examples on how the basics of the Nimbus framework work.
+The snippets below walk through a tiny "todo" domain so you can see how the core building blocks fit together. Each example is runnable on its own.
 
 For detailed documentation, please refer to the [Nimbus documentation](https://nimbus.overlap.at).
 
 ## Command
 
-```typescript
+A **Command** asks the system to *do* something (a write). You declare a [Zod](https://zod.dev/) schema that extends Nimbus' built-in `commandSchema`, write a handler, and register both on the router. Incoming messages are validated against the schema before they reach your handler.
 
+```typescript
+import {
+    commandSchema,
+    createCommand,
+    getRouter,
+} from '@nimbus-cqrs/core';
+import { z } from 'zod';
+
+const ADD_TODO = 'com.example.todo.add';
+
+const addTodoSchema = commandSchema.extend({
+    type: z.literal(ADD_TODO),
+    data: z.object({
+        title: z.string().min(1),
+    }),
+});
+type AddTodoCommand = z.infer<typeof addTodoSchema>;
+
+const handleAddTodo = async (cmd: AddTodoCommand) => {
+    // ...persist the todo here...
+    return { id: 'todo-1', title: cmd.data.title, status: 'open' };
+};
+
+const router = getRouter();
+router.register(ADD_TODO, handleAddTodo, addTodoSchema);
+
+const result = await router.route(
+    createCommand<AddTodoCommand>({
+        type: ADD_TODO,
+        source: 'https://app.example.com',
+        data: { title: 'Write the README' },
+    }),
+);
+
+console.log(result);
+// { id: 'todo-1', title: 'Write the README', status: 'open' }
 ```
 
+`createCommand` fills in the boilerplate CloudEvents fields (`id`, `correlationid`, `time`, …) for you, so you only specify the parts that matter to your domain.
+
 ## Query
 
-```typescript
+A **Query** asks the system to *read* something. Mechanically it is identical to a Command — same router, same validation, same shape — only the intent differs.
 
+```typescript
+import { createQuery, getRouter, querySchema } from '@nimbus-cqrs/core';
+import { z } from 'zod';
+
+const GET_TODO = 'com.example.todo.get';
+
+const getTodoSchema = querySchema.extend({
+    type: z.literal(GET_TODO),
+    data: z.object({ id: z.string() }),
+});
+type GetTodoQuery = z.infer<typeof getTodoSchema>;
+
+const handleGetTodo = async (q: GetTodoQuery) => {
+    // ...load the todo from your read model...
+    return { id: q.data.id, title: 'Write the README', status: 'open' };
+};
+
+const router = getRouter();
+router.register(GET_TODO, handleGetTodo, getTodoSchema);
+
+const todo = await router.route(
+    createQuery<GetTodoQuery>({
+        type: GET_TODO,
+        source: 'https://app.example.com',
+        data: { id: 'todo-1' },
+    }),
+);
 ```
 
 ## Event
 
-```typescript
+An **Event** announces that something *has happened*. Events are published to the in-process EventBus, which delivers them to every matching subscriber asynchronously, with exponential-backoff retries on handler errors and built-in OpenTelemetry traces and metrics.
 
+```typescript
+import {
+    createEvent,
+    eventSchema,
+    getEventBus,
+} from '@nimbus-cqrs/core';
+import { z } from 'zod';
+
+const TODO_ADDED = 'com.example.todo.added';
+
+const todoAddedSchema = eventSchema.extend({
+    type: z.literal(TODO_ADDED),
+    data: z.object({
+        id: z.string(),
+        title: z.string(),
+    }),
+});
+type TodoAddedEvent = z.infer<typeof todoAddedSchema>;
+
+const eventBus = getEventBus();
+
+eventBus.subscribeEvent<TodoAddedEvent>({
+    type: TODO_ADDED,
+    handler: async (event) => {
+        console.log(`New todo added: ${event.data.title}`);
+    },
+    onError: (error, event) => {
+        console.error(`Failed to handle ${event.id} after retries`, error);
+    },
+});
+
+eventBus.putEvent(
+    createEvent<TodoAddedEvent>({
+        type: TODO_ADDED,
+        source: 'https://app.example.com',
+        subject: '/todos/todo-1',
+        data: { id: 'todo-1', title: 'Write the README' },
+    }),
+);
 ```
 
+A typical flow is to publish an event from inside a command handler once the write has succeeded — that's how reads, side effects and integrations stay decoupled from the command path.
+
 ## Router
 
-```typescript
+A typical app configures a single named router at startup with cross-cutting concerns (logging, correlation IDs, …) and then resolves it from anywhere via `getRouter()`.
 
+```typescript
+import { getLogger, getRouter, setupRouter } from '@nimbus-cqrs/core';
+
+setupRouter('default', {
+    logInput: (input) => {
+        getLogger().debug({
+            category: 'Router',
+            message: `Routing ${input.type}`,
+            correlationId: input.correlationid,
+        });
+    },
+    logOutput: (output) => {
+        getLogger().debug({
+            category: 'Router',
+            message: 'Handler completed',
+            data: { output },
+        });
+    },
+});
+
+// Anywhere else in your app:
+const router = getRouter('default');
+router.register(/* type, handler, schema */);
+await router.route(/* command or query */);
 ```
 
+You can have multiple named routers (for example one per transport) by calling `setupRouter` with different names and resolving them with `getRouter('<name>')`.
+
 # License
 
 Copyright 2024-present Overlap GmbH & Co KG (https://overlap.at)

package/esm/lib/eventBus/eventBus.d.ts

@@ -67,7 +67,7 @@ export type SubscribeEventInput<TEvent extends Event> = {
  *
  * @example
  * ```ts
- * import { createEvent, NimbusEventBus } from '@nimbus/core';
+ * import { createEvent, NimbusEventBus } from '@nimbus-cqrs/core';
  *
  * const eventBus = new NimbusEventBus({
  *     name: 'orders',
@@ -131,7 +131,7 @@ export declare class NimbusEventBus {
      *
      * @example
      * ```ts
-     * import { getLogger, NimbusEventBus } from '@nimbus/core';
+     * import { getLogger, NimbusEventBus } from '@nimbus-cqrs/core';
      *
      * const eventBus = new NimbusEventBus({
      *     name: 'orders',
@@ -162,7 +162,7 @@ export declare class NimbusEventBus {
      *
      * @example
      * ```ts
-     * import { createEvent, getEventBus } from '@nimbus/core';
+     * import { createEvent, getEventBus } from '@nimbus-cqrs/core';
      *
      * const eventBus = getEventBus('default');
      *
@@ -206,7 +206,7 @@ export declare class NimbusEventBus {
      *
      * @example
      * ```ts
-     * import { getEventBus, getLogger } from '@nimbus/core';
+     * import { getEventBus, getLogger } from '@nimbus-cqrs/core';
      *
      * const eventBus = getEventBus('default');
      *
@@ -268,7 +268,7 @@ export declare class NimbusEventBus {
  *
  * @example
  * ```ts
- * import { getLogger, setupEventBus } from '@nimbus/core';
+ * import { getLogger, setupEventBus } from '@nimbus-cqrs/core';
  *
  * // At application startup, configure the event bus with all options
  * setupEventBus('default', {
@@ -300,7 +300,7 @@ export declare const setupEventBus: (name: string, options?: Omit<NimbusEventBus
  *
  * @example
  * ```ts
- * import { createEvent, getEventBus } from '@nimbus/core';
+ * import { createEvent, getEventBus } from '@nimbus-cqrs/core';
  *
  * // Get the event bus configured earlier with setupEventBus
  * const eventBus = getEventBus('default');

package/esm/lib/eventBus/eventBus.js

@@ -32,7 +32,7 @@ const eventSizeBytes = meter.createHistogram('eventbus_event_size_bytes', {
  *
  * @example
  * ```ts
- * import { createEvent, NimbusEventBus } from '@nimbus/core';
+ * import { createEvent, NimbusEventBus } from '@nimbus-cqrs/core';
  *
  * const eventBus = new NimbusEventBus({
  *     name: 'orders',
@@ -96,7 +96,7 @@ export class NimbusEventBus {
      *
      * @example
      * ```ts
-     * import { getLogger, NimbusEventBus } from '@nimbus/core';
+     * import { getLogger, NimbusEventBus } from '@nimbus-cqrs/core';
      *
      * const eventBus = new NimbusEventBus({
      *     name: 'orders',
@@ -135,7 +135,7 @@ export class NimbusEventBus {
      *
      * @example
      * ```ts
-     * import { createEvent, getEventBus } from '@nimbus/core';
+     * import { createEvent, getEventBus } from '@nimbus-cqrs/core';
      *
      * const eventBus = getEventBus('default');
      *
@@ -223,7 +223,7 @@ export class NimbusEventBus {
      *
      * @example
      * ```ts
-     * import { getEventBus, getLogger } from '@nimbus/core';
+     * import { getEventBus, getLogger } from '@nimbus-cqrs/core';
      *
      * const eventBus = getEventBus('default');
      *
@@ -404,7 +404,7 @@ const eventBusRegistry = new Map();
  *
  * @example
  * ```ts
- * import { getLogger, setupEventBus } from '@nimbus/core';
+ * import { getLogger, setupEventBus } from '@nimbus-cqrs/core';
  *
  * // At application startup, configure the event bus with all options
  * setupEventBus('default', {
@@ -438,7 +438,7 @@ export const setupEventBus = (name, options) => {
  *
  * @example
  * ```ts
- * import { createEvent, getEventBus } from '@nimbus/core';
+ * import { createEvent, getEventBus } from '@nimbus-cqrs/core';
  *
  * // Get the event bus configured earlier with setupEventBus
  * const eventBus = getEventBus('default');

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

@@ -85,7 +85,7 @@ export type LogRecord = {
  *     parseLogLevel,
  *     prettyLogFormatter,
  *     setupLogger,
- * } from '@nimbus/core';
+ * } from '@nimbus-cqrs/core';
  *
  * // Configure the logger at application startup
  * setupLogger({
@@ -145,7 +145,7 @@ export declare class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().debug({
      *     message: 'Hello World!',
@@ -171,7 +171,7 @@ export declare class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().info({
      *     message: 'Hello World!',
@@ -197,7 +197,7 @@ export declare class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().warn({
      *     message: 'Hello World!',
@@ -223,7 +223,7 @@ export declare class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().error({
      *     message: 'Hello World!',
@@ -249,7 +249,7 @@ export declare class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().critical({
      *     message: 'Hello World!',
@@ -310,7 +310,7 @@ export declare class Logger {
  *     parseLogLevel,
  *     prettyLogFormatter,
  *     setupLogger,
- * } from "@nimbus/core";
+ * } from "@nimbus-cqrs/core";
  *
  * setupLogger({
  *     logLevel: parseLogLevel(process.env.LOG_LEVEL),
@@ -333,7 +333,7 @@ export declare const setupLogger: (options: LogOptions) => void;
  *
  * @example
  * ```ts
- * import { getLogger } from '@nimbus/core';
+ * import { getLogger } from '@nimbus-cqrs/core';
  *
  * const logger = getLogger();
  *

package/esm/lib/log/logger.js

@@ -18,7 +18,7 @@ import { defaultLogOptions } from './options.js';
  *     parseLogLevel,
  *     prettyLogFormatter,
  *     setupLogger,
- * } from '@nimbus/core';
+ * } from '@nimbus-cqrs/core';
  *
  * // Configure the logger at application startup
  * setupLogger({
@@ -90,7 +90,7 @@ export class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().debug({
      *     message: 'Hello World!',
@@ -120,7 +120,7 @@ export class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().info({
      *     message: 'Hello World!',
@@ -150,7 +150,7 @@ export class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().warn({
      *     message: 'Hello World!',
@@ -180,7 +180,7 @@ export class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().error({
      *     message: 'Hello World!',
@@ -210,7 +210,7 @@ export class Logger {
      *
      * @example
      * ```ts
-     * import { getLogger } from "@nimbus/core";
+     * import { getLogger } from "@nimbus-cqrs/core";
      *
      * getLogger().critical({
      *     message: 'Hello World!',
@@ -324,7 +324,7 @@ export class Logger {
  *     parseLogLevel,
  *     prettyLogFormatter,
  *     setupLogger,
- * } from "@nimbus/core";
+ * } from "@nimbus-cqrs/core";
  *
  * setupLogger({
  *     logLevel: parseLogLevel(process.env.LOG_LEVEL),
@@ -349,7 +349,7 @@ export const setupLogger = (options) => {
  *
  * @example
  * ```ts
- * import { getLogger } from '@nimbus/core';
+ * import { getLogger } from '@nimbus-cqrs/core';
  *
  * const logger = getLogger();
  *

package/esm/lib/message/router.d.ts

@@ -40,7 +40,7 @@ type ZodSchema<T = any> = z.ZodType<T>;
  *
  * @example
  * ```ts
- * import { createCommand, MessageRouter } from '@nimbus/core';
+ * import { createCommand, MessageRouter } from '@nimbus-cqrs/core';
  *
  * const messageRouter = new MessageRouter({
  *     name: 'api',
@@ -92,7 +92,7 @@ export declare class MessageRouter {
      *
      * @example
      * ```ts
-     * import { commandSchema, type Command, getRouter } from '@nimbus/core';
+     * import { commandSchema, type Command, getRouter } from '@nimbus-cqrs/core';
      * import { z } from 'zod';
      *
      * // Define the command type and schema
@@ -133,7 +133,7 @@ export declare class MessageRouter {
      *
      * @example
      * ```ts
-     * import { createCommand, getRouter } from '@nimbus/core';
+     * import { createCommand, getRouter } from '@nimbus-cqrs/core';
      *
      * const router = getRouter('default');
      *
@@ -169,7 +169,7 @@ export declare class MessageRouter {
  *
  * @example
  * ```ts
- * import { getLogger, setupRouter } from '@nimbus/core';
+ * import { getLogger, setupRouter } from '@nimbus-cqrs/core';
  *
  * // At application startup, configure the router with all options
  * setupRouter('default', {
@@ -204,7 +204,7 @@ export declare const setupRouter: (name: string, options?: Omit<MessageRouterOpt
  *
  * @example
  * ```ts
- * import { createCommand, getRouter } from '@nimbus/core';
+ * import { createCommand, getRouter } from '@nimbus-cqrs/core';
  *
  * // Get the router configured earlier with setupRouter
  * const router = getRouter('default');

package/esm/lib/message/router.js

@@ -19,7 +19,7 @@ const routingDuration = meter.createHistogram('router_routing_duration_seconds',
  *
  * @example
  * ```ts
- * import { createCommand, MessageRouter } from '@nimbus/core';
+ * import { createCommand, MessageRouter } from '@nimbus-cqrs/core';
  *
  * const messageRouter = new MessageRouter({
  *     name: 'api',
@@ -76,7 +76,7 @@ export class MessageRouter {
      *
      * @example
      * ```ts
-     * import { commandSchema, type Command, getRouter } from '@nimbus/core';
+     * import { commandSchema, type Command, getRouter } from '@nimbus-cqrs/core';
      * import { z } from 'zod';
      *
      * // Define the command type and schema
@@ -126,7 +126,7 @@ export class MessageRouter {
      *
      * @example
      * ```ts
-     * import { createCommand, getRouter } from '@nimbus/core';
+     * import { createCommand, getRouter } from '@nimbus-cqrs/core';
      *
      * const router = getRouter('default');
      *
@@ -233,7 +233,7 @@ const routerRegistry = new Map();
  *
  * @example
  * ```ts
- * import { getLogger, setupRouter } from '@nimbus/core';
+ * import { getLogger, setupRouter } from '@nimbus-cqrs/core';
  *
  * // At application startup, configure the router with all options
  * setupRouter('default', {
@@ -270,7 +270,7 @@ export const setupRouter = (name, options) => {
  *
  * @example
  * ```ts
- * import { createCommand, getRouter } from '@nimbus/core';
+ * import { createCommand, getRouter } from '@nimbus-cqrs/core';
  *
  * // Get the router configured earlier with setupRouter
  * const router = getRouter('default');

package/esm/lib/tracing/withSpan.d.ts

@@ -31,7 +31,7 @@ export type WithSpanOptions = {
  *
  * @example
  * ```ts
- * import { withSpan } from '@nimbus/core';
+ * import { withSpan } from '@nimbus-cqrs/core';
  *
  * const fetchUser = withSpan(
  *     {

package/esm/lib/tracing/withSpan.js

@@ -10,7 +10,7 @@ import { context, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
  *
  * @example
  * ```ts
- * import { withSpan } from '@nimbus/core';
+ * import { withSpan } from '@nimbus-cqrs/core';
  *
  * const fetchUser = withSpan(
  *     {

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@nimbus-cqrs/core",
-  "version": "2.0.0-beta.0",
-  "description": "Core building blocks of the Nimbus CQRS framework.",
+  "version": "2.0.2",
+  "description": "Simplify Event-Driven Applications - Core building blocks of the Nimbus framework.",
+  "keywords": [
+    "nimbus",
+    "cqrs",
+    "event-sourcing",
+    "event-driven",
+    "typescript",
+    "command",
+    "query",
+    "event"
+  ],
   "author": "Daniel Gördes <d.goerdes@overlap.at> (https://overlap.at)",
   "homepage": "https://nimbus.overlap.at",
   "repository": {