event-emission 0.2.0 → 0.2.1

package/src/index.ts

@@ -21,18 +21,16 @@ declare global {
 export type {
   AddEventListenerOptionsLike,
   AsyncIteratorOptions,
-  DOMEventLike,
-  DOMEventTargetLike,
+  DispatchEventInput,
   EmissionEvent,
+  EventListenerLike,
+  EventListenerObject,
+  EventListenerOptionsLike,
   EventsIteratorOptions,
   EventTargetLike,
-  InteropOptions,
   Listener,
   MinimalAbortSignal,
-  ObservableLike,
-  Observer,
   OverflowStrategy,
-  Subscription,
   WildcardEvent,
   WildcardListener,
 } from './types';
@@ -47,32 +45,5 @@ export type {
 } from './factory';
 export { createEventTarget } from './factory';
 
-// Re-export observation utilities and types
-export type {
-  ArrayMutationDetail,
-  ArrayMutationMethod,
-  ObservableEventMap,
-  ObserveOptions,
-  PropertyChangeDetail,
-} from './observe';
-export {
-  getOriginal,
-  isObserved,
-  ORIGINAL_TARGET,
-  PROXY_MARKER,
-  setupEventForwarding,
-} from './observe';
-
-// Re-export Observable
-export type {
-  Subscriber,
-  SubscriptionObserverInterface as SubscriptionObserver,
-} from './observable';
-export { Observable } from './observable';
-
-// Re-export interop
-export type { FromEventTargetOptions } from './interop';
-export { forwardToEventTarget, fromEventTarget, pipe } from './interop';
-
 // Re-export EventEmission class
 export { EventEmission } from './event-emission';

package/src/{interop.ts → interoperability.ts}

@@ -7,6 +7,8 @@ import type {
   InteropOptions,
 } from './types';
 
+export type { DOMEventLike, DOMEventTargetLike, InteropOptions } from './types';
+
 /**
  * Forward events from an EventEmission target to a DOM EventTarget.
  *
@@ -43,11 +45,24 @@ export function forwardToEventTarget<E extends Record<string, unknown>>(
   const unsubscribe = source.addWildcardListener(
     '*',
     (event) => {
-      // Create a DOM-like event object
-      const domEvent: DOMEventLike = {
-        type: event.originalType,
-        detail: event.detail,
-      };
+      // Use CustomEvent when available to preserve DOM event semantics.
+      const CustomEventCtor = (globalThis as { CustomEvent?: typeof CustomEvent })
+        .CustomEvent;
+      const domEvent: DOMEventLike =
+        typeof CustomEventCtor === 'function'
+          ? new CustomEventCtor(event.originalType, {
+              detail: event.detail,
+              bubbles: event.bubbles,
+              cancelable: event.cancelable,
+              composed: event.composed,
+            })
+          : {
+              type: event.originalType,
+              detail: event.detail,
+              bubbles: event.bubbles,
+              cancelable: event.cancelable,
+              composed: event.composed,
+            };
       target.dispatchEvent(domEvent);
     },
     options,
@@ -144,6 +159,9 @@ export function fromEventTarget<E extends Record<string, unknown>>(
       emitter.dispatchEvent({
         type,
         detail: (event.detail ?? event) as E[typeof type],
+        bubbles: event.bubbles,
+        cancelable: event.cancelable,
+        composed: event.composed,
       } as unknown as EmissionEvent<E[keyof E & string]>);
     };
     handlers.set(type, handler);
@@ -266,7 +284,7 @@ export function pipe<E extends Record<string, unknown>>(
       target.dispatchEvent({
         type: event.originalType,
         detail: event.detail as E[keyof E & string],
-      } as unknown as EmissionEvent<E[keyof E & string]>);
+      } as unknown as Parameters<typeof target.dispatchEvent>[0]);
     },
     options,
   );

package/src/observe.ts

@@ -45,8 +45,10 @@ export const ORIGINAL_TARGET = Symbol.for('@lasercat/event-emission/original');
 export interface ObserveOptions {
   /** Enable deep observation of nested objects (default: true) */
   deep?: boolean;
-  /** Clone strategy for previous state (default: 'path') */
+  /** Clone strategy for previous state (default: 'path'); 'deep' uses structuredClone or deepClone */
   cloneStrategy?: 'shallow' | 'deep' | 'path';
+  /** Optional deep clone fallback for runtimes without structuredClone */
+  deepClone?: <T>(value: T) => T;
 }
 
 /** Event detail for property changes */
