@nimbus-cqrs/core 2.0.0-beta.0

package/esm/lib/log/logger.js

@@ -0,0 +1,394 @@
+import { blue, bold, red, yellow } from '../../deps/jsr.io/@std/fmt/1.0.10/colors.js';
+import { numericLogLevel } from './logLevel.js';
+import { defaultLogOptions } from './options.js';
+/**
+ * The Logger provides structured logging with configurable log levels, formatters, and console colors.
+ *
+ * The Logger is a singleton that should be configured once at application startup using
+ * {@link setupLogger}, then accessed throughout the application using {@link getLogger}.
+ *
+ * Log levels in order of severity: debug < info < warn < error < critical.
+ * Messages below the configured log level are silently ignored.
+ *
+ * @example
+ * ```ts
+ * import {
+ *     getLogger,
+ *     jsonLogFormatter,
+ *     parseLogLevel,
+ *     prettyLogFormatter,
+ *     setupLogger,
+ * } from '@nimbus/core';
+ *
+ * // Configure the logger at application startup
+ * setupLogger({
+ *     logLevel: parseLogLevel(process.env.LOG_LEVEL),
+ *     formatter: process.env.NODE_ENV === 'production'
+ *         ? jsonLogFormatter
+ *         : prettyLogFormatter,
+ *     useConsoleColors: process.env.NODE_ENV !== 'production',
+ * });
+ *
+ * // Use the logger throughout your application
+ * const logger = getLogger();
+ *
+ * logger.info({
+ *     message: 'Application started',
+ *     category: 'App',
+ *     data: { port: 3000, environment: 'production' },
+ * });
+ *
+ * logger.error({
+ *     message: 'Failed to connect to database',
+ *     category: 'Database',
+ *     error: new Error('Connection timeout'),
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ * ```
+ */
+export class Logger {
+    static _instance;
+    _logLevel;
+    _formatter;
+    _useConsoleColors;
+    constructor(options) {
+        this._logLevel = options.logLevel ?? defaultLogOptions.logLevel;
+        this._formatter = options.formatter ?? defaultLogOptions.formatter;
+        this._useConsoleColors = options.useConsoleColors ??
+            defaultLogOptions.useConsoleColors;
+    }
+    /**
+     * Configure the Logger.
+     *
+     * @param {LogOptions} options - The options for the Logger
+     * @param {LogLevel} options.logLevel - The log level to use for the Logger
+     * @param {LogFormatter} options.formatter - The formatter to use for the Logger
+     */
+    static configure(options) {
+        Logger._instance = new Logger(options);
+    }
+    /**
+     * Get the Logger instance.
+     *
+     * @returns {Logger} The Logger instance
+     */
+    static getInstance() {
+        if (!Logger._instance) {
+            Logger._instance = new Logger(defaultLogOptions);
+        }
+        return Logger._instance;
+    }
+    /**
+     * Log a message at the debug level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().debug({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    debug(logInput) {
+        if (numericLogLevel['debug'] >= numericLogLevel[this._logLevel]) {
+            this._log(logInput, 'debug', console.debug);
+        }
+    }
+    /**
+     * Log a message at the info level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().info({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    info(logInput) {
+        if (numericLogLevel['info'] >= numericLogLevel[this._logLevel]) {
+            this._log(logInput, 'info', console.info);
+        }
+    }
+    /**
+     * Log a message at the warn level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().warn({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    warn(logInput) {
+        if (numericLogLevel['warn'] >= numericLogLevel[this._logLevel]) {
+            this._log(logInput, 'warn', console.warn);
+        }
+    }
+    /**
+     * Log a message at the error level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().error({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    error(logInput) {
+        if (numericLogLevel['error'] >= numericLogLevel[this._logLevel]) {
+            this._log(logInput, 'error', console.error);
+        }
+    }
+    /**
+     * Log a message at the critical level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().critical({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    critical(logInput) {
+        if (numericLogLevel['critical'] >= numericLogLevel[this._logLevel]) {
+            this._log(logInput, 'critical', console.error);
+        }
+    }
+    /**
+     * Produce a log record.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {LogLevel} level - The log level
+     *
+     * @returns {LogRecord} The log record
+     */
+    _produceLogRecord(logInput, level) {
+        return {
+            timestamp: new Date(),
+            level,
+            category: logInput.category ?? 'Default',
+            message: logInput.message,
+            ...(logInput.data && { data: logInput.data }),
+            ...(logInput.error && { error: logInput.error }),
+            ...(logInput.correlationId &&
+                { correlationId: logInput.correlationId }),
+        };
+    }
+    /**
+     * Format a log record.
+     *
+     * @param {LogRecord} logRecord - The log record
+     *
+     * @returns {string} The formatted log record
+     */
+    _formatLogRecord(logRecord) {
+        return this._formatter(logRecord);
+    }
+    /**
+     * Colorize a string.
+     *
+     * @param {string} string - The string to colorize
+     * @param {LogLevel} logLevel - The log level to determine the color
+     *
+     * @returns {string} The colorized string
+     */
+    _colorizeString(string, logLevel) {
+        switch (logLevel) {
+            case 'info':
+                string = blue(string);
+                break;
+            case 'warn':
+                string = yellow(string);
+                break;
+            case 'error':
+                string = red(string);
+                break;
+            case 'critical':
+                string = bold(red(string));
+                break;
+            default:
+                break;
+        }
+        return string;
+    }
+    /**
+     * Log a message.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {LogLevel} logLevel - The log level
+     * @param {Function} logFunction - The log function
+     */
+    _log(logInput, logLevel, logFunction) {
+        const logRecord = this._produceLogRecord(logInput, logLevel);
+        const formattedLogRecord = this._formatLogRecord(logRecord);
+        if (Array.isArray(formattedLogRecord)) {
+            if (this._useConsoleColors) {
+                const coloredLogs = formattedLogRecord.map((log) => this._colorizeString(log, logLevel));
+                logFunction(...coloredLogs);
+            }
+            else {
+                logFunction(...formattedLogRecord);
+            }
+        }
+        else if (this._useConsoleColors) {
+            logFunction(this._colorizeString(formattedLogRecord, logLevel));
+        }
+        else {
+            logFunction(formattedLogRecord);
+        }
+    }
+}
+/**
+ * Configure the Logger.
+ *
+ * @param {LogOptions} options - The options for the Logger
+ *
+ * @example
+ * ```ts
+ * import {
+ *     jsonLogFormatter,
+ *     parseLogLevel,
+ *     prettyLogFormatter,
+ *     setupLogger,
+ * } from "@nimbus/core";
+ *
+ * setupLogger({
+ *     logLevel: parseLogLevel(process.env.LOG_LEVEL),
+ *     formatter:
+ *         process.env.NODE_ENV === "development"
+ *             ? prettyLogFormatter
+ *             : jsonLogFormatter,
+ *     useConsoleColors: process.env.NODE_ENV === "development",
+ * });
+ * ```
+ */
+export const setupLogger = (options) => {
+    Logger.configure(options);
+};
+/**
+ * Get the Logger instance.
+ *
+ * Returns the singleton Logger instance. If the logger has not been configured
+ * via {@link setupLogger}, a default logger with silent log level is returned.
+ *
+ * @returns The Logger instance.
+ *
+ * @example
+ * ```ts
+ * import { getLogger } from '@nimbus/core';
+ *
+ * const logger = getLogger();
+ *
+ * // Log at different levels with all available options
+ * logger.debug({
+ *     message: 'Processing request',
+ *     category: 'API',
+ *     data: { method: 'POST', path: '/orders' },
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ *
+ * logger.info({
+ *     message: 'Order created successfully',
+ *     category: 'Orders',
+ *     data: { orderId: '12345', customerId: '67890' },
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ *
+ * logger.warn({
+ *     message: 'Rate limit approaching',
+ *     category: 'API',
+ *     data: { currentRate: 95, maxRate: 100 },
+ * });
+ *
+ * logger.error({
+ *     message: 'Failed to process payment',
+ *     category: 'Payments',
+ *     data: { orderId: '12345' },
+ *     error: new Error('Payment gateway timeout'),
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ *
+ * logger.critical({
+ *     message: 'Database connection lost',
+ *     category: 'Database',
+ *     error: new Error('Connection refused'),
+ * });
+ * ```
+ */
+export const getLogger = () => {
+    return Logger.getInstance();
+};

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

