refactor: use Set instead of Array for O(1) listener operations in singleton-handler (#187)

Author: TrevorBurnham

src/internal/singleton-handler/__tests__/create-singleton-handler.test.tsx

@@ -79,3 +79,55 @@ test('should remove listeners when component unmounts', () => {
   expect(onChangeFirst).toHaveBeenCalledTimes(2);
   expect(onChangeSecond).toHaveBeenCalledTimes(1);
 });
+
+test('should notify listeners in registration order', () => {
+  const { Demo, state } = setup();
+  const callOrder: string[] = [];
+  const onChangeFirst = jest.fn(() => callOrder.push('first'));
+  const onChangeSecond = jest.fn(() => callOrder.push('second'));
+  const onChangeThird = jest.fn(() => callOrder.push('third'));
+  render(
+    <>
+      <Demo onChange={onChangeFirst} />
+      <Demo onChange={onChangeSecond} />
+      <Demo onChange={onChangeThird} />
+    </>
+  );
+  state.handler(42);
+  expect(callOrder).toEqual(['first', 'second', 'third']);
+});
+
+test('should handle rapid mount/unmount cycles correctly', () => {
+  const { Demo, state } = setup();
+  const onChange1 = jest.fn();
+  const onChange2 = jest.fn();
+  const onChange3 = jest.fn();
+
+  const { rerender, unmount } = render(<Demo onChange={onChange1} />);
+  expect(state.subscriptions).toEqual(1);
+
+  // Rapid additions
+  rerender(
+    <>
+      <Demo onChange={onChange1} />
+      <Demo onChange={onChange2} />
+    </>
+  );
+  rerender(
+    <>
+      <Demo onChange={onChange1} />
+      <Demo onChange={onChange2} />
+      <Demo onChange={onChange3} />
+    </>
+  );
+  expect(state.subscriptions).toEqual(1);
+
+  state.handler(100);
+  expect(onChange1).toHaveBeenCalledWith(100);
+  expect(onChange2).toHaveBeenCalledWith(100);
+  expect(onChange3).toHaveBeenCalledWith(100);
+
+  // Complete cleanup
+  unmount();
+  expect(state.subscriptions).toEqual(0);
+});

src/internal/singleton-handler/index.ts

@@ -9,7 +9,9 @@ type CleanupCallback = () => void;
 export type UseSingleton<T> = (listener: ValueCallback<T>) => void;
 
 export function createSingletonHandler<T>(factory: (handler: ValueCallback<T>) => CleanupCallback): UseSingleton<T> {
-  const listeners: Array<ValueCallback<T>> = [];
+  // Using Set for O(1) add/delete operations instead of Array's O(n) indexOf + splice.
+  // Sets maintain insertion order (ES2015+), preserving iteration consistency.
+  const listeners = new Set<ValueCallback<T>>();
   const callback: ValueCallback<T> = value => {
     unstable_batchedUpdates(() => {
       for (const listener of listeners) {
@@ -21,14 +23,14 @@ export function createSingletonHandler<T>(factory: (handler: ValueCallback<T>) =
 
   return function useSingleton(listener: ValueCallback<T>) {
     useEffect(() => {
-      if (listeners.length === 0) {
+      if (listeners.size === 0) {
         cleanup = factory(callback);
       }
-      listeners.push(listener);
+      listeners.add(listener);
 
       return () => {
-        listeners.splice(listeners.indexOf(listener), 1);
-        if (listeners.length === 0) {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
           cleanup!();
           cleanup = undefined;
         }