@crossdelta/cloudevents 0.5.7 → 0.6.1

package/dist/processing/dlq-safe.js

@@ -1,108 +0,0 @@
-/**
- * DLQ-Safe mode utilities
- * Handles quarantine and error publishing for CloudEvents processing
- */
-import { logger } from '../infrastructure';
-import { publishRawEvent } from '../publishing';
-/**
- * Checks if DLQ-Safe mode is enabled
- */
-export const isDlqSafeMode = (options) => {
-    return !!(options.quarantineTopic || options.errorTopic);
-};
-/**
- * Publishes a message to the quarantine topic for "poison messages" that can't be processed
- */
-export const quarantineMessage = async (processingContext, reason, options, error) => {
-    if (!options.quarantineTopic) {
-        logger.warn('No quarantine topic configured, skipping quarantine');
-        return;
-    }
-    try {
-        // Serialize error properly - handle ValidationError specially
-        let serializedError;
-        if (error) {
-            if (typeof error === 'object' && error !== null && 'type' in error && error.type === 'ValidationError') {
-                serializedError = JSON.stringify(error, null, 2);
-            }
-            else if (error instanceof Error) {
-                serializedError = JSON.stringify({
-                    name: error.name,
-                    message: error.message,
-                    stack: error.stack,
-                }, null, 2);
-            }
-            else {
-                serializedError = JSON.stringify(error, null, 2);
-            }
-        }
-        const quarantineData = {
-            originalMessageId: processingContext.messageId,
-            originalEventType: processingContext.eventType,
-            originalEventData: processingContext.eventData,
-            originalEventContext: processingContext.eventContext,
-            originalCloudEvent: processingContext.originalCloudEvent,
-            quarantinedAt: new Date().toISOString(),
-            quarantineReason: reason,
-            error: serializedError,
-        };
-        await publishRawEvent(options.quarantineTopic, 'hono.cloudevents.quarantined', quarantineData, {
-            projectId: options.projectId,
-            subject: `quarantine.${reason}`,
-            source: options.source || 'hono-cloudevents',
-            attributes: {
-                'quarantine-reason': reason,
-            },
-        });
-        logger.info(`Message ${processingContext.messageId} quarantined: ${reason}`);
-    }
-    catch (publishError) {
-        const errorMessage = publishError instanceof Error ? publishError.message : 'Unknown error';
-        logger.error(`Failed to quarantine message ${processingContext.messageId}: ${errorMessage}`);
-    }
-};
-/**
- * Publishes recoverable processing errors to the error topic
- */
-export const publishRecoverableError = async (processingContext, error, options) => {
-    if (!options.errorTopic) {
-        logger.warn('No error topic configured, skipping error publishing');
-        return;
-    }
-    try {
-        const errorData = {
-            originalMessageId: processingContext.messageId,
-            originalEventType: processingContext.eventType,
-            originalEventData: processingContext.eventData,
-            originalEventContext: processingContext.eventContext,
-            originalCloudEvent: processingContext.originalCloudEvent,
-            errorTimestamp: new Date().toISOString(),
-            error: {
-                message: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-                type: error instanceof Error ? error.constructor.name : typeof error,
-            },
-        };
-        await publishRawEvent(options.errorTopic, 'hono.cloudevents.processing-error', errorData, {
-            projectId: options.projectId,
-            subject: 'processing.error',
-            source: options.source || 'hono-cloudevents',
-        });
-        logger.info(`Processing error published for message ${processingContext.messageId}`);
-    }
-    catch (publishError) {
-        const errorMessage = publishError instanceof Error ? publishError.message : 'Unknown error';
-        logger.error(`Failed to publish error for message ${processingContext.messageId}: ${errorMessage}`);
-    }
-};
-/**
- * Creates processing context from event data
- */
-export const createProcessingContext = (eventType, eventData, context, originalCloudEvent) => ({
-    messageId: context?.messageId || 'unknown',
-    eventType,
-    eventData,
-    eventContext: context,
-    timestamp: new Date().toISOString(),
-    originalCloudEvent,
-});

package/dist/processing/handler-cache.d.ts

