Add scoped event emitter and refactor ThumbnailPlugin

bobsingor · bobsingor · commit 3166fbd8bce4 · 2025-11-07T22:23:49.000+02:00
Introduces a generic scoped event emitter utility for key-based event scoping. Refactors ThumbnailPlugin to use scoped emitters for window and scroll events, improving per-document event handling and cleanup. Updates event API usage to leverage scoped hooks and emission.
diff --git a/packages/core/src/lib/index.ts b/packages/core/src/lib/index.ts
@@ -10,6 +10,7 @@ export * from './store/initial-state';
 export * from './store/selectors';
 export * from './utils/event-control';
 export * from './utils/eventing';
+export * from './utils/scoped-eventing';
 export * from './utils/math';
 export * from './utils/typed-object';
 export * from './plugin/builder';
diff --git a/packages/core/src/lib/utils/scoped-eventing.ts b/packages/core/src/lib/utils/scoped-eventing.ts
@@ -0,0 +1,274 @@
+import {
+  EventControl,
+  EventControlOptions,
+  KeyedEventControl,
+  isKeyedOptions,
+} from './event-control';
+import { EventHook, Listener, Unsubscribe } from './eventing';
+import { arePropsEqual } from './math';
+
+/* ------------------------------------------------------------------ */
+/* Scoped Emitter - Generic Key-Based Event Scoping                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * A scoped behavior emitter that maintains separate cached values
+ * and listener sets per scope key.
+ *
+ * @typeParam TData - The scoped data type (without key context)
+ * @typeParam TGlobalEvent - The global event type (includes key context)
+ * @typeParam TKey - The key type (string, number, or both)
+ */
+export interface ScopedEmitter<
+  TData = any,
+  TGlobalEvent = { key: string; data: TData },
+  TKey extends string | number = string | number,
+> {
+  /**
+   * Emit an event for a specific scope key.
+   */
+  emit(key: TKey, data: TData): void;
+
+  /**
+   * Get a scoped event hook that only receives events for this key.
+   */
+  forScope(key: TKey): EventHook<TData>;
+
+  /**
+   * Global event hook that receives events from all scopes.
+   */
+  readonly onGlobal: EventHook<TGlobalEvent>;
+
+  /**
+   * Clear all scopes' caches and listeners
+   */
+  clear(): void;
+
+  /**
+   * Clear a specific scope's cache and listeners
+   */
+  clearScope(key: TKey): void;
+
+  /**
+   * Get the current cached value for a specific scope
+   */
+  getValue(key: TKey): TData | undefined;
+
+  /**
+   * Get all active scope keys
+   */
+  getScopes(): TKey[];
+}
+
+/**
+ * Creates a scoped behavior emitter with global event support.
+ *
+ * @param toGlobalEvent - Transform function to convert (key, data) into a global event
+ * @param equality - Optional equality function for per-scope caching (default: arePropsEqual)
+ *
+ * @example
+ * ```typescript
+ * // Document-scoped (string keys)
+ * const window$ = createScopedEmitter<WindowState, WindowChangeEvent, string>(
+ *   (documentId, window) => ({ documentId, window })
+ * );
+ *
+ * // User-scoped (number keys)
+ * const presence$ = createScopedEmitter<UserPresence, PresenceEvent, number>(
+ *   (userId, presence) => ({ userId, presence })
+ * );
+ *
+ * // Flexible (string or number)
+ * const data$ = createScopedEmitter<Data, DataEvent>(
+ *   (id, data) => ({ id, data })
+ * );
+ * ```
+ */
+export function createScopedEmitter<
+  TData = any,
+  TGlobalEvent = { key: string; data: TData },
+  TKey extends string | number = string | number,
+>(
+  toGlobalEvent: (key: TKey, data: TData) => TGlobalEvent,
+  equality: (a: TData, b: TData) => boolean = arePropsEqual,
+): ScopedEmitter<TData, TGlobalEvent, TKey> {
+  // Per-scope state (normalized keys as strings)
+  const scopeCaches = new Map<string, TData>();
+  const scopeListeners = new Map<string, Set<Listener<TData>>>();
+  const scopeProxyMaps = new Map<
+    string,
+    Map<Listener<TData>, { wrapped: Listener<TData>; destroy: () => void }>
+  >();
+
+  // Global listeners (no caching - only for new emissions)
+  const globalListeners = new Set<Listener<TGlobalEvent>>();
+  const globalProxyMap = new Map<
+    Listener<TGlobalEvent>,
+    { wrapped: Listener<TGlobalEvent>; destroy: () => void }
+  >();
+
+  const normalizeKey = (key: TKey): string => String(key);
+
+  const getOrCreateListeners = (key: string): Set<Listener<TData>> => {
+    let listeners = scopeListeners.get(key);
+    if (!listeners) {
+      listeners = new Set();
+      scopeListeners.set(key, listeners);
+    }
+    return listeners;
+  };
+
+  const getOrCreateProxyMap = (
+    key: string,
+  ): Map<Listener<TData>, { wrapped: Listener<TData>; destroy: () => void }> => {
+    let proxyMap = scopeProxyMaps.get(key);
+    if (!proxyMap) {
+      proxyMap = new Map();
+      scopeProxyMaps.set(key, proxyMap);
+    }
+    return proxyMap;
+  };
+
+  const onGlobal: EventHook<TGlobalEvent> = (
+    listener: Listener<TGlobalEvent>,
+    options?: EventControlOptions<TGlobalEvent>,
+  ): Unsubscribe => {
+    let realListener = listener;
+    let destroy = () => {};
+
+    if (options) {
+      if (isKeyedOptions(options)) {
+        const ctl = new KeyedEventControl(listener, options);
+        realListener = ctl.handle as Listener<TGlobalEvent>;
+        destroy = () => ctl.destroy();
+      } else {
+        const ctl = new EventControl(listener, options);
+        realListener = ctl.handle as Listener<TGlobalEvent>;
+        destroy = () => ctl.destroy();
+      }
+      globalProxyMap.set(listener, { wrapped: realListener, destroy });
+    }
+
+    globalListeners.add(realListener);
+
+    return () => {
+      globalListeners.delete(realListener);
+      destroy();
+      globalProxyMap.delete(listener);
+    };
+  };
+
+  return {
+    emit(key: TKey, data: TData) {
+      const normalizedKey = normalizeKey(key);
+      const cached = scopeCaches.get(normalizedKey);
+
+      // Only process if changed or first emission
+      if (cached === undefined || !equality(cached, data)) {
+        scopeCaches.set(normalizedKey, data);
+
+        // Notify per-scope listeners
+        const listeners = scopeListeners.get(normalizedKey);
+        if (listeners) {
+          listeners.forEach((l) => l(data));
+        }
+
+        // Notify global listeners with key context
+        const globalEvent = toGlobalEvent(key, data);
+        globalListeners.forEach((l) => l(globalEvent));
+      }
+    },
+
+    forScope(key: TKey): EventHook<TData> {
+      const normalizedKey = normalizeKey(key);
+
+      return (listener: Listener<TData>, options?: EventControlOptions<TData>): Unsubscribe => {
+        const listeners = getOrCreateListeners(normalizedKey);
+        const proxyMap = getOrCreateProxyMap(normalizedKey);
+
+        let realListener = listener;
+        let destroy = () => {};
+
+        if (options) {
+          if (isKeyedOptions(options)) {
+            const ctl = new KeyedEventControl(listener, options);
+            realListener = ctl.handle as Listener<TData>;
+            destroy = () => ctl.destroy();
+          } else {
+            const ctl = new EventControl(listener, options);
+            realListener = ctl.handle as Listener<TData>;
+            destroy = () => ctl.destroy();
+          }
+          proxyMap.set(listener, { wrapped: realListener, destroy });
+        }
+
+        // Replay cached value for this scope
+        const cached = scopeCaches.get(normalizedKey);
+        if (cached !== undefined) {
+          realListener(cached);
+        }
+
+        listeners.add(realListener);
+
+        return () => {
+          listeners.delete(realListener);
+          destroy();
+          proxyMap.delete(listener);
+
+          // Cleanup empty collections
+          if (listeners.size === 0) {
+            scopeListeners.delete(normalizedKey);
+          }
+          if (proxyMap.size === 0) {
+            scopeProxyMaps.delete(normalizedKey);
+          }
+        };
+      };
+    },
+
+    onGlobal,
+
+    getValue(key: TKey): TData | undefined {
+      return scopeCaches.get(normalizeKey(key));
+    },
+
+    getScopes(): TKey[] {
+      // Cast back to TKey array (safe because we only store what was emitted)
+      return Array.from(scopeCaches.keys()) as TKey[];
+    },
+
+    clearScope(key: TKey): void {
+      const normalizedKey = normalizeKey(key);
+
+      scopeCaches.delete(normalizedKey);
+
+      const listeners = scopeListeners.get(normalizedKey);
+      if (listeners) {
+        listeners.clear();
+        scopeListeners.delete(normalizedKey);
+      }
+
+      const proxyMap = scopeProxyMaps.get(normalizedKey);
+      if (proxyMap) {
+        proxyMap.forEach((p) => p.destroy());
+        proxyMap.clear();
+        scopeProxyMaps.delete(normalizedKey);
+      }
+    },
+
+    clear(): void {
+      scopeCaches.clear();
+      scopeListeners.forEach((set) => set.clear());
+      scopeListeners.clear();
+      scopeProxyMaps.forEach((map) => {
+        map.forEach((p) => p.destroy());
+        map.clear();
+      });
+      scopeProxyMaps.clear();
+
+      globalListeners.clear();
+      globalProxyMap.forEach((p) => p.destroy());
+      globalProxyMap.clear();
+    },
+  };
+}
diff --git a/packages/plugin-thumbnail/src/lib/thumbnail-plugin.ts b/packages/plugin-thumbnail/src/lib/thumbnail-plugin.ts
@@ -2,6 +2,7 @@ import {
   BasePlugin,
   createBehaviorEmitter,
   createEmitter,
+  createScopedEmitter,
   Listener,
   PluginRegistry,
   REFRESH_PAGES,
@@ -48,9 +49,13 @@ export class ThumbnailPlugin extends BasePlugin<
   // Per-document auto-scroll tracking
   private readonly canAutoScroll = new Map<string, boolean>();
 
-  private readonly window$ = createBehaviorEmitter<WindowChangeEvent>();
+  private readonly window$ = createScopedEmitter<WindowState, WindowChangeEvent, string>(
+    (documentId, window) => ({ documentId, window }),
+  );
+  private readonly scrollTo$ = createScopedEmitter<ScrollToOptions, ScrollToEvent, string>(
+    (documentId, options) => ({ documentId, options }),
+  );
   private readonly refreshPages$ = createEmitter<RefreshPagesEvent>();
-  private readonly scrollTo$ = createBehaviorEmitter<ScrollToEvent>();
 
   constructor(
     id: string,
@@ -138,7 +143,8 @@ export class ThumbnailPlugin extends BasePlugin<
     }
 
     this.canAutoScroll.delete(documentId);
-
+    this.window$.clearScope(documentId);
+    this.scrollTo$.clearScope(documentId);
     this.logger.debug(
       'ThumbnailPlugin',
       'DocumentClosed',
@@ -167,8 +173,8 @@ export class ThumbnailPlugin extends BasePlugin<
       forDocument: (documentId: string) => this.createThumbnailScope(documentId),
 
       // Events
-      onWindow: this.window$.on,
-      onScrollTo: this.scrollTo$.on,
+      onWindow: this.window$.onGlobal,
+      onScrollTo: this.scrollTo$.onGlobal,
       onRefreshPages: this.refreshPages$.on,
     };
   }