@@ -0,0 +1,34 @@
+import { type LogFormatter } from './logFormatter.js';
+import type { LogLevel } from './logLevel.js';
+/**
+ * Configuration options for the Logger.
+ *
+ * Use these options with {@link setupLogger} to configure the logger at application startup.
+ */
+export type LogOptions = {
+    /**
+     * The minimum log level to output. Messages below this level are silently ignored.
+     * Levels in order of severity: debug < info < warn < error < critical.
+     * Defaults to 'silent' (no logs output).
+     */
+    logLevel?: LogLevel;
+    /**
+     * The formatter function used to convert LogRecord objects into output strings.
+     * Use `jsonLogFormatter` for structured JSON output (recommended for production),
+     * or `prettyLogFormatter` for human-readable output (recommended for development).
+     * Defaults to `jsonLogFormatter`.
+     */
+    formatter?: LogFormatter;
+    /**
+     * Whether to apply ANSI color codes to the console output based on log level.
+     * Set to true for colored output in development terminals.
+     * Set to false for production or when outputting to log aggregation systems.
+     * Defaults to false.
+     */
+    useConsoleColors?: boolean;
+};
+/**
+ * The default log options.
+ */
+export declare const defaultLogOptions: Required<LogOptions>;
+//# sourceMappingURL=options.d.ts.map

