@drip-apex/sdk 0.1.0

package/src/wait.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("waitForElement", () => {
+  const originalDocument = (globalThis as any).document;
+  const originalMutationObserver = (globalThis as any).MutationObserver;
+  const originalNode = (globalThis as any).Node;
+  let observerCallback: MutationCallback | null = null;
+  let disconnect: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.useFakeTimers();
+    disconnect = vi.fn();
+    observerCallback = null;
+    (globalThis as any).Node = {
+      ELEMENT_NODE: 1,
+      DOCUMENT_FRAGMENT_NODE: 11,
+    };
+    (globalThis as any).document = {
+      documentElement: {},
+      querySelectorAll: vi.fn(() => []),
+    };
+    (globalThis as any).MutationObserver = class MutationObserver {
+      constructor(callback: MutationCallback) {
+        observerCallback = callback;
+      }
+      observe = vi.fn();
+      disconnect = disconnect;
+    };
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    (globalThis as any).document = originalDocument;
+    (globalThis as any).MutationObserver = originalMutationObserver;
+    (globalThis as any).Node = originalNode;
+  });
+
+  it("ignores invalid selectors instead of leaving a broken observer behind", async () => {
+    (globalThis as any).document.querySelectorAll = vi.fn(() => {
+      throw new Error("invalid selector");
+    });
+    const { waitForElement } = await import("./wait");
+    const callback = vi.fn();
+    const onMiss = vi.fn();
+
+    expect(() => waitForElement("[", callback, { onMiss })).not.toThrow();
+    expect(callback).not.toHaveBeenCalled();
+    expect(onMiss).toHaveBeenCalledTimes(1);
+    expect(observerCallback).toBeNull();
+  });
+
+  it("expires unresolved selector waits", async () => {
+    const { waitForElement } = await import("./wait");
+    const callback = vi.fn();
+    const onMiss = vi.fn();
+    waitForElement(".late-node", callback, { ttlMs: 1000, onMiss });
+
+    vi.advanceTimersByTime(1001);
+    const node = {
+      nodeType: 1,
+      matches: vi.fn(() => true),
+      querySelectorAll: vi.fn(() => []),
+    };
+    observerCallback?.([{ addedNodes: [node] } as unknown as MutationRecord], {} as MutationObserver);
+
+    await Promise.resolve();
+    expect(callback).not.toHaveBeenCalled();
+    expect(onMiss).toHaveBeenCalledTimes(1);
+    expect(disconnect).toHaveBeenCalled();
+  });
+
+  it("rechecks existing SPA nodes when attributes make a delayed selector match", async () => {
+    const { waitForElement } = await import("./wait");
+    const callback = vi.fn();
+    const onMiss = vi.fn();
+    const node = {
+      nodeType: 1,
+      matches: vi.fn((selector: string) => selector === "[data-route='pdp']"),
+      querySelectorAll: vi.fn(() => []),
+    } as unknown as Element;
+
+    waitForElement("[data-route='pdp']", callback, { ttlMs: 1000, onMiss });
+    observerCallback?.(
+      [{ type: "attributes", target: node } as unknown as MutationRecord],
+      {} as MutationObserver,
+    );
+
+    await Promise.resolve();
+    expect(callback).toHaveBeenCalledWith(node);
+    expect(onMiss).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1001);
+    expect(onMiss).not.toHaveBeenCalled();
+  });
+});

package/src/wait.ts

