refactor: rename collection → noun in CDC API surface

Aligns with .do ecosystem naming convention (Noun() from digital-objects).
Entity types are singular: contact.created, deal.updated, invoice.deleted.

- emitChange(op, noun, docId, doc, prev) — was (type, collection, ...)
- CDCCollection constructor takes noun (singular entity type name)
- cdc-processor uses noun variable (SQL column stays 'collection')

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: nathanclevenger

core/src/cdc-delta.ts

@@ -67,7 +67,7 @@ function parseRecordJson(str: string, fieldName: string): Record<string, unknown
 
 /**
  * Extracts operation type from the CDC event name.
- * Expected format: `{collection}.{op}` (e.g. 'contacts.created', 'users.deleted')
+ * Expected format: `{noun}.{op}` (e.g. 'contact.created', 'user.deleted')
  */
 export function extractOp(eventName: string): CDCOp {
   const dot = eventName.lastIndexOf('.')

core/src/cdc-processor.ts

@@ -320,18 +320,19 @@ export class CDCProcessorDO extends DurableObject<Env> {
   /**
    * Process a single CDC event.
    * In the new Event format: data contains { type, id, ...fields }, meta may contain prev/bookmark.
+   * The `type` field in data is the singular noun (e.g. 'contact', 'deal').
    */
   private async processEvent(event: CDCEvent): Promise<void> {
-    const { type: _entityType, id: docId, ...docFields } = event.data
-    const collection = event.data.type
+    const { type: _noun, id: docId, ...docFields } = event.data
+    const noun = event.data.type
     const ts = event.ts
     const meta = event.meta as Record<string, unknown>
     const prev = meta.prev as Record<string, unknown> | undefined
     const bookmark = meta.bookmark as string | undefined
     const op = this.extractOp(event.event)
 
-    // Get existing document state from SQLite
-    const existing = this.getDocumentState(collection, docId)
+    // Get existing document state from SQLite (column named 'collection' for backward compat)
+    const existing = this.getDocumentState(noun, docId)
 
     let newData: Record<string, unknown>
     let prevData: Record<string, unknown> | null = null
@@ -364,13 +365,13 @@ export class CDCProcessorDO extends DurableObject<Env> {
       bookmark: bookmark ?? undefined,
       deleted,
     }
-    this.upsertDocumentState(collection, docState)
+    this.upsertDocumentState(noun, docState)
 
-    // Add to pending_deltas in SQLite
+    // Add to pending_deltas in SQLite (column named 'collection' for backward compat)
     this.ctx.storage.sql.exec(
       `INSERT INTO pending_deltas (collection, doc_id, op, data, prev, ts, bookmark)
        VALUES (?, ?, ?, ?, ?, ?, ?)`,
-      collection,
+      noun,
       docId,
       op,
       JSON.stringify(newData),
@@ -379,13 +380,13 @@ export class CDCProcessorDO extends DurableObject<Env> {
       bookmark ?? null,
     )
 
-    // Ensure manifest exists for this collection
-    this.ensureManifest(collection)
+    // Ensure manifest exists for this noun
+    this.ensureManifest(noun)
   }
 
   /**
    * Extract operation type from the event name.
-   * Format: `{collection}.{op}` (e.g. 'contacts.created')
+   * Format: `{noun}.{op}` (e.g. 'contact.created')
    */
   private extractOp(eventName: string): 'created' | 'updated' | 'deleted' {
     const dot = eventName.lastIndexOf('.')

core/src/cdc.ts

@@ -27,23 +27,25 @@ export interface Collection<T extends Record<string, unknown>> {
  * - The previous document state (if trackPrevious is enabled)
  * - SQLite bookmark for PITR
  *
+ * @param noun - Singular entity type name (e.g. 'contact', 'deal', 'invoice')
+ *
  * @example
  * ```typescript
- * const users = new CDCCollection(
- *   this.collection<User>('users'),
+ * const contacts = new CDCCollection(
+ *   this.collection<Contact>('contacts'),
  *   this.events,
- *   'users'
+ *   'contact'  // singular noun — events become contact.created, contact.updated, etc.
  * )
  *
- * // This emits a CDC event
- * users.put('user-123', { name: 'Alice', active: true })
+ * // This emits a CDC event: { type: 'cdc', event: 'contact.created', data: { type: 'contact', id, ... } }
+ * contacts.put('contact-123', { name: 'Alice', active: true })
  * ```
  */
 export class CDCCollection<T extends Record<string, unknown>> {
   constructor(
     private collection: Collection<T>,
     private emitter: EventEmitter,
-    private name: string
+    private noun: string
   ) {}
 
   /**
@@ -61,9 +63,9 @@ export class CDCCollection<T extends Record<string, unknown>> {
     this.collection.put(id, doc)
 
     if (prev) {
-      this.emitter.emitChange('updated', this.name, id, doc, prev)
+      this.emitter.emitChange('updated', this.noun, id, doc, prev)
     } else {
-      this.emitter.emitChange('created', this.name, id, doc)
+      this.emitter.emitChange('created', this.noun, id, doc)
     }
   }
 
@@ -75,7 +77,7 @@ export class CDCCollection<T extends Record<string, unknown>> {
     const deleted = this.collection.delete(id)
 
     if (deleted && prev) {
-      this.emitter.emitChange('deleted', this.name, id, undefined, prev)
+      this.emitter.emitChange('deleted', this.noun, id, undefined, prev)
     }
 
     return deleted
@@ -125,7 +127,7 @@ export class CDCCollection<T extends Record<string, unknown>> {
 
     // Emit delete for each document
     for (const id of keys) {
-      this.emitter.emitChange('deleted', this.name, id)
+      this.emitter.emitChange('deleted', this.noun, id)
     }
 
     return count

core/src/emitter.ts

@@ -198,21 +198,27 @@ export class EventEmitter {
   }
 
   /**
-   * Emit a CDC (Change Data Capture) event for a collection change.
+   * Emit a CDC (Change Data Capture) event for an entity mutation.
    * Automatically captures the SQLite bookmark for PITR (point-in-time recovery).
    * Only emits if the `cdc` option is enabled.
+   *
+   * @param op - The operation: 'created', 'updated', or 'deleted'
+   * @param noun - Singular entity type name (e.g. 'contact', 'deal', 'invoice')
+   * @param docId - Document ID
+   * @param doc - Current document state (omit for deletes)
+   * @param prev - Previous document state (when trackPrevious is enabled)
    */
-  emitChange(type: 'created' | 'updated' | 'deleted', collection: string, docId: string, doc?: Record<string, unknown>, prev?: Record<string, unknown>): void {
+  emitChange(op: 'created' | 'updated' | 'deleted', noun: string, docId: string, doc?: Record<string, unknown>, prev?: Record<string, unknown>): void {
     if (!this.options.cdc) return
 
-    this.getBookmarkAndEmit(type, collection, docId, doc, prev).catch((error) => {
-      this.log.error('Failed to emit CDC event', { error: error instanceof Error ? error.message : String(error), collection, docId })
+    this.getBookmarkAndEmit(op, noun, docId, doc, prev).catch((error) => {
+      this.log.error('Failed to emit CDC event', { error: error instanceof Error ? error.message : String(error), noun, docId })
     })
   }
 
   private async getBookmarkAndEmit(
-    type: 'created' | 'updated' | 'deleted',
-    collection: string,
+    op: 'created' | 'updated' | 'deleted',
+    noun: string,
     docId: string,
     doc?: Record<string, unknown>,
     prev?: Record<string, unknown>,
@@ -226,8 +232,8 @@ export class EventEmitter {
 
     this.emit({
       type: 'cdc',
-      event: `${collection}.${type}`,
-      data: { type: collection, id: docId, ...(doc ?? {}) },
+      event: `${noun}.${op}`,
+      data: { type: noun, id: docId, ...(doc ?? {}) },
       meta: {
         ...(this.options.trackPrevious && prev ? { prev } : {}),
         ...(bookmark ? { bookmark } : {}),