package/esm/lib/log/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/lib/log/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,UAAU,CAIlD,CAAC"}

package/esm/lib/log/options.js

@@ -0,0 +1,9 @@
+import { jsonLogFormatter } from './logFormatter.js';
+/**
+ * The default log options.
+ */
+export const defaultLogOptions = {
+    logLevel: 'silent',
+    formatter: jsonLogFormatter,
+    useConsoleColors: false,
+};

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

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+/**
+ * A command is a message that is sent to tell the system
+ * to perform an action. Typically commands come in via an API
+ * like HTTP POST requests, gRPC calls, or similar inbound traffic.
+ *
+ * Nimbus sticks to the CloudEvents specifications for all messages
+ * to make it easier to work with these messages across multiple systems.
+ *
+ * @see https://cloudevents.io/ for more information.
+ *
+ * @property {string} specversion - The version of the CloudEvents specification which the event uses.
+ * @property {string} id - A globally unique identifier of the event.
+ * @property {string} correlationid - A globally unique identifier that indicates a correlation to previous and subsequent messages.
+ * @property {string} time - The time when the command was created.
+ * @property {string} source - A URI reference that identifies the system that is constructing the command.
+ * @property {string} type - The type must follow the CloudEvents naming convention, which uses a reversed domain name as a namespace, followed by a domain-specific name.
+ * @property {string} subject - An identifier for an object or entity the command is about (optional).
+ * @property {TData} data - The actual data, containing the specific business payload.
+ * @property {string} datacontenttype - A MIME type that indicates the format that the data is in (optional).
+ * @property {string} dataschema - An absolute URL to the schema that the data adheres to (optional).
+ *
+ * @template TData - The type of the data.
+ *
+ * @example
+ * const submitOrderCommand: Command<SubmitOrderPayload> = {
+ *     specversion: '1.0',
+ *     id: '123',
+ *     correlationid: '456',
+ *     time: '2025-01-01T00:00:00Z',
+ *     source: 'https://nimbus.overlap.at',
+ *     type: 'at.overlap.nimbus.submit-order',
+ *     data: {
+ *         customerId: '666',
+ *         cartId: '123',
+ *     },
+ *     datacontenttype: 'application/json',
+ * };
+ */
+export type Command<TData = unknown> = {
+    specversion: '1.0';
+    id: string;
+    correlationid: string;
+    time: string;
+    source: string;
+    type: string;
+    subject?: string;
+    data: TData;
+    datacontenttype?: string;
+    dataschema?: string;
+};
+/**
+ * Type alias for the command data field schema.
+ */
+type CommandDataSchema = z.ZodUnion<[
+    z.ZodRecord<z.ZodString, z.ZodUnknown>,
+    z.ZodString,
+    z.ZodNumber,
+    z.ZodArray<z.ZodUnknown>,
+    z.ZodBoolean
+]>;
+/**
+ * Type alias for the command schema shape.
+ */
+export type CommandSchemaType = z.ZodObject<{
+    specversion: z.ZodLiteral<'1.0'>;
+    id: z.ZodString;
+    correlationid: z.ZodString;
+    time: z.ZodISODateTime;
+    source: z.ZodString;
+    type: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    data: CommandDataSchema;
+    datacontenttype: z.ZodOptional<z.ZodString>;
+    dataschema: z.ZodOptional<z.ZodURL>;
+}>;
+/**
+ * The Zod schema matching the Command type.
+ *
+ * Zod is the default for validating incomming messages.
+ *
+ * We do not infer the Command type from this schema because of
+ * slow type issues see https://jsr.io/docs/about-slow-types for more details.
+ */
+export declare const commandSchema: CommandSchemaType;
+/**
+ * Input for creating a command.
+ *
+ * When a specific command type is provided via the generic parameter,
+ * the input is validated against that type. This means fields like
+ * `type` and `data` must match the narrower types of `TCommand`.
+ */
+export type CreateCommandInput<TCommand extends Command = Command> = Partial<Pick<TCommand, 'id' | 'correlationid' | 'time' | 'subject' | 'datacontenttype' | 'dataschema'>> & Pick<TCommand, 'type' | 'source' | 'data'>;
+/**
+ * Creates a command based on input data with the convenience
+ * to skip properties and use the defaults for the rest.
+ */
+export declare const createCommand: <TCommand extends Command>(input: CreateCommandInput<TCommand>) => TCommand;
+export {};
+//# sourceMappingURL=command.d.ts.map