@@ -1,36 +0,0 @@
-/**
- * Handler Cache Management
- * Immutable cache operations for CloudEvents handlers
- */
-import type { ZodTypeAny } from 'zod';
-import { type EnrichedEvent, type HandlerConstructor } from '../domain';
-export interface ProcessedHandler {
-    type: string;
-    name: string;
-    schema: ZodTypeAny;
-    handle: (payload: unknown, context?: unknown) => Promise<void>;
-    match?: (event: EnrichedEvent<unknown>) => boolean;
-    safeParse?: boolean;
-}
-/**
- * Clears the handler cache. Useful for testing.
- * @internal
- */
-export declare const clearHandlerCache: () => void;
-export declare const getCachedHandlers: (key: string) => ProcessedHandler[];
-export declare const setCachedHandlers: (key: string, handlers: ProcessedHandler[]) => void;
-export declare const hasCachedHandlers: (key: string) => boolean;
-export declare const isMessageProcessed: (messageId: string) => boolean;
-export declare const addProcessedMessage: (messageId: string) => void;
-/**
- * Converts HandlerConstructor to ProcessedHandler
- */
-export declare const processHandler: (HandlerClass: HandlerConstructor) => ProcessedHandler | null;
-/**
- * Creates a cache key from configuration with environment awareness
- */
-export declare const createCacheKey: (discover?: string, handlers?: HandlerConstructor[]) => string;
-/**
- * Setup handlers with caching
- */
-export declare const setupHandlers: (cacheKey: string, discover?: string, handlers?: HandlerConstructor[], log?: boolean | "pretty" | "structured") => Promise<void>;

package/dist/processing/handler-cache.js

@@ -1,94 +0,0 @@
-/**
- * Handler Cache Management
- * Immutable cache operations for CloudEvents handlers
- */
-import { discoverHandlers, extractTypeFromSchema } from '../domain';
-import { logger } from '../infrastructure/logging';
-const createEmptyCache = () => new Map();
-const createEmptyMessageIds = () => new Set();
-// Global state (necessary for middleware persistence)
-let handlerCache = createEmptyCache();
-let processedMessageIds = createEmptyMessageIds();
-/**
- * Clears the handler cache. Useful for testing.
- * @internal
- */
-export const clearHandlerCache = () => {
-    handlerCache = createEmptyCache();
-    processedMessageIds = createEmptyMessageIds();
-};
-// Pure cache operations
-export const getCachedHandlers = (key) => handlerCache.get(key) || [];
-export const setCachedHandlers = (key, handlers) => {
-    handlerCache = new Map(handlerCache).set(key, handlers);
-};
-export const hasCachedHandlers = (key) => handlerCache.has(key);
-export const isMessageProcessed = (messageId) => processedMessageIds.has(messageId);
-export const addProcessedMessage = (messageId) => {
-    processedMessageIds = new Set(processedMessageIds).add(messageId);
-};
-/**
- * Converts HandlerConstructor to ProcessedHandler
- */
-export const processHandler = (HandlerClass) => {
-    const metadata = HandlerClass.__eventarcMetadata;
-    if (!metadata)
-        return null;
-    const instance = new HandlerClass();
-    const eventType = metadata.declaredType || extractTypeFromSchema(metadata.schema);
-    if (!eventType)
-        return null;
-    return {
-        type: eventType,
-        name: HandlerClass.name,
-        schema: metadata.schema,
-        handle: async (payload, context) => {
-            await Promise.resolve(instance.handle(payload, context));
-        },
-        match: metadata.match,
-        safeParse: metadata.safeParse || false,
-    };
-};
-/**
- * Creates a cache key from configuration with environment awareness
- */
-export const createCacheKey = (discover, handlers = []) => {
-    const discoverKey = discover || 'no-discover';
-    const handlersKey = handlers
-        .map((h) => h.name)
-        .sort()
-        .join(',') || 'no-handlers';
-    const envKey = process.env.NODE_ENV || 'development';
-    return `${envKey}:${discoverKey}:${handlersKey}`;
-};
-/**
- * Setup handlers with caching
- */
-export const setupHandlers = async (cacheKey, discover, handlers = [], log = false) => {
-    if (hasCachedHandlers(cacheKey))
-        return;
-    try {
-        const allHandlers = discover ? await discoverHandlers(discover, { log: !!log }) : handlers;
-        const processedHandlers = allHandlers.map(processHandler).filter(Boolean);
-        setCachedHandlers(cacheKey, processedHandlers);
-        if (log && processedHandlers.length > 0) {
-            if (log === 'pretty') {
-                logger.info(`Discovered ${processedHandlers.length} handler${processedHandlers.length === 1 ? '' : 's'}:`);
-                for (const handler of processedHandlers) {
-                    logger.info(`  • ${handler.name}`);
-                }
-            }
-            else {
-                // structured or true
-                logger.info('Handler discovery completed', {
-                    handlerCount: processedHandlers.length,
-                    handlers: processedHandlers.map((h) => h.name),
-                });
-            }
-        }
-    }
-    catch (error) {
-        logger.error('Failed to setup handlers:', error);
-        setCachedHandlers(cacheKey, []);
-    }
-};

