@crossdelta/cloudevents 0.1.1

package/dist/src/publishing/nats.publisher.js

@@ -0,0 +1,66 @@
+import { connect, StringCodec } from 'nats';
+import { extractTypeFromSchema } from '../domain';
+import { createValidationError, logger } from '../infrastructure';
+const sc = StringCodec();
+let natsConnectionPromise = null;
+async function getNatsConnection(servers) {
+    if (!natsConnectionPromise) {
+        const url = servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
+        natsConnectionPromise = connect({ servers: url })
+            .then((connection) => {
+            logger.debug(`[NATS] connected to ${url}`);
+            return connection;
+        })
+            .catch((error) => {
+            logger.error('[NATS] connection error', error);
+            natsConnectionPromise = null;
+            throw error;
+        });
+    }
+    return natsConnectionPromise;
+}
+export async function publishNatsEvent(subjectName, schema, eventData, options) {
+    const eventType = extractTypeFromSchema(schema);
+    if (!eventType) {
+        throw new Error('Could not extract event type from schema. Make sure your schema has proper metadata.');
+    }
+    const validationResult = schema.safeParse(eventData);
+    if (!validationResult.success) {
+        const validationDetails = validationResult.error.issues.map((issue) => ({
+            code: issue.code,
+            message: issue.message,
+            path: issue.path,
+            expected: 'expected' in issue ? String(issue.expected) : undefined,
+            received: 'received' in issue ? String(issue.received) : undefined,
+        }));
+        const handlerValidationError = {
+            handlerName: `NatsPublisher:${eventType}`,
+            validationErrors: validationDetails,
+        };
+        throw createValidationError(eventType, [handlerValidationError]);
+    }
+    return publishNatsRawEvent(subjectName, eventType, validationResult.data, options);
+}
+export async function publishNatsRawEvent(subjectName, eventType, eventData, options) {
+    const cloudEvent = {
+        specversion: '1.0',
+        type: eventType,
+        source: options?.source || 'hono-service',
+        id: crypto.randomUUID(),
+        time: new Date().toISOString(),
+        datacontenttype: 'application/json',
+        data: eventData,
+        ...(options?.subject && { subject: options.subject }),
+    };
+    const data = JSON.stringify(cloudEvent);
+    const nc = await getNatsConnection(options?.servers);
+    nc.publish(subjectName, sc.encode(data));
+    logger.debug(`Published CloudEvent ${eventType} to NATS subject ${subjectName} (id=${cloudEvent.id})`);
+    return cloudEvent.id;
+}
+/**
+ * @internal Resets the cached NATS connection. Intended for testing only.
+ */
+export function __resetNatsPublisher() {
+    natsConnectionPromise = null;
+}

package/dist/src/publishing/pubsub.publisher.d.ts

@@ -0,0 +1,39 @@
+import type { ZodTypeAny } from 'zod';
+export interface PublishEventOptions {
+    projectId?: string;
+    keyFilename?: string;
+    source?: string;
+    subject?: string;
+    attributes?: Record<string, string>;
+}
+/**
+ * Publishes an event using a Zod schema for validation and type extraction.
+ * Automatically extracts the event type from the schema and creates a CloudEvent.
+ *
+ * @param topicName - PubSub topic name
+ * @param schema - Zod schema that defines the event structure and type
+ * @param eventData - Event data that must match the schema
+ * @param options - Optional PubSub configuration
+ * @returns Promise resolving to the published message ID
+ *
+ * @example
+ * ```typescript
+ * await publishEvent(
+ *   'customer-events',
+ *   CustomerCreatedSchema,
+ *   { customer: { id: '123', email: 'test@example.com' } }
+ * )
+ * ```
+ */
+export declare function publishEvent<T extends ZodTypeAny>(topicName: string, schema: T, eventData: unknown, options?: PublishEventOptions): Promise<string>;
+/**
+ * Raw event publisher - bypasses schema validation.
+ * Use this when you need direct control over the event type and data.
+ *
+ * @param topicName - PubSub topic name
+ * @param eventType - Manual event type identifier
+ * @param eventData - Raw event data
+ * @param options - Optional PubSub configuration
+ * @returns Promise resolving to the published message ID
+ */
+export declare function publishRawEvent(topicName: string, eventType: string, eventData: unknown, options?: PublishEventOptions): Promise<string>;

package/dist/src/publishing/pubsub.publisher.js