@@ -183,14 +189,8 @@ export class ThumbnailPlugin extends BasePlugin<
       renderThumb: (idx, dpr) => this.renderThumb(idx, dpr, documentId),
       updateWindow: (scrollY, viewportH) => this.updateWindow(scrollY, viewportH, documentId),
       getWindow: () => this.getWindow(documentId),
-      onWindow: (listener: Listener<WindowState | null>) =>
-        this.window$.on((event) => {
-          if (event.documentId === documentId) listener(event.window);
-        }),
-      onScrollTo: (listener: Listener<ScrollToOptions>) =>
-        this.scrollTo$.on((event) => {
-          if (event.documentId === documentId) listener(event.options);
-        }),
+      onWindow: this.window$.forScope(documentId),
+      onScrollTo: this.scrollTo$.forScope(documentId),
       onRefreshPages: (listener: Listener<number[]>) =>
         this.refreshPages$.on((event) => {
           if (event.documentId === documentId) listener(event.pages);
@@ -266,7 +266,7 @@ export class ThumbnailPlugin extends BasePlugin<
     if (docState.viewportH > 0) {
       this.updateWindow(docState.scrollY, docState.viewportH, documentId);
     } else {
-      this.window$.emit({ documentId, window });
+      this.window$.emit(documentId, window);
     }
   }
 
@@ -311,7 +311,7 @@ export class ThumbnailPlugin extends BasePlugin<
     };
 
     this.dispatch(setWindowState(id, newWindow));