package/dist/processing/idempotency.d.ts

@@ -1,51 +0,0 @@
-/**
- * Idempotency utilities for CloudEvents processing
- *
- * Provides deduplication support to ensure handlers process each message exactly once.
- * Uses CloudEvent ID as the deduplication key.
- */
-import type { IdempotencyStore } from '../domain/types';
-/**
- * Options for the in-memory idempotency store
- */
-export interface InMemoryIdempotencyStoreOptions {
-    /** Maximum number of message IDs to store (LRU eviction). @default 10000 */
-    maxSize?: number;
-    /** Default TTL for entries in milliseconds. @default 86400000 (24 hours) */
-    defaultTtlMs?: number;
-}
-/**
- * Creates an in-memory idempotency store with LRU eviction and TTL support.
- *
- * Suitable for single-instance deployments or development. For production
- * multi-instance deployments, use a Redis-based store.
- *
- * @example
- * ```typescript
- * const store = createInMemoryIdempotencyStore({ maxSize: 5000, defaultTtlMs: 3600000 })
- *
- * await consumeJetStreamEvents({
- *   stream: 'ORDERS',
- *   subjects: ['orders.>'],
- *   consumer: 'notifications',
- *   discover: `./src/events/**\/*.handler.ts`,
- *   idempotencyStore: store,
- * })
- * ```
- */
-export declare function createInMemoryIdempotencyStore(options?: InMemoryIdempotencyStoreOptions): IdempotencyStore;
-/**
- * Gets or creates the default idempotency store
- */
-export declare function getDefaultIdempotencyStore(): IdempotencyStore;
-/**
- * Resets the default idempotency store. Useful for testing.
- */
-export declare function resetDefaultIdempotencyStore(): void;
-/**
- * Checks if a message should be processed (not a duplicate)
- * and marks it as processed if so.
- *
- * @returns true if the message should be processed, false if it's a duplicate
- */
-export declare function checkAndMarkProcessed(store: IdempotencyStore, messageId: string, ttlMs?: number): Promise<boolean>;

package/dist/processing/idempotency.js

@@ -1,112 +0,0 @@
-/**
- * Idempotency utilities for CloudEvents processing
- *
- * Provides deduplication support to ensure handlers process each message exactly once.
- * Uses CloudEvent ID as the deduplication key.
- */
-/**
- * Creates an in-memory idempotency store with LRU eviction and TTL support.
- *
- * Suitable for single-instance deployments or development. For production
- * multi-instance deployments, use a Redis-based store.
- *
- * @example
- * ```typescript
- * const store = createInMemoryIdempotencyStore({ maxSize: 5000, defaultTtlMs: 3600000 })
- *
- * await consumeJetStreamEvents({
- *   stream: 'ORDERS',
- *   subjects: ['orders.>'],
- *   consumer: 'notifications',
- *   discover: `./src/events/**\/*.handler.ts`,
- *   idempotencyStore: store,
- * })
- * ```
- */
-export function createInMemoryIdempotencyStore(options = {}) {
-    const { maxSize = 10_000, defaultTtlMs = 24 * 60 * 60 * 1000 } = options;
-    // Use Map for insertion-order iteration (LRU approximation)
-    const cache = new Map();
-    const evictExpired = () => {
-        const now = Date.now();
-        for (const [key, entry] of cache) {
-            if (entry.expiresAt <= now) {
-                cache.delete(key);
-            }
-        }
-    };
-    const evictOldest = (count) => {
-        const keysToDelete = [...cache.keys()].slice(0, count);
-        for (const key of keysToDelete) {
-            cache.delete(key);
-        }
-    };
-    return {
-        has(messageId) {
-            const entry = cache.get(messageId);
-            if (!entry)
-                return false;
-            // Check if expired
-            if (entry.expiresAt <= Date.now()) {
-                cache.delete(messageId);
-                return false;
-            }
-            // Move to end for LRU (re-insert)
-            cache.delete(messageId);
-            cache.set(messageId, entry);
-            return true;
-        },
-        add(messageId, ttlMs) {
-            // Evict expired entries periodically
-            if (cache.size >= maxSize) {
-                evictExpired();
-            }
-            // If still at capacity, evict oldest entries
-            if (cache.size >= maxSize) {
-                const evictCount = Math.max(1, Math.floor(maxSize * 0.1)); // Evict 10%
-                evictOldest(evictCount);
-            }
-            cache.set(messageId, {
-                expiresAt: Date.now() + (ttlMs ?? defaultTtlMs),
-            });
-        },
-        clear() {
-            cache.clear();
-        },
-    };
-}
-/**
- * Default idempotency store instance.
- * Used when no custom store is provided to consumers.
- */
-let defaultStore = null;
-/**
- * Gets or creates the default idempotency store
- */
-export function getDefaultIdempotencyStore() {
-    if (!defaultStore) {
-        defaultStore = createInMemoryIdempotencyStore();
-    }
-    return defaultStore;
-}
-/**
- * Resets the default idempotency store. Useful for testing.
- */
-export function resetDefaultIdempotencyStore() {
-    defaultStore?.clear?.();
-    defaultStore = null;
-}
-/**
- * Checks if a message should be processed (not a duplicate)
- * and marks it as processed if so.
- *
- * @returns true if the message should be processed, false if it's a duplicate
- */
-export async function checkAndMarkProcessed(store, messageId, ttlMs) {
-    const isDuplicate = await store.has(messageId);
-    if (isDuplicate) {
-        return false;
-    }
-    await store.add(messageId, ttlMs);
-    return true;
-}