@@ -0,0 +1,84 @@
+import { extractTypeFromSchema } from '../domain';
+import { createValidationError, logger } from '../infrastructure';
+/**
+ * Publishes an event using a Zod schema for validation and type extraction.
+ * Automatically extracts the event type from the schema and creates a CloudEvent.
+ *
+ * @param topicName - PubSub topic name
+ * @param schema - Zod schema that defines the event structure and type
+ * @param eventData - Event data that must match the schema
+ * @param options - Optional PubSub configuration
+ * @returns Promise resolving to the published message ID
+ *
+ * @example
+ * ```typescript
+ * await publishEvent(
+ *   'customer-events',
+ *   CustomerCreatedSchema,
+ *   { customer: { id: '123', email: 'test@example.com' } }
+ * )
+ * ```
+ */
+export async function publishEvent(topicName, schema, eventData, options) {
+    // Extract event type from schema
+    const eventType = extractTypeFromSchema(schema);
+    if (!eventType) {
+        throw new Error('Could not extract event type from schema. Make sure your schema has proper metadata.');
+    }
+    // Validate the data against the schema
+    const validationResult = schema.safeParse(eventData);
+    if (!validationResult.success) {
+        const validationDetails = validationResult.error.issues.map((issue) => ({
+            code: issue.code,
+            message: issue.message,
+            path: issue.path,
+            expected: 'expected' in issue ? String(issue.expected) : undefined,
+            received: 'received' in issue ? String(issue.received) : undefined,
+        }));
+        const handlerValidationError = {
+            handlerName: `Publisher:${eventType}`,
+            validationErrors: validationDetails,
+        };
+        throw createValidationError(eventType, [handlerValidationError]);
+    }
+    return publishRawEvent(topicName, eventType, validationResult.data, options);
+}
+/**
+ * Raw event publisher - bypasses schema validation.
+ * Use this when you need direct control over the event type and data.
+ *
+ * @param topicName - PubSub topic name
+ * @param eventType - Manual event type identifier
+ * @param eventData - Raw event data
+ * @param options - Optional PubSub configuration
+ * @returns Promise resolving to the published message ID
+ */
+export async function publishRawEvent(topicName, eventType, eventData, options) {
+    const { PubSub } = await import('@google-cloud/pubsub');
+    const pubsub = new PubSub({
+        projectId: options?.projectId,
+        keyFilename: options?.keyFilename,
+    });
+    const cloudEvent = {
+        specversion: '1.0',
+        type: eventType,
+        source: options?.source || 'hono-service',
+        id: crypto.randomUUID(),
+        time: new Date().toISOString(),
+        datacontenttype: 'application/json',
+        data: eventData,
+        ...(options?.subject && { subject: options.subject }),
+    };
+    const data = JSON.stringify(cloudEvent);
+    const dataBuffer = Buffer.from(data);
+    const topic = pubsub.topic(topicName);
+    const messageId = await topic.publishMessage({
+        data: dataBuffer,
+        attributes: {
+            'content-type': 'application/cloudevents+json',
+            ...options?.attributes,
+        },
+    });
+    logger.debug(`Published CloudEvent ${eventType} with ID: ${messageId}`);
+    return messageId;
+}

package/dist/src/transports/nats/index.d.ts

@@ -0,0 +1,2 @@
+export * from './nats-consumer';
+export * from './nats-message-processor';

package/dist/src/transports/nats/index.js

@@ -0,0 +1,2 @@
+export * from './nats-consumer';
+export * from './nats-message-processor';

package/dist/src/transports/nats/nats-consumer.d.ts

@@ -0,0 +1,30 @@
+import { type Subscription } from 'nats';
+import type { CloudEventsOptions } from '../../middlewares/cloudevents-middleware';
+/**
+ * Describes the configuration required to bootstrap the NATS event consumer.
+ *
+ * @property servers - Optional NATS connection string; defaults to `NATS_URL` or the local instance.
+ * @property subject - NATS subject to subscribe to for incoming events.
+ * @property discover - Glob pattern or directory used to discover event handler classes.
+ * @property consumerName - Optional identifier appended to log output and the consumer name.
+ * @property quarantineTopic - Optional Pub/Sub topic for quarantining malformed messages when DLQ mode is enabled.
+ * @property errorTopic - Optional Pub/Sub topic for recovering handler errors when DLQ mode is enabled.
+ * @property projectId - Optional Google Cloud project identifier used for DLQ publishing.
+ * @property source - Optional CloudEvent source identifier applied to DLQ messages.
+ */
+export interface NatsConsumerOptions extends Pick<CloudEventsOptions, 'quarantineTopic' | 'errorTopic' | 'projectId' | 'source'> {
+    servers?: string;
+    subject: string;
+    discover: string;
+    consumerName?: string;
+}
+/**
+ * Connects to NATS, discovers matching event handlers, and processes incoming CloudEvents.
+ *
+ * @param options - Consumer configuration describing connection, discovery, and subscription details.
+ * @returns The active NATS subscription for the configured subject.
+ *
+ * When `quarantineTopic` or `errorTopic` is provided, the consumer forwards malformed messages
+ * and handler failures to the configured DLQ topics instead of throwing errors.
+ */
+export declare function consumeNatsEvents(options: NatsConsumerOptions): Promise<Subscription>;