@@ -0,0 +1,238 @@
+import { Mutation } from "./types";
+import { applyTrackedMutation, isInsertAction, isInsertDuplicate, getMutationKey } from "./mutate";
+
+type WaitEntry = {
+  selector: string;
+  callback: (el: Element) => void;
+  handled: WeakSet<Element>;
+  matched: boolean;
+  expiresAt: number;
+  onMiss?: () => void;
+};
+
+const entries: WaitEntry[] = [];
+let observer: MutationObserver | null = null;
+let pending = false;
+const pendingRoots = new Set<ParentNode>();
+const DEFAULT_WAIT_TTL_MS = 30_000;
+let expiryTimer: ReturnType<typeof setTimeout> | null = null;
+
+function isElement(node: Node): node is Element {
+  return node.nodeType === Node.ELEMENT_NODE;
+}
+
+function hasQuerySelectorAll(node: ParentNode): node is ParentNode & { querySelectorAll: (selectors: string) => NodeListOf<Element> } {
+  return typeof (node as ParentNode & { querySelectorAll?: unknown }).querySelectorAll === "function";
+}
+
+function applyToEntry(entry: WaitEntry, element: Element): void {
+  if (entry.expiresAt <= Date.now()) return;
+  if (entry.handled.has(element)) return;
+  entry.handled.add(element);
+  entry.matched = true;
+  entry.callback(element);
+}
+
+function clearExpiryTimer(): void {
+  if (expiryTimer !== null) {
+    clearTimeout(expiryTimer);
+    expiryTimer = null;
+  }
+}
+
+function scheduleExpiryPrune(): void {
+  clearExpiryTimer();
+  if (entries.length === 0) return;
+  const nextExpiry = Math.min(...entries.map((entry) => entry.expiresAt));
+  const delay = Math.max(1, nextExpiry - Date.now() + 1);
+  expiryTimer = setTimeout(() => {
+    expiryTimer = null;
+    pruneExpiredEntries();
+  }, delay);
+}
+
+function pruneExpiredEntries(): void {
+  const ts = Date.now();
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    if (entries[i].expiresAt <= ts) {
+      const [expired] = entries.splice(i, 1);
+      if (!expired.matched) {
+        try {
+          expired.onMiss?.();
+        } catch {}
+      }
+    }
+  }
+  if (entries.length === 0 && observer) {
+    observer.disconnect();
+    observer = null;
+    pending = false;
+    pendingRoots.clear();
+    clearExpiryTimer();
+  } else {
+    scheduleExpiryPrune();
+  }
+}
+
+function buildSelectorMap(): Map<string, WaitEntry[]> {
+  pruneExpiredEntries();
+  const selectorMap = new Map<string, WaitEntry[]>();
+  for (const entry of entries) {
+    const group = selectorMap.get(entry.selector);
+    if (group) {
+      group.push(entry);
+    } else {
+      selectorMap.set(entry.selector, [entry]);
+    }
+  }
+  return selectorMap;
+}
+
+function runSelectorOnRoot(selector: string, root: ParentNode): Element[] {
+  const matched: Element[] = [];
+  try {
+    if (isElement(root) && root.matches(selector)) {
+      matched.push(root);
+    }
+    if (hasQuerySelectorAll(root)) {
+      root.querySelectorAll(selector).forEach((el) => matched.push(el));
+    }
+  } catch {
+    return [];
+  }
+  return matched;
+}
+
+const debouncedCheck = () => {
+  if (pending) return;
+  pending = true;
+  queueMicrotask(() => {
+    pending = false;
+    flushChecks();
+  });
+};
+
+function checkAllEntries(): void {
+  const selectorMap = buildSelectorMap();
+  for (const [selector, selectorEntries] of selectorMap) {
+    try {
+      const elements = document.querySelectorAll(selector);
+      elements.forEach((el) => {
+        selectorEntries.forEach((entry) => applyToEntry(entry, el));
+      });
+    } catch {}
+  }
+  pruneExpiredEntries();
+}
+
+function checkPendingRoots(): void {
+  if (pendingRoots.size === 0) return;
+  const roots = Array.from(pendingRoots);
+  pendingRoots.clear();
+
+  const selectorMap = buildSelectorMap();
+  for (const [selector, selectorEntries] of selectorMap) {
+    for (const root of roots) {
+      const matches = runSelectorOnRoot(selector, root);
+      for (const element of matches) {
+        selectorEntries.forEach((entry) => applyToEntry(entry, element));
+      }
+    }
+  }
+  pruneExpiredEntries();
+}
+
+function flushChecks(): void {
+  if (entries.length === 0) return;
+  if (pendingRoots.size > 0) {
+    checkPendingRoots();
+    return;
+  }
+  checkAllEntries();
+}
+
+function ensureObserver(): void {
+  if (observer) return;
+  observer = new MutationObserver((records) => {
+    for (const record of records) {
+      if (record.type === "childList") {
+        record.addedNodes.forEach((node) => {
+          if (isElement(node)) {
+            pendingRoots.add(node);
+          } else if (node.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+            pendingRoots.add(node as DocumentFragment);
+          }
+        });
+      } else if (record.type === "attributes" && isElement(record.target)) {
+        pendingRoots.add(record.target);
+      } else if (record.type === "characterData" && record.target.parentElement) {
+        pendingRoots.add(record.target.parentElement);
+      }
+    }
+    if (pendingRoots.size > 0) debouncedCheck();
+  });
+  observer.observe(document.documentElement, {
+    attributes: true,
+    characterData: true,
+    childList: true,
+    subtree: true,
+  });
+}
+
+export function waitForElement(
+  selector: string,
+  callback: (el: Element) => void,
+  options: { ttlMs?: number; onMiss?: () => void } = {},
+): void {
+  const handled = new WeakSet<Element>();
+  let matched = false;
+  try {
+    const existing = document.querySelectorAll(selector);
+    existing.forEach((el) => {
+      handled.add(el);
+      matched = true;
+      callback(el);
+    });
+  } catch {
+    options.onMiss?.();
+    return;
+  }
+  const ttlMs = Math.max(1_000, Math.min(options.ttlMs ?? DEFAULT_WAIT_TTL_MS, 120_000));
+  entries.push({ selector, callback, handled, matched, expiresAt: Date.now() + ttlMs, onMiss: options.onMiss });
+  scheduleExpiryPrune();
+  ensureObserver();
+}
+
+export function applyMutationWithWait(
+  mutation: Mutation,
+  index: number,
+  onApplied?: ((mutation: Mutation, element: Element, index: number) => void) | null,
+  onMiss?: ((mutation: Mutation, index: number) => void) | null,
+): void {
+  const key = getMutationKey(mutation, index);
+  waitForElement(mutation.selector, (element) => {
+    if (isInsertAction(mutation.action)) {
+      if (isInsertDuplicate(element, key)) {
+        onApplied?.(mutation, element, index);
+        return;
+      }
+      applyTrackedMutation(mutation, element, key);
+    } else {
+      applyTrackedMutation(mutation, element, key);
+    }
+    onApplied?.(mutation, element, index);
+  }, {
+    onMiss: () => onMiss?.(mutation, index),
+  });
+}
+
+export function resetWaitEntries(): void {
+  entries.length = 0;
+  pending = false;
+  pendingRoots.clear();
+  if (observer) {
+    observer.disconnect();
+    observer = null;
+  }
+  clearExpiryTimer();
+}