Add wildcard events, template generation, count(), and array itemTransform

[vgpastor]

Summary

This release adds four user-requested features to improve the bulk import API: wildcard event subscription for monitoring all events at once, CSV template generation with synthetic example data, a count() method to get total records before processing, and per-item transformation for array fields.

Key Changes

• Wildcard event subscription (onAny() / offAny())

  • Subscribe to all domain events regardless of type via importer.onAny(handler)
  • Simplifies SSE/WebSocket relay patterns where all events need forwarding
  • Handlers are isolated; errors don't propagate to other handlers

• Enhanced generateTemplate() with example rows

  • Now accepts { exampleRows: N } option to generate synthetic data rows
  • Each field type produces appropriate examples: fake emails, ISO dates, numbers, booleans, arrays
  • Fields with defaultValue use that value instead of generated examples
  • Backward compatible: calling without options returns header-only (existing behavior)

• New count() method

  • Returns total record count from configured source without modifying import state
  • Useful for progress bars and UI feedback before calling start()
  • Requires from() to be called first; throws if source not configured

• Array field itemTransform option

  • New optional itemTransform: (item: string) => string on array fields
  • Applied to each element after splitting by separator
  • Enables normalization (e.g., lowercase, trim) of array items
  • Backward compatible: existing code without itemTransform works unchanged

• Deferred import:started event emission

  • Event now fires after yielding to microtask queue (await Promise.resolve())
  • Allows handlers registered after start() on the same tick to receive the event
  • Fixes race condition where late-registered handlers would miss the event

• API refinements

  • getStatus() now returns both status and state (deprecated alias) for backward compatibility
  • Exported ParsedRecord type for processor callback signatures
  • Exported GenerateTemplateOptions type for template generation
  • Updated RecordProcessorFn to accept ParsedRecord instead of RawRecord

Implementation Details

• EventBus extended with wildcardHandlers Set and onAny()/offAny() methods
• Template generation uses a private generateExampleValue() helper that switches on field type
• count() streams through source and parser without creating import state
• Array transformation in SchemaValidator applies itemTransform after split and trim
• Deferred emission in StartImport uses await Promise.resolve() before emitting import:started

Testing

• 477 lines of comprehensive acceptance tests covering all new features
• Unit tests for EventBus wildcard handlers and error isolation
• All existing tests updated to use status instead of deprecated state

https://claude.ai/code/session_0152RPJq1WLJhnyLDFZxQwF7