package/dist/src/transports/nats/nats-consumer.js

@@ -0,0 +1,54 @@
+import { connect, StringCodec } from 'nats';
+import { discoverHandlers } from '../../domain';
+import { logger } from '../../infrastructure/logging';
+import { processHandler } from '../../processing/handler-cache';
+import { createNatsMessageProcessor } from './nats-message-processor';
+const sc = StringCodec();
+/**
+ * Connects to NATS, discovers matching event handlers, and processes incoming CloudEvents.
+ *
+ * @param options - Consumer configuration describing connection, discovery, and subscription details.
+ * @returns The active NATS subscription for the configured subject.
+ *
+ * When `quarantineTopic` or `errorTopic` is provided, the consumer forwards malformed messages
+ * and handler failures to the configured DLQ topics instead of throwing errors.
+ */
+export async function consumeNatsEvents(options) {
+    const servers = options.servers ?? process.env.NATS_URL ?? 'nats://localhost:4222';
+    const subject = options.subject;
+    const name = options.consumerName ?? `nats-consumer:${subject}`;
+    // 1) Discover handler classes from *.event.ts files
+    const handlerConstructors = await discoverHandlers(options.discover);
+    const processedHandlers = handlerConstructors
+        .map(processHandler)
+        .filter((h) => h !== null);
+    logger.info(`[${name}] discovered handlers`, {
+        count: processedHandlers.length,
+        handlers: processedHandlers.map((h) => h.name),
+    });
+    // 2) Connect to NATS
+    const nc = await connect({ servers });
+    logger.info(`[${name}] connected to NATS: ${servers}`);
+    // 3) Subscribe to the subject
+    const sub = nc.subscribe(subject);
+    logger.info(`[${name}] subscribed to subject: ${subject}`);
+    const dlqEnabled = Boolean(options.quarantineTopic || options.errorTopic);
+    const { handleMessage, handleUnhandledProcessingError } = createNatsMessageProcessor({
+        name,
+        subject,
+        dlqEnabled,
+        options,
+        processedHandlers,
+        decode: (data) => sc.decode(data),
+        logger,
+    });
+    const processSubscription = async () => {
+        for await (const msg of sub) {
+            await handleMessage(msg).catch((error) => handleUnhandledProcessingError(msg, error));
+        }
+    };
+    processSubscription().catch((err) => {
+        logger.error(`[${name}] subscription loop crashed`, err);
+    });
+    return sub;
+}

package/dist/src/transports/nats/nats-message-processor.d.ts

@@ -0,0 +1,22 @@
+import type { Msg } from 'nats';
+import { type DlqOptions } from '../../processing/dlq-safe';
+import type { ProcessedHandler } from '../../processing/handler-cache';
+export interface LoggerLike {
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    error(message: string, meta?: unknown): void;
+}
+export interface NatsMessageProcessorDeps {
+    name: string;
+    subject: string;
+    dlqEnabled: boolean;
+    options: DlqOptions;
+    processedHandlers: ProcessedHandler[];
+    decode: (data: Uint8Array) => string;
+    logger: LoggerLike;
+}
+export interface NatsMessageProcessor {
+    handleMessage(msg: Msg): Promise<void>;
+    handleUnhandledProcessingError(msg: Msg, error: unknown): Promise<void>;
+}
+export declare const createNatsMessageProcessor: ({ name, subject, dlqEnabled, options, processedHandlers, decode, logger, }: NatsMessageProcessorDeps) => NatsMessageProcessor;

package/dist/src/transports/nats/nats-message-processor.js

