@crossdelta/cloudevents 0.5.3 → 0.5.5

package/README.md

@@ -11,7 +11,7 @@ Type-safe event-driven microservices with [NATS](https://nats.io) and [Zod](http
   └──────────────┘      │              │      └──────────────┘
                         └──────────────┘
         │                                            │
-        │  publishNatsRawEvent(...)                  │  handleEvent(...)
+        │  publish(...)                              │  handleEvent(...)
         ▼                                            ▼
   ┌──────────────┐                            ┌──────────────┐
   │ { orderId,   │                            │ Zod schema   │
@@ -286,14 +286,32 @@ export const OrdersCreatedContract = createContract({
 ```typescript
 interface ChannelConfig {
   stream: string    // JetStream stream name (e.g., 'ORDERS')
-  subject?: string  // NATS subject (defaults to event type)
+  subject?: string  // NATS subject (optional override)
 }
 ```
 
-**Subject Defaulting:**
-- If `subject` is **not provided**, it defaults to the event `type`
-- This follows the convention: `orders.created` → subject `orders.created`
-- Override when needed: `subject: 'orders.v1.created'`
+**Subject Routing (CRITICAL):**
+- **Without `subject`**: Domain is auto-pluralized: `customer.created` → subject `customers.created`
+- **With `subject`**: Uses exact subject specified (no auto-pluralization)
+- **Why pluralize**: Stream subjects are plural (`customers.*`), event types are singular (`customer.created`)
+
+**Examples:**
+```typescript
+// Auto-pluralized subject
+createContract({
+  type: 'order.created',          // Event type: singular
+  channel: { stream: 'ORDERS' },  // Subject: orders.created (plural)
+})
+
+// Custom subject (no auto-pluralization)
+createContract({
+  type: 'order.created',
+  channel: { 
+    stream: 'ORDERS',
+    subject: 'orders.v1.created'  // Exact subject, no auto-pluralization
+  },
+})
+```
 
 ### Multiple Events, Same Stream
 

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

@@ -1,59 +1,19 @@
 import type { ZodTypeAny } from 'zod';
 import { type RoutingConfig } from '../domain';
 export interface PublishNatsEventOptions {
-    /**
-     * NATS URL(s), e.g., "nats://localhost:4222".
-     * Defaults to `process.env.NATS_URL` or `nats://localhost:4222`.
-     */
     servers?: string;
-    /**
-     * CloudEvent source identifier (e.g., "orderboss://orders-service").
-     */
     source?: string;
-    /**
-     * Optional CloudEvent subject (e.g., an order ID). Not to be confused with the NATS subject.
-     */
     subject?: string;
-    /**
-     * Tenant identifier for multi-tenant event routing.
-     * Will be added as a CloudEvent extension attribute.
-     */
     tenantId?: string;
 }
-/**
- * Derives a NATS subject from a CloudEvent type using routing configuration.
- *
- * @example
- * ```typescript
- * const config: RoutingConfig = {
- *   typeToSubjectMap: { 'orderboss.orders': 'orders' },
- *   defaultSubjectPrefix: 'events',
- * }
- *
- * deriveSubjectFromType('orderboss.orders.created', config)
- * // Returns: 'orders.created'
- *
- * deriveSubjectFromType('unknown.event.type', config)
- * // Returns: 'events.unknown.event.type'
- * ```
- */
-export declare function deriveSubjectFromType(eventType: string, config?: RoutingConfig): string;
-/**
- * Derives a JetStream stream name from a CloudEvent type using routing configuration.
- */
-export declare function deriveStreamFromType(eventType: string, config?: RoutingConfig): string | undefined;
-export declare function publishNatsEvent<T extends ZodTypeAny>(subjectName: string, schema: T, eventData: unknown, options?: PublishNatsEventOptions): Promise<string>;
-export declare function publishNatsRawEvent(subjectName: string, eventType: string, eventData: unknown, options?: PublishNatsEventOptions): Promise<string>;
-/**
- * Simplified publish function where subject equals event type.
- *
- * @example
- * ```typescript
- * await publish('orders.created', { orderId: '123', total: 99.99 })
- * ```
- */
-export declare function publish(eventType: string, eventData: unknown, options?: PublishNatsEventOptions): Promise<string>;
-/**
- * @internal Resets the cached NATS connection. Intended for testing only.
- */
-export declare function __resetNatsPublisher(): void;
+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

@@ -2,49 +2,59 @@ import { connect, StringCodec } from 'nats';
 import { extractTypeFromSchema } from '../domain';
 import { createValidationError, logger } from '../infrastructure';
 const sc = StringCodec();
-/**
- * Derives a NATS subject from a CloudEvent type using routing configuration.
- *
- * @example
- * ```typescript
- * const config: RoutingConfig = {
- *   typeToSubjectMap: { 'orderboss.orders': 'orders' },
- *   defaultSubjectPrefix: 'events',
- * }
- *
- * deriveSubjectFromType('orderboss.orders.created', config)
- * // Returns: 'orders.created'
- *
- * deriveSubjectFromType('unknown.event.type', config)
- * // Returns: 'events.unknown.event.type'
- * ```
- */
-export function deriveSubjectFromType(eventType, config) {
+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) {
-        // No mapping configured, use type as-is (replace dots with dots is a no-op)
         return config?.defaultSubjectPrefix ? `${config.defaultSubjectPrefix}.${eventType}` : eventType;
     }
-    // Find the longest matching prefix
     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];
-            // Remove leading dot from suffix if present
             const cleanSuffix = suffix.startsWith('.') ? suffix.slice(1) : suffix;
             return cleanSuffix ? `${mappedPrefix}.${cleanSuffix}` : mappedPrefix;
         }
     }
-    // No match found, use default prefix or type as-is
     return config.defaultSubjectPrefix ? `${config.defaultSubjectPrefix}.${eventType}` : eventType;
-}
-/**
- * Derives a JetStream stream name from a CloudEvent type using routing configuration.
- */
-export function deriveStreamFromType(eventType, config) {
+};
+export const deriveStreamFromType = (eventType, config) => {
     if (!config?.typeToStreamMap)
         return undefined;
-    // Find the longest matching prefix
     const sortedPrefixes = Object.keys(config.typeToStreamMap).sort((a, b) => b.length - a.length);
     for (const prefix of sortedPrefixes) {
         if (eventType.startsWith(prefix)) {
@@ -52,25 +62,26 @@ export function deriveStreamFromType(eventType, config) {
         }
     }
     return undefined;
-}
-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) {
+};
+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.');
@@ -91,39 +102,14 @@ export async function publishNatsEvent(subjectName, schema, eventData, options)
         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 }),
-        ...(options?.tenantId && { tenantid: options.tenantId }), // CloudEvents extension (lowercase)
-    };
-    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;
-}
-/**
- * Simplified publish function where subject equals event type.
- *
- * @example
- * ```typescript
- * await publish('orders.created', { orderId: '123', total: 99.99 })
- * ```
- */
-export async function publish(eventType, eventData, options) {
-    return publishNatsRawEvent(eventType, eventType, eventData, options);
-}
-/**
- * @internal Resets the cached NATS connection. Intended for testing only.
- */
-export function __resetNatsPublisher() {
+};
+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;
-}
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossdelta/cloudevents",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "CloudEvents toolkit for TypeScript - Zod validation, handler discovery, NATS JetStream",
   "author": "crossdelta",
   "license": "MIT",