@crossdelta/cloudevents 0.5.6 → 0.6.0

package/dist/domain/discovery.js

@@ -1,201 +0,0 @@
-import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { glob } from 'glob';
-import { logger } from '../infrastructure';
-import { isValidHandler } from './validation';
-/**
- * Gets the search directories for event handler discovery.
- * @returns Array of search directory paths.
- */
-const getSearchDirectories = () => {
-    const directories = new Set();
-    directories.add(process.cwd());
-    try {
-        const currentDir = dirname(fileURLToPath(import.meta.url));
-        directories.add(currentDir);
-        // For monorepo tests: also check packages/cloudevents if we're in dist/
-        if (currentDir.includes('/dist/')) {
-            const pkgRoot = currentDir.split('/dist/')[0];
-            if (pkgRoot)
-                directories.add(pkgRoot);
-        }
-    }
-    catch {
-        // Ignore resolution errors; fallback to process.cwd()
-    }
-    // Filter out directories that don't exist (e.g., during hot-reload)
-    return [...directories].filter((dir) => existsSync(dir));
-};
-/**
- * Loads and validates handlers from a TypeScript/JavaScript file.
- */
-const loadHandlers = async (filePath, filter) => {
-    try {
-        // Check if file exists before import to avoid ENOENT during hot-reload
-        if (!existsSync(filePath)) {
-            return [];
-        }
-        const module = await import(filePath);
-        return Object.entries(module)
-            .filter(([name, handler]) => isValidHandler(handler) && (!filter || filter(name, handler)))
-            .map(([name, handler]) => {
-            const HandlerClass = handler;
-            // Only override with export name if:
-            // 1. Export is named (not 'default')
-            // 2. Handler has no meaningful name (empty or generic class names)
-            const hasNoMeaningfulName = !HandlerClass.name || HandlerClass.name === '' || HandlerClass.name === 'HandlerClass';
-            const isNamedExport = name !== 'default';
-            if (hasNoMeaningfulName && isNamedExport) {
-                return Object.defineProperty(HandlerClass, 'name', { value: name, configurable: true });
-            }
-            return HandlerClass;
-        });
-    }
-    catch (error) {
-        // Comprehensive error logging for debugging
-        logger?.warn(`Failed to load ${filePath}`);
-        logger?.warn(`Error type: ${typeof error}`);
-        logger?.warn(`Error constructor: ${error?.constructor?.name}`);
-        if (error instanceof Error) {
-            logger?.warn(`Error message: ${error.message}`);
-            if (error.stack) {
-                logger?.warn(`Stack trace:\n${error.stack}`);
-            }
-        }
-        else {
-            logger?.warn(`Error value: ${String(error)}`);
-            try {
-                logger?.warn(`Error JSON: ${JSON.stringify(error, null, 2)}`);
-            }
-            catch {
-                logger?.warn('(Error is not JSON-serializable)');
-            }
-        }
-        return [];
-    }
-};
-/**
- * Deduplicates handlers by class name to avoid loading the same handler from .ts and .js
- * @param handlers - Array of handler constructors
- * @returns Array of unique handlers
- */
-const deduplicateHandlers = (handlers) => handlers.reduce((acc, handler) => {
-    const existing = acc.find((h) => h.name === handler.name);
-    if (!existing) {
-        acc.push(handler);
-    }
-    return acc;
-}, []);
-/**
- * Discovers files matching the pattern across multiple search paths
- * @param pattern - Glob pattern to match
- * @param searchPaths - Array of directories to search in
- * @param logger - Logger instance for debug output
- * @param log - Whether logging is enabled
- * @returns Promise resolving to array of unique file paths
- */
-/**
- * Simple, elegant file discovery using glob patterns
- */
-const EXTENSION_FALLBACKS = ['js', 'mjs', 'cjs'];
-const expandPatternVariants = (pattern, preferCompiled) => {
-    if (!/\.tsx?\b/.test(pattern)) {
-        return [pattern];
-    }
-    const basePattern = pattern;
-    const compiledVariants = EXTENSION_FALLBACKS.map((ext) => basePattern.replace(/\.tsx?\b/g, `.${ext}`));
-    const ordered = preferCompiled ? [...compiledVariants, basePattern] : [basePattern, ...compiledVariants];
-    return [...new Set(ordered)];
-};
-/**
- * Check if a directory path should be scanned (exists and is accessible)
- */
-const shouldScanDirectory = (basePath, variant) => {
-    if (!existsSync(basePath)) {
-        return false;
-    }
-    // For patterns with directory prefixes like "dist/...", check if prefix dir exists
-    const dirPrefix = variant.match(/^([^*{[]+)\//)?.[1];
-    if (dirPrefix) {
-        const fullDirPath = join(basePath, dirPrefix);
-        return existsSync(fullDirPath);
-    }
-    return true;
-};
-const discoverFiles = async (pattern, basePath, preferCompiled) => {
-    // Don't add src/dist prefix for test patterns or absolute paths
-    const isTestPattern = pattern.startsWith('test/');
-    const prefixedPattern = isTestPattern ? pattern : `{src,dist,build,lib,out}/${pattern}`;
-    const patterns = preferCompiled ? [prefixedPattern, pattern] : [pattern, prefixedPattern];
-    const allFiles = [];
-    for (const globPattern of patterns) {
-        const variants = expandPatternVariants(globPattern, preferCompiled);
-        for (const variant of variants) {
-            try {
-                // Check if directory should be scanned to avoid scandir errors during hot-reload
-                if (!shouldScanDirectory(basePath, variant)) {
-                    continue;
-                }
-                const files = await glob(variant, {
-                    cwd: basePath,
-                    absolute: true,
-                    nodir: true,
-                    windowsPathsNoEscape: true,
-                });
-                // Filter out files that no longer exist (race condition during hot-reload)
-                const existingFiles = files.filter((f) => existsSync(f));
-                allFiles.push(...existingFiles);
-            }
-            catch {
-                // Ignore errors silently - directory might have been deleted during hot-reload
-            }
-        }
-    }
-    return [...new Set(allFiles)]; // Remove duplicates
-};
-/**
- * Discovers event handlers from files matching the given glob pattern.
- *
- * @param pattern - Glob pattern to match handler files (e.g., 'events/*.handler.ts')
- * @param options - Configuration options
- * @returns Promise resolving to array of discovered handler constructors
- *
- * @example
- * ```typescript
- * // Discover all handlers in events directory
- * const handlers = await discoverHandlers('events/*.handler.ts')
- *
- * // With filtering and logging
- * const handlers = await discoverHandlers('events/*.handler.ts', {
- *   filter: (name, handler) => name.includes('Customer'),
- *   log: true
- * })
- * ```
- */
-export const discoverHandlers = async (pattern, options = {}) => {
-    const { filter } = options;
-    const searchDirectories = getSearchDirectories();
-    const preferCompiled = searchDirectories.some((dir) => dir.includes('/dist/') || dir.includes('\\dist\\'));
-    try {
-        const uniqueFiles = new Set();
-        for (const basePath of searchDirectories) {
-            const discoveredFiles = await discoverFiles(pattern, basePath, preferCompiled);
-            for (const file of discoveredFiles) {
-                uniqueFiles.add(file);
-            }
-        }
-        if (uniqueFiles.size === 0) {
-            logger.warn(`No files found matching pattern: ${pattern}`);
-            return [];
-        }
-        const handlers = await Promise.all([...uniqueFiles].map((file) => loadHandlers(file, filter)));
-        const flatHandlers = handlers.flat();
-        const uniqueHandlers = deduplicateHandlers(flatHandlers);
-        return uniqueHandlers;
-    }
-    catch (error) {
-        logger.error('Discovery failed:', error);
-        return [];
-    }
-};

package/dist/domain/handler-factory.d.ts

@@ -1,49 +0,0 @@
-import { type ZodTypeAny, z } from 'zod';
-import type { EventContext } from '../adapters/cloudevents';
-import type { HandleEventOptions, HandlerConstructor } from './types';
-/**
- * Creates an event handler using the handleEvent pattern
- * Compatible with the new middleware system
- *
- * Supports both inline schemas (Basic Mode) and shared contracts (Advanced Mode).
- *
- * @example Basic Mode - Data-only schema inline
- * ```typescript
- * export default handleEvent({
- *   type: 'orderboss.orders.created',
- *   schema: z.object({ orderId: z.string(), total: z.number() }),
- * }, async (data) => {
- *   console.log('Order created:', data.orderId)
- * })
- * ```
- *
- * @example Advanced Mode - With shared contract
- * ```typescript
- * import { OrderCreatedContract } from '@orderboss/contracts'
- *
- * export default handleEvent(OrderCreatedContract, async (data) => {
- *   console.log('Order created:', data.orderId)
- * })
- * ```
- *
- * @example With tenant filtering
- * ```typescript
- * export default handleEvent({
- *   type: 'orderboss.orders.created',
- *   schema: OrderSchema,
- *   tenantId: ['tenant-a', 'tenant-b'],
- * }, async (data, context) => {
- *   console.log(`Order for tenant ${context?.tenantId}:`, data)
- * })
- * ```
- */
-export declare function handleEvent<TSchema extends ZodTypeAny>(schemaOrOptions: TSchema | HandleEventOptions<TSchema> | HandleEventOptions, handler: (payload: TSchema['_output'], context?: EventContext) => Promise<void> | void, eventType?: string): HandlerConstructor;
-/**
- * Creates an event schema with type inference
- * Automatically enforces the presence of a 'type' field
- */
-export declare function eventSchema<T extends Record<string, ZodTypeAny>>(schema: T & {
-    type: ZodTypeAny;
-}): z.ZodObject<T & {
-    type: ZodTypeAny;
-} extends infer T_1 ? { -readonly [P in keyof T_1]: T_1[P]; } : never, z.core.$strip>;

package/dist/domain/handler-factory.js

@@ -1,169 +0,0 @@
-import { z } from 'zod';
-/**
- * Extracts type value from Zod v4+ value getter
- */
-function extractFromValueGetter(typeField) {
-    if ('value' in typeField && typeof typeField.value === 'string') {
-        return typeField.value;
-    }
-    return undefined;
-}
-/**
- * Extracts type value from Zod _def (v3 and v4)
- */
-function extractFromTypeDef(typeField) {
-    if (!('_def' in typeField))
-        return undefined;
-    const typeDef = typeField._def;
-    // Try _def.values array (Zod v4)
-    if (Array.isArray(typeDef.values) && typeDef.values.length > 0) {
-        return String(typeDef.values[0]);
-    }
-    // Fallback to _def.value (Zod v3)
-    if (typeof typeDef.value === 'string') {
-        return typeDef.value;
-    }
-    return undefined;
-}
-/**
- * Extracts event type from a schema's type field
- */
-function extractFromTypeField(shape) {
-    const typeField = shape.type;
-    if (!typeField || typeof typeField !== 'object' || typeField === null) {
-        return undefined;
-    }
-    const field = typeField;
-    return extractFromValueGetter(field) ?? extractFromTypeDef(field);
-}
-/**
- * Extracts event type from schema
- * Supports both old Zod (_def.value) and new Zod (_def.values / value getter)
- */
-function extractEventTypeFromSchema(schema) {
-    if (!('shape' in schema) || !schema.shape || typeof schema.shape !== 'object') {
-        return undefined;
-    }
-    return extractFromTypeField(schema.shape);
-}
-/**
- * Creates a tenant match function from tenant ID configuration
- */
-function createTenantMatcher(tenantId) {
-    const tenantIds = Array.isArray(tenantId) ? tenantId : [tenantId];
-    return (event) => {
-        if (!event.tenantId)
-            return false;
-        return tenantIds.includes(event.tenantId);
-    };
-}
-/**
- * Combines multiple match functions with AND logic
- */
-function combineMatchers(matchers) {
-    return (event) => matchers.every((matcher) => matcher(event));
-}
-/**
- * Creates an event handler using the handleEvent pattern
- * Compatible with the new middleware system
- *
- * Supports both inline schemas (Basic Mode) and shared contracts (Advanced Mode).
- *
- * @example Basic Mode - Data-only schema inline
- * ```typescript
- * export default handleEvent({
- *   type: 'orderboss.orders.created',
- *   schema: z.object({ orderId: z.string(), total: z.number() }),
- * }, async (data) => {
- *   console.log('Order created:', data.orderId)
- * })
- * ```
- *
- * @example Advanced Mode - With shared contract
- * ```typescript
- * import { OrderCreatedContract } from '@orderboss/contracts'
- *
- * export default handleEvent(OrderCreatedContract, async (data) => {
- *   console.log('Order created:', data.orderId)
- * })
- * ```
- *
- * @example With tenant filtering
- * ```typescript
- * export default handleEvent({
- *   type: 'orderboss.orders.created',
- *   schema: OrderSchema,
- *   tenantId: ['tenant-a', 'tenant-b'],
- * }, async (data, context) => {
- *   console.log(`Order for tenant ${context?.tenantId}:`, data)
- * })
- * ```
- */
-export function handleEvent(schemaOrOptions, handler, eventType) {
-    // Handle both API formats
-    let schema;
-    let finalEventType = eventType;
-    let matchFn;
-    let safeParse = false;
-    if (schemaOrOptions && typeof schemaOrOptions === 'object' && 'schema' in schemaOrOptions) {
-        const options = schemaOrOptions;
-        schema = options.schema;
-        finalEventType = options.type || eventType;
-        safeParse = options.safeParse ?? false;
-        // Build match function from options
-        const matchers = [];
-        if (options.tenantId) {
-            matchers.push(createTenantMatcher(options.tenantId));
-        }
-        if (options.match) {
-            matchers.push(options.match);
-        }
-        if (matchers.length === 1) {
-            matchFn = matchers[0];
-        }
-        else if (matchers.length > 1) {
-            matchFn = combineMatchers(matchers);
-        }
-    }
-    else {
-        schema = schemaOrOptions;
-    }
-    // Try to extract event type from schema if not provided
-    if (!finalEventType) {
-        finalEventType = extractEventTypeFromSchema(schema);
-    }
-    // Fallback to unknown event
-    if (!finalEventType) {
-        finalEventType = 'unknown.event';
-    }
-    // Create handler class with proper naming (e.g., "orderboss.orders.created" → "OrdersCreatedHandler")
-    const handlerName = `${finalEventType
-        .split('.')
-        .slice(-2) // Take last 2 segments (e.g., ["orders", "created"])
-        .map(s => s.charAt(0).toUpperCase() + s.slice(1)) // Capitalize
-        .join('')}Handler`;
-    const HandlerClass = class extends Object {
-        static __eventarcMetadata = {
-            schema,
-            declaredType: finalEventType,
-            match: matchFn,
-            safeParse,
-        };
-        async handle(payload, context) {
-            await Promise.resolve(handler(payload, context));
-        }
-    };
-    // Set the class name properly
-    Object.defineProperty(HandlerClass, 'name', {
-        value: handlerName,
-        configurable: true,
-    });
-    return HandlerClass;
-}
-/**
- * Creates an event schema with type inference
- * Automatically enforces the presence of a 'type' field
- */
-export function eventSchema(schema) {
-    return z.object(schema);
-}

package/dist/domain/index.d.ts

@@ -1,6 +0,0 @@
-export { createContract } from './contract-helper';
-export { discoverHandlers } from './discovery';
-export { eventSchema, handleEvent } from './handler-factory';
-export type { ChannelConfig, ChannelMetadata, EnrichedEvent, EventHandler, HandleEventOptions, HandlerConstructor, HandlerMetadata, IdempotencyStore, InferEventData, MatchFn, RoutingConfig, } from './types';
-export type { HandlerValidationError, ValidationErrorDetail } from './validation';
-export { extractTypeFromSchema, isValidHandler } from './validation';

package/dist/domain/index.js

@@ -1,4 +0,0 @@
-export { createContract } from './contract-helper';
-export { discoverHandlers } from './discovery';
-export { eventSchema, handleEvent } from './handler-factory';
-export { extractTypeFromSchema, isValidHandler } from './validation';

package/dist/domain/types.d.ts

@@ -1,108 +0,0 @@
-/**
- * Domain Types
- *
- * Core business logic types for handlers, events, and domain operations
- */
-import type { ZodTypeAny } from 'zod';
-import type { EventContext } from '../adapters/cloudevents/types';
-/**
- * Event handler interface
- */
-export interface EventHandler<T = unknown> {
-    handle(payload: T, context?: unknown): Promise<void> | void;
-}
-/**
- * Constructor type for event handler classes that implement the EventHandler interface
- */
-export type HandlerConstructor<T = unknown> = (new (...args: unknown[]) => EventHandler<T>) & {
-    __eventarcMetadata?: {
-        schema: ZodTypeAny;
-        declaredType?: string;
-        match?: (event: EnrichedEvent<T>) => boolean;
-        safeParse?: boolean;
-    };
-};
-/**
- * Enriched event with both data and context
- */
-export interface EnrichedEvent<T> extends EventContext {
-    data: T;
-    /** Tenant identifier for multi-tenant event routing */
-    tenantId?: string;
-}
-/**
- * Match function type for custom event matching
- */
-export type MatchFn<T> = (event: EnrichedEvent<T>) => boolean;
-/**
- * Handler metadata attached to handler constructors
- */
-export type HandlerMetadata<S extends ZodTypeAny> = {
-    schema: S;
-    declaredType?: string;
-    match?: MatchFn<unknown>;
-    safeParse: boolean;
-};
-/**
- * Channel metadata for NATS JetStream routing
- */
-export interface ChannelMetadata {
-    /** JetStream stream name (e.g., 'ORDERS') */
-    stream: string;
-    /** NATS subject (defaults to event type if not specified) */
-    subject: string;
-}
-/**
- * Channel configuration input (subject is optional, defaults to type)
- */
-export interface ChannelConfig {
-    /** JetStream stream name (e.g., 'ORDERS') */
-    stream: string;
-    /** NATS subject (optional, defaults to event type) */
-    subject?: string;
-}
-/**
- * Options for creating event handlers
- *
- * Note: In Zod v4, we use a more relaxed schema constraint to allow
- * contracts defined in external packages to work correctly.
- */
-export interface HandleEventOptions<S = ZodTypeAny> {
-    schema: S;
-    type?: string;
-    match?: MatchFn<unknown>;
-    safeParse?: boolean;
-    /** Filter events by tenant ID(s). If set, only events matching these tenant(s) are processed. */
-    tenantId?: string | string[];
-    /** Channel metadata for NATS JetStream routing (optional) */
-    channel?: ChannelConfig;
-}
-/**
- * Routing configuration for type → subject → stream mapping
- */
-export interface RoutingConfig {
-    /** Map event type prefix to NATS subject prefix, e.g., { 'orderboss.orders': 'orders' } */
-    typeToSubjectMap?: Record<string, string>;
-    /** Map event type prefix to stream name, e.g., { 'orderboss.orders': 'ORDERS' } */
-    typeToStreamMap?: Record<string, string>;
-    /** Default subject prefix when no mapping found */
-    defaultSubjectPrefix?: string;
-}
-/**
- * Idempotency store interface for deduplication
- */
-export interface IdempotencyStore {
-    /** Check if a message has already been processed */
-    has(messageId: string): Promise<boolean> | boolean;
-    /** Mark a message as processed */
-    add(messageId: string, ttlMs?: number): Promise<void> | void;
-    /** Clear the store (useful for testing) */
-    clear?(): Promise<void> | void;
-}
-/**
- * Type helper to extract data type from a Zod schema
- * Handles both data-only schemas and full CloudEvent schemas with a 'data' field
- */
-export type InferEventData<S extends ZodTypeAny> = S['_output'] extends {
-    data: infer D;
-} ? D : S['_output'];

package/dist/domain/types.js

@@ -1,6 +0,0 @@
-/**
- * Domain Types
- *
- * Core business logic types for handlers, events, and domain operations
- */
-export {};

package/dist/domain/validation.d.ts

@@ -1,37 +0,0 @@
-/**
- * Domain Validation
- *
- * Core business logic for validating events, handlers, and schemas
- * Contains no infrastructure concerns - pure domain logic
- */
-import type { ZodTypeAny } from 'zod';
-/**
- * Validation error detail for individual field errors
- */
-export interface ValidationErrorDetail {
-    code?: string;
-    message: string;
-    path?: (string | number)[];
-    expected?: string;
-    received?: string;
-    validation?: string;
-}
-/**
- * Handler validation error with handler information
- */
-export interface HandlerValidationError {
-    handlerName: string;
-    validationErrors: ValidationErrorDetail[];
-}
-/**
- * Validates whether an exported value is a valid event handler
- * Checks for either eventarc metadata or a handle method in the prototype
- */
-export declare function isValidHandler(value: unknown): boolean;
-/**
- * Extracts the event type from a Zod schema by looking for a literal 'type' field
- *
- * @param schema - Zod schema to extract type from
- * @returns Event type string or undefined if not found
- */
-export declare const extractTypeFromSchema: (schema: ZodTypeAny) => string | undefined;

package/dist/domain/validation.js

@@ -1,53 +0,0 @@
-/**
- * Domain Validation
- *
- * Core business logic for validating events, handlers, and schemas
- * Contains no infrastructure concerns - pure domain logic
- */
-/**
- * Type guards for schema shape analysis
- */
-const hasShape = (schema) => 'shape' in schema &&
-    schema.shape !== null &&
-    schema.shape !== undefined &&
-    typeof schema.shape === 'object';
-const hasTypeField = (shape) => 'type' in shape &&
-    shape.type !== null &&
-    shape.type !== undefined &&
-    typeof shape.type === 'object' &&
-    'value' in shape.type;
-const extractTypeValue = (typeField) => typeof typeField.value === 'string' ? typeField.value : undefined;
-/**
- * Safely extracts type from schema shape
- */
-const safeExtractType = (schema) => {
-    if (!hasShape(schema))
-        return undefined;
-    if (!hasTypeField(schema.shape))
-        return undefined;
-    return extractTypeValue(schema.shape.type);
-};
-/**
- * Validates whether an exported value is a valid event handler
- * Checks for either eventarc metadata or a handle method in the prototype
- */
-export function isValidHandler(value) {
-    if (typeof value !== 'function')
-        return false;
-    const handler = value;
-    return !!(handler.__eventarcMetadata || handler.prototype?.handle);
-}
-/**
- * Extracts the event type from a Zod schema by looking for a literal 'type' field
- *
- * @param schema - Zod schema to extract type from
- * @returns Event type string or undefined if not found
- */
-export const extractTypeFromSchema = (schema) => {
-    try {
-        return safeExtractType(schema);
-    }
-    catch {
-        return undefined;
-    }
-};

package/dist/infrastructure/errors.d.ts

@@ -1,53 +0,0 @@
-import type { Context } from 'hono';
-import type { HandlerValidationError } from '../domain';
-export type ErrorResponse = {
-    error: {
-        type: string;
-        message: string;
-        timestamp: string;
-        details?: unknown;
-    };
-};
-export type SuccessResponse = {
-    message: string;
-    timestamp: string;
-};
-export type ValidationError = {
-    type: 'ValidationError';
-    eventType: string;
-    message: string;
-    details: HandlerValidationError[];
-};
-export type NoHandlerFoundError = {
-    type: 'NoHandlerFoundError';
-    eventType: string;
-    message: string;
-};
-export type CloudEventParseError = {
-    type: 'CloudEventParseError';
-    message: string;
-    cause?: Error;
-};
-/**
- * Handles errors with full context logging
- */
-export declare const handleErrorWithContext: (error: Error, context: Context, additionalInfo?: Record<string, unknown>) => {
-    message: string;
-    stack: string | undefined;
-    url: string;
-    method: string;
-    headers: {
-        [k: string]: string;
-    };
-};
-/**
- * Converts an error to a standardized response format
- */
-export declare const errorToResponse: (error: Error, type?: string) => ErrorResponse;
-/**
- * Creates a standardized error response
- */
-export declare const createErrorResponse: (type: string, message: string, details?: unknown) => ErrorResponse;
-export declare const createValidationError: (eventType: string, details: HandlerValidationError[]) => ValidationError;
-export declare const createNoHandlerFoundError: (eventType: string) => NoHandlerFoundError;
-export declare const createCloudEventParseError: (message: string, cause?: Error) => CloudEventParseError;