@@ -0,0 +1,95 @@
+import { createProcessingContext, publishRecoverableError, quarantineMessage, } from '../../processing/dlq-safe';
+import { throwValidationError, validateEventData } from '../../processing/validation';
+export const createNatsMessageProcessor = ({ name, subject, dlqEnabled, options, processedHandlers, decode, logger, }) => {
+    const toEnrichedEvent = (ce) => ({
+        eventType: ce.type,
+        source: ce.source,
+        subject: ce.subject,
+        time: ce.time ?? new Date().toISOString(),
+        messageId: ce.id,
+        data: ce.data,
+    });
+    const toUnknownContext = (msg) => ({
+        eventType: 'unknown',
+        source: `nats://${subject}`,
+        subject,
+        time: new Date().toISOString(),
+        messageId: msg.headers?.get('Nats-Msg-Id') ?? 'unknown',
+        data: decode(msg.data),
+    });
+    const createContext = (event, ce) => createProcessingContext(event.eventType, event.data, event, ce);
+    const safeParseMessage = (msg) => {
+        try {
+            const cloudEvent = JSON.parse(decode(msg.data));
+            return { ok: true, cloudEvent, enriched: toEnrichedEvent(cloudEvent) };
+        }
+        catch (error) {
+            return { ok: false, error, context: createContext(toUnknownContext(msg)) };
+        }
+    };
+    const findHandler = (event) => processedHandlers.find((handler) => handler.type === event.eventType && (!handler.match || handler.match(event)));
+    const handleParseFailure = async ({ context, error }) => {
+        logger.error(`[${name}] failed to parse CloudEvent payload`, error);
+        if (!dlqEnabled)
+            return;
+        await quarantineMessage(context, 'parse_error', options, error);
+    };
+    const handleMissingHandler = async (context, eventType) => {
+        logger.warn(`[${name}] no handler for event type ${eventType}`);
+        if (!dlqEnabled)
+            return;
+        await quarantineMessage(context, 'no_handler', options, new Error(`No handler for event type ${eventType}`));
+    };
+    const handleValidationFailure = async (validationResult, handler, context) => {
+        if (dlqEnabled) {
+            await quarantineMessage(context, 'validation_error', options, validationResult.error);
+            return;
+        }
+        if (validationResult.shouldSkip)
+            return;
+        throwValidationError(handler.name, validationResult.error);
+    };
+    const executeHandler = async (handler, enriched, context) => {
+        try {
+            await handler.handle(enriched.data, enriched);
+        }
+        catch (error) {
+            if (!dlqEnabled)
+                throw error;
+            await publishRecoverableError(context, error, options);
+        }
+    };
+    const handleMessage = async (msg) => {
+        const parseResult = safeParseMessage(msg);
+        if (!parseResult.ok) {
+            await handleParseFailure(parseResult);
+            return;
+        }
+        const { cloudEvent, enriched } = parseResult;
+        const processingContext = createContext(enriched, cloudEvent);
+        const handler = findHandler(enriched);
+        if (!handler) {
+            await handleMissingHandler(processingContext, enriched.eventType);
+            return;
+        }
+        const validationResult = validateEventData(handler, enriched.data);
+        if ('error' in validationResult) {
+            await handleValidationFailure(validationResult, handler, processingContext);
+            return;
+        }
+        await executeHandler(handler, enriched, processingContext);
+    };
+    const handleUnhandledProcessingError = async (msg, error) => {
+        logger.error(`[${name}] failed to handle NATS message`, error);
+        if (!dlqEnabled) {
+            return;
+        }
+        try {
+            await quarantineMessage(createContext(toUnknownContext(msg)), 'unhandled_error', options, error);
+        }
+        catch (quarantineError) {
+            logger.error(`[${name}] failed to quarantine unhandled error`, quarantineError);
+        }
+    };
+    return { handleMessage, handleUnhandledProcessingError };
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@crossdelta/cloudevents",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start:dev": "tsc -p tsconfig.json --watch",
+    "stryker": "bun stryker run",
+    "lint": "biome lint --fix",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "cloudevents": "7.0.2",
+    "glob": "11.0.0",
+    "nats": "^2.29.3"
+  },
+  "optionalDependencies": {
+    "@google-cloud/pubsub": "5.2.0"
+  },
+  "peerDependencies": {
+    "hono": "^4.6.0",
+    "zod": "^3.23.0"
+  },
+  "trustedDependencies": [],
+  "devDependencies": {
+    "@types/bun": "^1.3.3",
+    "@stryker-mutator/core": "^9.1.1",
+    "stryker-mutator-bun-runner": "^0.4.0",
+    "typescript": "^5.9.2"
+  }
+}