package/esm/lib/message/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/lib/message/command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,MAAM,OAAO,CAAC,KAAK,GAAG,OAAO,IAAI;IACnC,WAAW,EAAE,KAAK,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,KAAK,iBAAiB,GAAG,CAAC,CAAC,QAAQ,CAC/B;IACI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,CAAC;IACtC,CAAC,CAAC,SAAS;IACX,CAAC,CAAC,SAAS;IACX,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC;IACxB,CAAC,CAAC,UAAU;CACf,CACJ,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,SAAS,CAAC;IACxC,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACjC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC;IAChB,aAAa,EAAE,CAAC,CAAC,SAAS,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,cAAc,CAAC;IACvB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,IAAI,EAAE,CAAC,CAAC,SAAS,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,eAAe,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC5C,UAAU,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;CACvC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,iBAiB1B,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,IAC3D,OAAO,CACL,IAAI,CACA,QAAQ,EACN,IAAI,GACJ,eAAe,GACf,MAAM,GACN,SAAS,GACT,iBAAiB,GACjB,YAAY,CACjB,CACJ,GACC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,SAAS,OAAO,EAClD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,KACpC,QAeF,CAAC"}

package/esm/lib/message/command.js

@@ -0,0 +1,47 @@
+import { ulid } from '../../deps/jsr.io/@std/ulid/1.0.0/mod.js';
+import { z } from 'zod';
+/**
+ * The Zod schema matching the Command type.
+ *
+ * Zod is the default for validating incomming messages.
+ *
+ * We do not infer the Command type from this schema because of
+ * slow type issues see https://jsr.io/docs/about-slow-types for more details.
+ */
+export const commandSchema = z.object({
+    specversion: z.literal('1.0'),
+    id: z.string(),
+    correlationid: z.string(),
+    time: z.iso.datetime(),
+    source: z.string(),
+    type: z.string(),
+    subject: z.string().optional(),
+    data: z.union([
+        z.record(z.string(), z.unknown()),
+        z.string(),
+        z.number(),
+        z.array(z.unknown()),
+        z.boolean(),
+    ]),
+    datacontenttype: z.string().optional(),
+    dataschema: z.url().optional(),
+});
+/**
+ * Creates a command based on input data with the convenience
+ * to skip properties and use the defaults for the rest.
+ */
+export const createCommand = (input) => {
+    const command = {
+        specversion: '1.0',
+        id: input.id ?? ulid(),
+        correlationid: input.correlationid ?? ulid(),
+        time: input.time ?? new Date().toISOString(),
+        source: input.source,
+        type: input.type,
+        ...(input.subject && { subject: input.subject }),
+        data: input.data,
+        datacontenttype: input.datacontenttype ?? 'application/json',
+        ...(input.dataschema && { dataschema: input.dataschema }),
+    };
+    return command;
+};

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

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+/**
+ * An event is a message that is emitted by the system to notify
+ * subscribers that something has happened. Typically events are
+ * the result of a command that was executed before.
+ *
+ * Nimbus sticks to the CloudEvents specifications for all messages
+ * to make it easier to work with these messages across multiple systems.
+ *
+ * @see https://cloudevents.io/ for more information.
+ *
+ * @property {string} specversion - The version of the CloudEvents specification which the event uses.
+ * @property {string} id - A globally unique identifier of the event.
+ * @property {string} correlationid - A globally unique identifier that indicates a correlation to previous and subsequent messages to this event.
+ * @property {string} time - The time when the event was created.
+ * @property {string} source - A URI reference that identifies the system that is constructing the event.
+ * @property {string} type - The type must follow the CloudEvents naming convention, which uses a reversed domain name as a namespace, followed by a domain-specific name.
+ * @property {string} subject - An identifier for an object or entity the event is about (optional).
+ * @property {TData} data - The actual data, containing the specific business payload.
+ * @property {string} datacontenttype - A MIME type that indicates the format that the data is in (optional).
+ * @property {string} dataschema - An absolute URL to the schema that the data adheres to (optional).
+ *
+ * @template TData - The type of the data.
+ *
+ * @example
+ * const orderSubmittedEvent: Event<Order> = {
+ *     specversion: '1.0',
+ *     id: '123',
+ *     correlationid: '456',
+ *     time: '2025-01-01T00:00:00Z',
+ *     source: 'https://nimbus.overlap.at',
+ *     type: 'at.overlap.nimbus.submit-order',
+ *     subject: '/orders/42',
+ *     data: {
+ *         orderId: '42',
+ *         customerId: '666',
+ *         cartId: '123',
+ *         status: 'submitted',
+ *     },
+ *     datacontenttype: 'application/json',
+ * };
+ */
+export type Event<TData = unknown> = {
+    specversion: '1.0';
+    id: string;
+    correlationid: string;
+    time: string;
+    source: string;
+    type: string;
+    subject: string;
+    data: TData;
+    datacontenttype?: string;
+    dataschema?: string;
+};
+/**
+ * Type alias for the event data field schema.
+ */
+type EventDataSchema = z.ZodUnion<[
+    z.ZodRecord<z.ZodString, z.ZodUnknown>,
+    z.ZodString,
+    z.ZodNumber,
+    z.ZodArray<z.ZodUnknown>,
+    z.ZodBoolean
+]>;
+/**
+ * Type alias for the event schema shape.
+ */
+export type EventSchemaType = z.ZodObject<{
+    specversion: z.ZodLiteral<'1.0'>;
+    id: z.ZodString;
+    correlationid: z.ZodString;
+    time: z.ZodISODateTime;
+    source: z.ZodString;
+    type: z.ZodString;
+    subject: z.ZodString;
+    data: EventDataSchema;
+    datacontenttype: z.ZodOptional<z.ZodString>;
+    dataschema: z.ZodOptional<z.ZodURL>;
+}>;
+/**
+ * The Zod schema matching the Event type.
+ *
+ * Zod is the default for validating incoming messages.
+ *
+ * We do not infer the Event type from this schema because of
+ * slow type issues see https://jsr.io/docs/about-slow-types for more details.
+ */
+export declare const eventSchema: EventSchemaType;
+/**
+ * Input for creating an event.
+ *
+ * When a specific event type is provided via the generic parameter,
+ * the input is validated against that type. This means fields like
+ * `type` and `data` must match the narrower types of `TEvent`.
+ */
+export type CreateEventInput<TEvent extends Event = Event> = Partial<Pick<TEvent, 'id' | 'correlationid' | 'time' | 'datacontenttype' | 'dataschema'>> & Pick<TEvent, 'type' | 'source' | 'subject' | 'data'>;
+/**
+ * Creates an event based on input data with the convenience
+ * to skip properties and use the defaults for the rest.
+ */
+export declare const createEvent: <TEvent extends Event>(input: CreateEventInput<TEvent>) => TEvent;
+export {};
+//# sourceMappingURL=event.d.ts.map