package/dist/processing/index.d.ts

@@ -1,4 +0,0 @@
-export * from './dlq-safe';
-export * from './handler-cache';
-export * from './idempotency';
-export * from './validation';

package/dist/processing/index.js

@@ -1,4 +0,0 @@
-export * from './dlq-safe';
-export * from './handler-cache';
-export * from './idempotency';
-export * from './validation';

package/dist/processing/validation.d.ts

@@ -1,41 +0,0 @@
-/**
- * Validation utilities for CloudEvents processing
- */
-import type { HandlerValidationError } from '../domain';
-import type { ProcessedHandler } from './handler-cache';
-/**
- * Creates validation details from Zod error
- */
-export declare const createValidationDetails: (error: {
-    issues: Array<{
-        code: string;
-        message: string;
-        path: PropertyKey[];
-        expected?: unknown;
-        received?: unknown;
-    }>;
-}) => {
-    code: string;
-    message: string;
-    path: (string | number)[];
-    expected: string;
-    received: string;
-}[];
-/**
- * Validates event data against handler schema
- * Returns structured result for both normal and safeParse modes
- */
-export declare const validateEventData: (handler: ProcessedHandler, eventData: unknown) => {
-    success: true;
-} | {
-    error: HandlerValidationError;
-    shouldSkip: boolean;
-};
-/**
- * Checks if handler matches event
- */
-export declare const isHandlerMatching: (eventType: string, eventData: unknown, context: unknown) => (handler: ProcessedHandler) => boolean;
-/**
- * Throws validation error in standard mode
- */
-export declare const throwValidationError: (handlerType: string, error: HandlerValidationError) => never;

package/dist/processing/validation.js

@@ -1,48 +0,0 @@
-import { createValidationError } from '../infrastructure';
-/**
- * Creates validation details from Zod error
- */
-export const createValidationDetails = (error) => error.issues.map((issue) => ({
-    code: issue.code,
-    message: issue.message,
-    path: issue.path.filter((p) => typeof p !== 'symbol'),
-    expected: String(issue.expected),
-    received: String(issue.received),
-}));
-/**
- * Validates event data against handler schema
- * Returns structured result for both normal and safeParse modes
- */
-export const validateEventData = (handler, eventData) => {
-    const result = handler.schema.safeParse(eventData);
-    if (!result.success) {
-        const validationDetails = createValidationDetails(result.error);
-        const handlerValidationError = {
-            handlerName: handler.name,
-            validationErrors: validationDetails,
-        };
-        return {
-            error: handlerValidationError,
-            shouldSkip: handler.safeParse || false,
-        };
-    }
-    return { success: true };
-};
-/**
- * Checks if handler matches event
- */
-export const isHandlerMatching = (eventType, eventData, context) => (handler) => {
-    if (handler.type !== eventType)
-        return false;
-    if (handler.match) {
-        const enrichedEvent = { data: eventData, ...context };
-        return handler.match(enrichedEvent);
-    }
-    return true;
-};
-/**
- * Throws validation error in standard mode
- */
-export const throwValidationError = (handlerType, error) => {
-    throw createValidationError(handlerType, [error]);
-};

package/dist/publishing/index.d.ts