-    this.window$.emit({ documentId: id, window: newWindow });
+    this.window$.emit(id, newWindow);
   }
 
   private getWindow(documentId?: string): WindowState | null {
@@ -333,7 +333,7 @@ export class ThumbnailPlugin extends BasePlugin<
     if (docState.viewportH <= 0) {
       // Center the thumbnail in the viewport
       const top = Math.max(PADDING_Y, item.top - item.wrapperHeight);
-      this.scrollTo$.emit({ documentId: id, options: { top, behavior } });
+      this.scrollTo$.emit(id, { top, behavior });
       return;
     }
 
@@ -345,14 +345,14 @@ export class ThumbnailPlugin extends BasePlugin<
     const needsDown = bottom > docState.scrollY + docState.viewportH - margin;
 
     if (needsUp) {
-      this.scrollTo$.emit({
-        documentId: id,
-        options: { top: Math.max(0, top - PADDING_Y), behavior },
+      this.scrollTo$.emit(id, {
+        top: Math.max(0, top - PADDING_Y),
+        behavior,
       });
     } else if (needsDown) {
-      this.scrollTo$.emit({
-        documentId: id,
-        options: { top: Math.max(0, bottom - docState.viewportH + PADDING_Y), behavior },
+      this.scrollTo$.emit(id, {
+        top: Math.max(0, bottom - docState.viewportH + PADDING_Y),
+        behavior,
       });
     }
   }