@@ -115,11 +117,17 @@ const ARRAY_MUTATORS = new Set<ArrayMutationMethod>([
 // Internal Types
 // =============================================================================
 
+type ResolvedObserveOptions = {
+  deep: boolean;
+  cloneStrategy: 'shallow' | 'deep' | 'path';
+  deepClone?: ObserveOptions['deepClone'];
+};
+
 interface ProxyContext<T extends object> {
   eventTarget: EventTargetLike<ObservableEventMap<T>>;
   /** Reference to the original (unproxied) root object for cloning */
   originalRoot: T;
-  options: Required<ObserveOptions>;
+  options: ResolvedObserveOptions;
 }
 
 // =============================================================================
@@ -161,22 +169,18 @@ function isArrayMutator(prop: string | symbol): prop is ArrayMutationMethod {
 
 /** Clone along changed path for efficiency */
 function cloneAlongPath(obj: unknown, path?: string): unknown {
-  if (obj === null || typeof obj !== 'object') {
-    return obj;
-  }
+  const isArray = Array.isArray(obj);
+  const rootClone = isArray
+    ? [...(obj as unknown[])]
+    : { ...(obj as Record<string, unknown>) };
 
-  if (!path) {
-    return Array.isArray(obj) ? [...obj] : { ...obj };
+  if (!path || isArray) {
+    return rootClone;
   }
 
   const parts = path.split('.');
 
-  if (Array.isArray(obj)) {
-    // For arrays, shallow copy
-    return [...obj];
-  }
-
-  const result: Record<string, unknown> = { ...obj };
+  const result = rootClone as Record<string, unknown>;
 
   let current: Record<string, unknown> = result;
   // Clone all objects along the path, INCLUDING the leaf
@@ -202,6 +206,7 @@ function cloneForComparison(
   obj: unknown,
   strategy: 'shallow' | 'deep' | 'path',
   changedPath?: string,
+  deepClone?: ObserveOptions['deepClone'],
 ): unknown {
   if (obj === null || typeof obj !== 'object') return obj;
 
@@ -210,6 +215,14 @@ function cloneForComparison(
       return Array.isArray(obj) ? [...obj] : { ...obj };
 
     case 'deep':
+      if (deepClone) {
+        return deepClone(obj);
+      }
+      if (typeof structuredClone !== 'function') {
+        throw new Error(
+          "structuredClone is not available in this runtime; provide observe.deepClone, or use cloneStrategy 'path' or 'shallow'.",
+        );
+      }
       return structuredClone(obj);
 
     case 'path':
@@ -300,6 +313,7 @@ function createArrayMethodInterceptor<T extends object>(
       context.originalRoot,
       context.options.cloneStrategy,
       path,
+      context.options.deepClone,
     );
     const previousItems = [...array];
 
@@ -418,6 +432,7 @@ function createObservableProxyInternal<T extends object>(
         context.originalRoot,
         context.options.cloneStrategy,
         propPath,
+        context.options.deepClone,
       );
 
       const success = Reflect.set(obj, prop, value, receiver);
@@ -457,6 +472,7 @@ function createObservableProxyInternal<T extends object>(
         context.originalRoot,
         context.options.cloneStrategy,
         propPath,
+        context.options.deepClone,
       );
 
       const success = Reflect.deleteProperty(obj, prop);
@@ -544,6 +560,8 @@ export function setupEventForwarding<T extends object>(
   target: EventTargetLike<ObservableEventMap<T>>,
 ): () => void {
   const handlers = new Map<string, (event: unknown) => void>();
+  const sourceAddEventListener = source.addEventListener.bind(source);
+  const sourceRemoveEventListener = source.removeEventListener.bind(source);
 
   const forwardHandler = (type: string) => (event: unknown) => {
     const detail = (event as MinimalCustomEvent).detail ?? event;
@@ -566,7 +584,7 @@ export function setupEventForwarding<T extends object>(
     if (!handlers.has(type) && type !== 'update' && !type.startsWith('update:')) {
       const handler = forwardHandler(type);
       handlers.set(type, handler);
-      source.addEventListener(type, handler);
+      sourceAddEventListener(type, handler);
     }
     return originalAddEventListener(
       type as keyof ObservableEventMap<T> & string,
@@ -587,7 +605,7 @@ export function setupEventForwarding<T extends object>(
       originalAddEventListener;
     // Clean up all forwarding handlers
     for (const [type, handler] of handlers) {
-      source.removeEventListener(type, handler);
+      sourceRemoveEventListener(type, handler);
     }
     handlers.clear();
   };
@@ -664,6 +682,9 @@ export function getOriginal<T extends object>(proxy: T): T {
  * including nested objects and array mutations. Events are dispatched to the
  * provided event target for each change.
  *
+ * If the target is an EventTarget, event forwarding is set up automatically and
+ * cleaned up when the event target completes.
+ *
  * Note: This is typically called internally by createEventTarget with observe: true.
  * You usually don't need to call this directly.
  *
@@ -709,9 +730,10 @@ export function createObservableProxy<T extends object>(
   eventTarget: EventTargetLike<ObservableEventMap<T>>,
   options?: ObserveOptions,
 ): T {
-  const resolvedOptions: Required<ObserveOptions> = {
+  const resolvedOptions: ResolvedObserveOptions = {
     deep: options?.deep ?? true,
     cloneStrategy: options?.cloneStrategy ?? 'path',
+    deepClone: options?.deepClone,
   };
 
   const context: ProxyContext<T> = {
@@ -724,7 +746,22 @@ export function createObservableProxy<T extends object>(
 
   // Set up event forwarding if target is already an EventTarget
   if (isEventTarget(target)) {
-    setupEventForwarding(target as unknown as MinimalEventTarget, eventTarget);
+    const cleanupForwarding = setupEventForwarding(
+      target as unknown as MinimalEventTarget,
+      eventTarget,
+    );
+    const maybeComplete = (eventTarget as { complete?: () => void }).complete;
+    if (typeof maybeComplete === 'function') {
+      const originalComplete = maybeComplete.bind(eventTarget);
+      let cleaned = false;
+      (eventTarget as { complete: () => void }).complete = () => {
+        if (!cleaned) {
+          cleaned = true;
+          cleanupForwarding();
+        }
+        return originalComplete();
+      };
+    }
   }
 
   return proxy;

package/src/symbols.ts

@@ -1,5 +1,5 @@
 /**
- * Symbol.observable polyfill for TC39 Observable interop.
+ * Symbol.observable polyfill for TC39 Observable interoperability.
  * This ensures the symbol exists even in environments that don't support it natively.
  */
 export const SymbolObservable: symbol =

package/src/types.ts

@@ -10,9 +10,9 @@ declare global {
  * Event structure passed to listeners.
  * Matches the shape of a DOM CustomEvent to ensure compatibility.
  */
-export interface EmissionEvent<Detail> {
+export interface EmissionEvent<Detail, Type extends string = string> {
   /** The event type identifier. */
-  readonly type: string;
+  readonly type: Type;
   /** The event payload data. */
   readonly detail: Detail;
 
@@ -20,6 +20,8 @@ export interface EmissionEvent<Detail> {
   readonly bubbles: boolean;
   /** DOM Event compatibility: true if the event can be cancelled. */
   readonly cancelable: boolean;
+  /** DOM Event compatibility: legacy alias for stopPropagation(). */
+  cancelBubble: boolean;
   /** DOM Event compatibility: true if the event can cross Shadow DOM boundaries. */
   readonly composed: boolean;
   /** DOM Event compatibility: the object currently processing the event. */
@@ -30,6 +32,10 @@ export interface EmissionEvent<Detail> {
   readonly eventPhase: number;
   /** DOM Event compatibility: true if the event was dispatched by the user agent. */
   readonly isTrusted: boolean;
+  /** DOM Event compatibility: legacy alias for defaultPrevented. */
+  returnValue: boolean;
+  /** DOM Event compatibility: legacy alias for target. */
+  readonly srcElement: unknown;
   /** DOM Event compatibility: the object that originally dispatched the event. */
   readonly target: unknown;
   /** DOM Event compatibility: the time at which the event was created. */
@@ -37,6 +43,8 @@ export interface EmissionEvent<Detail> {
 
   /** DOM Event compatibility: returns the path of nodes the event will travel through. */
   composedPath(): unknown[];
+  /** DOM Event compatibility: legacy initializer. */
+  initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
   /** DOM Event compatibility: cancels the event if it is cancelable. */
   preventDefault(): void;
   /** DOM Event compatibility: prevents other listeners from being called. */
@@ -55,11 +63,11 @@ export interface EmissionEvent<Detail> {
  * Event passed to wildcard listeners, includes the original event type.
  */
 export interface WildcardEvent<E extends Record<string, unknown>> extends EmissionEvent<
-  E[keyof E]
+  E[keyof E],
+  '*' | `${string}:*`
 > {
   readonly type: '*' | `${string}:*`;
   readonly originalType: keyof E & string;
-  readonly detail: E[keyof E];
 }
 
 /**
@@ -75,11 +83,41 @@ export interface MinimalAbortSignal {
 /**
  * Options for addEventListener.
  */
-export type AddEventListenerOptionsLike = {
+export interface EventListenerOptionsLike {
+  capture?: boolean;
+}
+
+/**
+ * Options for addEventListener.
+ */
+export type AddEventListenerOptionsLike = EventListenerOptionsLike & {
   once?: boolean;
+  passive?: boolean;
   signal?: MinimalAbortSignal;
 };
 
+/**
+ * EventListener-like callback (function or object with handleEvent).
+ */
+export type EventListenerObject<T> = {
+  handleEvent: (event: T) => void | Promise<void>;
+};
+
+export type EventListenerLike<T> =
+  | ((event: T) => void | Promise<void>)
+  | EventListenerObject<T>;
+
+/**
+ * Minimal event input accepted by dispatchEvent.
+ */
+export type DispatchEventInput<Detail, Type extends string = string> = {
+  type: Type;
+  detail: Detail;
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+};
+
 /**
  * TC39 Observable observer interface.
  */
@@ -130,22 +168,26 @@ export interface AsyncIteratorOptions {
 export type EventsIteratorOptions = AsyncIteratorOptions;
 
 /**
- * Options for interop helpers.
+ * Options for interoperability helpers.
  */
 export interface InteropOptions {
   signal?: MinimalAbortSignal;
 }
 
 /**
- * Minimal DOM Event interface for interop.
+ * Minimal DOM Event interface for interoperability.
  */
 export interface DOMEventLike {
   type: string;
   detail?: unknown;
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+  defaultPrevented?: boolean;
 }
 
 /**
- * Minimal DOM EventTarget interface for interop.
+ * Minimal DOM EventTarget interface for interoperability.
  */
 export interface DOMEventTargetLike {
   addEventListener(type: string, listener: (event: DOMEventLike) => void): void;
@@ -157,9 +199,14 @@ export interface DOMEventTargetLike {
  * Internal listener record type.
  */
 export type Listener<E> = {
-  fn: (event: EmissionEvent<E>) => void | Promise<void>;
-  once?: boolean;
-  signal?: MinimalAbortSignal;
+  type: string;
+  original: EventListenerLike<EmissionEvent<E>>;
+  callback: (event: EmissionEvent<E>) => void | Promise<void>;
+  capture: boolean;
+  passive: boolean;
+  once: boolean;
+  signal?: MinimalAbortSignal | null;
+  removed: boolean;
   abortHandler?: () => void;
 };
 
@@ -180,12 +227,8 @@ export type WildcardListener<E extends Record<string, unknown>> = {
 export interface OnOptions extends AddEventListenerOptionsLike {
   /** Listen for an "error" event and send it to the observer's error method. */
   receiveError?: boolean;
-  /** Member indicates that the callback will not cancel the event. */
-  passive?: boolean;
   /** Handler function called before the event is dispatched to observers. */
   handler?: (event: EmissionEvent<unknown>) => void;
-  /** Member indicates that the Observable will complete after one event. */
-  once?: boolean;
 }
 
 /**
@@ -196,38 +239,40 @@ export interface OnOptions extends AddEventListenerOptionsLike {
 export interface EventTargetLike<E extends Record<string, any>> {
   addEventListener: <K extends keyof E & string>(
     type: K,
-    listener: (event: EmissionEvent<E[K]>) => void | Promise<void>,
-    options?: AddEventListenerOptionsLike,
+    listener: EventListenerLike<EmissionEvent<E[K], K>> | null,
+    options?: AddEventListenerOptionsLike | boolean,
   ) => () => void;
   removeEventListener: <K extends keyof E & string>(
     type: K,
-    listener: (event: EmissionEvent<E[K]>) => void | Promise<void>,
+    listener: EventListenerLike<EmissionEvent<E[K], K>> | null,
+    options?: EventListenerOptionsLike | boolean,
   ) => void;
-  dispatchEvent: <K extends keyof E & string>(event: EmissionEvent<E[K]>) => boolean;
+  dispatchEvent: <K extends keyof E & string>(
+    event: DispatchEventInput<E[K], K> | DOMEventLike,
+  ) => boolean;
   clear: () => void;
 
   // Ergonomics
   on: <K extends keyof E & string>(
     type: K,
     options?: OnOptions | boolean,
-  ) => ObservableLike<EmissionEvent<E[K]>>;
+  ) => ObservableLike<EmissionEvent<E[K], K>>;
   once: <K extends keyof E & string>(
     type: K,
-    listener: (event: EmissionEvent<E[K]>) => void | Promise<void>,
-    options?: Omit<AddEventListenerOptionsLike, 'once'>,
+    listener: EventListenerLike<EmissionEvent<E[K], K>> | null,
+    options?: Omit<AddEventListenerOptionsLike, 'once'> | boolean,
   ) => () => void;
   removeAllListeners: <K extends keyof E & string>(type?: K) => void;
   /**
    * Pipe events from this emitter to another target.
-   * Note: Only forwards events for types that have listeners when pipe() is called.
-   * Events for types registered after piping won't be forwarded automatically.
+   * Forwards all events. If mapFn returns null, the event is skipped.
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic constraint requires any
   pipe: <T extends Record<string, any>>(
     target: EventTargetLike<T>,
     mapFn?: <K extends keyof E & string>(
-      event: EmissionEvent<E[K]>,
-    ) => EmissionEvent<T[keyof T & string]> | null,
+      event: EmissionEvent<E[K], K>,
+    ) => DispatchEventInput<T[keyof T & string], keyof T & string> | null,
   ) => () => void;
   complete: () => void;
   readonly completed: boolean;
@@ -243,12 +288,12 @@ export interface EventTargetLike<E extends Record<string, any>> {
     listener: (event: WildcardEvent<E>) => void | Promise<void>,
   ) => void;
 
-  // Observable interop
+  // Observable interoperability
   subscribe: <K extends keyof E & string>(
     type: K,
     observerOrNext?:
-      | Observer<EmissionEvent<E[K]>>
-      | ((value: EmissionEvent<E[K]>) => void),
+      | Observer<EmissionEvent<E[K], K>>
+      | ((value: EmissionEvent<E[K], K>) => void),
     error?: (err: unknown) => void,
     complete?: () => void,
   ) => Subscription;
@@ -258,5 +303,5 @@ export interface EventTargetLike<E extends Record<string, any>> {
   events: <K extends keyof E & string>(
     type: K,
     options?: AsyncIteratorOptions,
-  ) => AsyncIterableIterator<EmissionEvent<E[K]>>;
+  ) => AsyncIterableIterator<EmissionEvent<E[K], K>>;
 }

package/dist/interop.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"interop.d.ts","sourceRoot":"","sources":["../src/interop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,kBAAkB,EAElB,eAAe,EACf,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAC1B,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM,IAAI,CAeZ;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACnC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,eAAe,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAgE9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAC1B,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM,IAAI,CAWZ"}