@@ -1,2 +0,0 @@
-export * from './nats.publisher';
-export * from './pubsub.publisher';

package/dist/publishing/index.js

@@ -1,2 +0,0 @@
-export * from './nats.publisher';
-export * from './pubsub.publisher';

package/dist/publishing/nats.publisher.d.ts

@@ -1,19 +0,0 @@
-import type { ZodTypeAny } from 'zod';
-import { type RoutingConfig } from '../domain';
-export interface PublishNatsEventOptions {
-    servers?: string;
-    source?: string;
-    subject?: string;
-    tenantId?: string;
-}
-export declare const deriveSubjectFromType: (eventType: string, config?: RoutingConfig) => string;
-export declare const deriveStreamFromType: (eventType: string, config?: RoutingConfig) => string | undefined;
-export declare const publishNatsRawEvent: (subjectName: string, eventType: string, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
-export declare const publishNatsEvent: <T extends ZodTypeAny>(subjectName: string, schema: T, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
-export declare const publish: (eventTypeOrContract: string | {
-    type: string;
-    channel?: {
-        subject?: string;
-    };
-}, eventData: unknown, options?: PublishNatsEventOptions) => Promise<string>;
-export declare const __resetNatsPublisher: () => void;

package/dist/publishing/nats.publisher.js

@@ -1,115 +0,0 @@
-import { connect, StringCodec } from 'nats';
-import { extractTypeFromSchema } from '../domain';
-import { createValidationError, logger } from '../infrastructure';
-const sc = StringCodec();
-let natsConnectionPromise = null;
-const pluralize = (word) => {
-    if (word.endsWith('y') && !['a', 'e', 'i', 'o', 'u'].includes(word[word.length - 2])) {
-        return `${word.slice(0, -1)}ies`;
-    }
-    if (word.endsWith('s') || word.endsWith('sh') || word.endsWith('ch') || word.endsWith('x')) {
-        return `${word}es`;
-    }
-    return `${word}s`;
-};
-const deriveSubjectFromEventType = (eventType) => {
-    const parts = eventType.split('.');
-    if (parts.length < 2)
-        return eventType;
-    const domain = parts[0];
-    const action = parts.slice(1).join('.');
-    const pluralDomain = pluralize(domain);
-    return `${pluralDomain}.${action}`;
-};
-const getNatsConnection = async (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 const deriveSubjectFromType = (eventType, config) => {
-    if (!config?.typeToSubjectMap) {
-        return config?.defaultSubjectPrefix ? `${config.defaultSubjectPrefix}.${eventType}` : eventType;
-    }
-    const sortedPrefixes = Object.keys(config.typeToSubjectMap).sort((a, b) => b.length - a.length);
-    for (const prefix of sortedPrefixes) {
-        if (eventType.startsWith(prefix)) {
-            const suffix = eventType.slice(prefix.length);
-            const mappedPrefix = config.typeToSubjectMap[prefix];
-            const cleanSuffix = suffix.startsWith('.') ? suffix.slice(1) : suffix;
-            return cleanSuffix ? `${mappedPrefix}.${cleanSuffix}` : mappedPrefix;
-        }
-    }
-    return config.defaultSubjectPrefix ? `${config.defaultSubjectPrefix}.${eventType}` : eventType;
-};
-export const deriveStreamFromType = (eventType, config) => {
-    if (!config?.typeToStreamMap)
-        return undefined;
-    const sortedPrefixes = Object.keys(config.typeToStreamMap).sort((a, b) => b.length - a.length);
-    for (const prefix of sortedPrefixes) {
-        if (eventType.startsWith(prefix)) {
-            return config.typeToStreamMap[prefix];
-        }
-    }
-    return undefined;
-};
-export const publishNatsRawEvent = async (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 }),
-        ...(options?.tenantId && { tenantid: options.tenantId }),
-    };
-    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;
-};
-export const publishNatsEvent = async (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.filter((p) => typeof p !== 'symbol'),
-            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 const publish = async (eventTypeOrContract, eventData, options) => {
-    const eventType = typeof eventTypeOrContract === 'string' ? eventTypeOrContract : eventTypeOrContract.type;
-    const natsSubject = typeof eventTypeOrContract === 'string'
-        ? deriveSubjectFromEventType(eventTypeOrContract)
-        : (eventTypeOrContract.channel?.subject ?? eventTypeOrContract.type);
-    return publishNatsRawEvent(natsSubject, eventType, eventData, options);
-};
-export const __resetNatsPublisher = () => {
-    natsConnectionPromise = null;
-};