rusteerio 0.0.0-stage → 0.1.0

package/src/router.ts

@@ -0,0 +1,327 @@
+import { requireNative, type NativeDocument, type NativeNodeRecord } from './native.js';
+import { hasParserHooks, parseNativeDocument } from './hooks.js';
+import type { CheerioOptions } from './types.js';
+
+interface ManagedNativeDocument extends NativeDocument {
+  retain?(ids: number[]): void;
+  release?(ids: number[]): void;
+  collectGarbage?(): { live: number; slots: number; retained: number; reclaimed: number };
+}
+interface PinRecord { global: number; document: WeakRef<ManagedNativeDocument>; local: number }
+interface Handle { global: number; document: ManagedNativeDocument; local: number; data?: object; pin: PinRecord }
+interface HandleEntry { reference: WeakRef<Handle>; pin: PinRecord }
+interface Registry {
+  next: number;
+  space: object;
+  handles: Map<number, WeakRef<Handle>>;
+  byDocument: WeakMap<NativeDocument, Map<number, HandleEntry>>;
+  finalizer: FinalizationRegistry<PinRecord>;
+  snapshots: WeakMap<NativeDocument, Map<number, NativeNodeRecord | null>>;
+}
+const registryKey = Symbol.for('rusteerio.native-handles.v2');
+const globals = globalThis as typeof globalThis & { [key: symbol]: Registry | undefined };
+const registry: Registry = globals[registryKey] ??= (() => {
+  const handles = new Map<number, WeakRef<Handle>>();
+  const byDocument = new WeakMap<NativeDocument, Map<number, HandleEntry>>();
+  const snapshots = new WeakMap<NativeDocument, Map<number, NativeNodeRecord | null>>();
+  const pending: PinRecord[] = [];
+  let scheduled = false;
+  const flush = () => {
+    scheduled = false;
+    const batches = new Map<ManagedNativeDocument, number[]>();
+    for (const pin of pending.splice(0)) {
+      const document = pin.document.deref();
+      if (!document) continue;
+      const entries = byDocument.get(document);
+      if (entries?.get(pin.local)?.pin === pin) entries.delete(pin.local);
+      const ids = batches.get(document) ?? [];
+      ids.push(pin.local); batches.set(document, ids);
+    }
+    for (const [document, ids] of batches) {
+      snapshots.delete(document);
+      document.release?.(ids);
+      document.collectGarbage?.();
+    }
+  };
+  return { next: 1, space: {}, handles, byDocument, snapshots, finalizer: new FinalizationRegistry<PinRecord>((pin) => {
+    if (!handles.get(pin.global)?.deref()) handles.delete(pin.global);
+    pending.push(pin);
+    if (!scheduled) { scheduled = true; queueMicrotask(flush); }
+  }) };
+})();
+
+function rawOperation<T = any>(document: NativeDocument, command: string, args: any): T {
+  const result = document.op(command, JSON.stringify(args));
+  return result === '' || result === undefined ? undefined as T : JSON.parse(result);
+}
+function localMap(document: NativeDocument): Map<number, HandleEntry> {
+  let map = registry.byDocument.get(document);
+  if (!map) registry.byDocument.set(document, map = new Map());
+  return map;
+}
+function handleFor(document: ManagedNativeDocument, local: number): Handle {
+  const map = localMap(document);
+  let handle = map.get(local)?.reference.deref();
+  if (!handle || handle.document !== document || handle.local !== local) {
+    const pin: PinRecord = { global: registry.next++, document: new WeakRef(document), local };
+    handle = { global: pin.global, document, local, pin };
+    document.retain?.([local]);
+    const reference = new WeakRef(handle);
+    map.set(local, { reference, pin }); registry.handles.set(handle.global, reference);
+    registry.finalizer.register(handle, pin);
+  }
+  return handle;
+}
+
+/** Keep numeric native IDs alive for precisely the lifetime of their JS owner. */
+export function retainNodes(document: NativeDocument, ids: number[]): object {
+  return (document as NativeDocument & { retainNodes?(ids: number[]): object }).retainNodes?.(ids) ?? {};
+}
+
+/**
+ * Maps stable JS handles to their current native arena. Native adoption moves
+ * the DOM; this bridge only translates IDs and routes commands to its owner.
+ * Global tables contain weak references. Live APIs and node handles retain the
+ * ownership records they use, including records moved to another arena.
+ */
+export class RoutedDocument implements NativeDocument {
+  readonly nodeSpace = registry.space;
+  readonly options: CheerioOptions;
+  private readonly anchor: Handle;
+  get raw(): ManagedNativeDocument { return this.anchor.document; }
+
+  constructor(document: NativeDocument, options: CheerioOptions = {}, anchor?: Handle) {
+    this.options = options;
+    this.anchor = anchor ?? handleFor(document, document.rootId());
+  }
+  private keep(handle: Handle): number { return handle.global; }
+  private lookup(id: number): Handle {
+    const handle = registry.handles.get(id)?.deref();
+    if (!handle) throw new RangeError(`Unknown native node handle ${id}`);
+    return handle;
+  }
+  private global(document: NativeDocument, local: number): number { return this.keep(handleFor(document, local)); }
+  private globals(document: NativeDocument, ids: number[]): number[] { return ids.map((id) => this.global(document, id)); }
+  retainNode(id: number): void { this.lookup(id); }
+  retainNodes(ids: number[]): object { return ids.filter((id) => id !== undefined).map((id) => this.lookup(id)); }
+  nodeDocument(id: number): NativeDocument { return new RoutedDocument(this.raw, this.options, this.lookup(id)); }
+  collectGarbage(): { live: number; slots: number; retained: number; reclaimed: number } | undefined { registry.snapshots.delete(this.raw); return this.raw.collectGarbage?.(); }
+  retainNodeData(id: number, data: object): void { this.lookup(id).data = data; }
+  nodeData(id: number): object | undefined { return this.lookup(id).data; }
+  nodeDataOperation(id: number): (command: string, args: any) => any {
+    const handle = this.lookup(id);
+    const options = this.options;
+    return (command, args) => rawOperation(handle.document, command, { ...args, ids: [handle.local], options });
+  }
+  localNodeId(id: number): number { return this.global(this.raw, id); }
+  rootId(): number { return this.global(this.raw, this.raw.rootId()); }
+
+  private record(document: NativeDocument, record: NativeNodeRecord | null): NativeNodeRecord | null {
+    if (!record) return null;
+    const view = { ...record, id: this.global(document, record.id) };
+    // Translate links only when read. A text callback must not allocate/pin
+    // handles for every unobserved child and sibling in its ancestor records.
+    Object.defineProperty(view, 'children', { enumerable: true, get: () => this.globals(document, record.children ?? []) });
+    for (const key of ['parent', 'prev', 'next']) Object.defineProperty(view, key, { enumerable: true, get: () => record[key] == null ? null : this.global(document, record[key]) });
+    return view;
+  }
+  private groups(ids: number[]): { document: NativeDocument; ids: number[]; global: number[] }[] {
+    const groups: { document: NativeDocument; ids: number[]; global: number[] }[] = [];
+    for (const id of ids) {
+      const handle = this.lookup(id);
+      const last = groups[groups.length - 1];
+      if (last?.document === handle.document) { last.ids.push(handle.local); last.global.push(id); }
+      else groups.push({ document: handle.document, ids: [handle.local], global: [id] });
+    }
+    return groups;
+  }
+  private call<T = any>(document: NativeDocument, command: string, args: any): T {
+    if (command === 'extractPlan' && JSON.stringify(args.plan).includes('innerHTML')) registry.snapshots.delete(document);
+    if (Object.hasOwn(args, 'value') || ['create', 'createNode', 'setNode', 'import', 'insert', 'clone', 'remove', 'removeAttr', 'removeData', 'addClass', 'removeClass', 'toggleClass'].includes(command)) registry.snapshots.delete(document);
+    return rawOperation(document, command, { ...args, options: args.options ?? this.options });
+  }
+
+  private move(target: NativeDocument, ids: number[], copy = false): number[] {
+    if (!copy) {
+      const groups = new Map<NativeDocument, Handle[]>();
+      for (const id of ids) { const handle = this.lookup(id); const group = groups.get(handle.document) ?? []; group.push(handle); groups.set(handle.document, group); }
+      for (const [source, handles] of groups) {
+        if (source === target) continue;
+        if (!target.adopt) throw new Error('The native addon does not support cross-document adoption. Rebuild the Rust addon.');
+        registry.snapshots.delete(source); registry.snapshots.delete(target);
+        const adopted: { mapping: [number, number][] } = JSON.parse(target.adopt(source, handles.map((handle) => handle.local), true));
+        for (const [oldLocal, newLocal] of adopted.mapping) {
+          const entry = localMap(source).get(oldLocal);
+          if (!entry) continue;
+          const handle = entry.reference.deref();
+          if (handle && (handle.document !== source || handle.local !== oldLocal)) continue;
+          localMap(source).delete(oldLocal);
+          entry.pin.document = new WeakRef(target); entry.pin.local = newLocal;
+          if (handle) { handle.document = target; handle.local = newLocal; }
+          localMap(target).set(newLocal, entry);
+        }
+      }
+      return ids.map((id) => this.lookup(id).local);
+    }
+    const result: number[] = [];
+    for (const group of this.groups(ids)) {
+      if (copy && group.document === target) {
+        result.push(...this.call<number[]>(target, 'clone', { ids: group.ids, deep: true }));
+        continue;
+      }
+      if (!target.adopt) throw new Error('The native addon does not support cross-document adoption. Rebuild the Rust addon.');
+      registry.snapshots.delete(target);
+      const adopted: { roots: number[]; mapping: [number, number][] } = JSON.parse(target.adopt(group.document, group.ids, !copy));
+      result.push(...adopted.roots);
+    }
+    return result;
+  }
+
+  private scratch(command: string, args: any, ids: number[]): any {
+    const documents = [...new Set(ids.map((id) => this.lookup(id).document))];
+    const scratch = new (requireNative().NativeDocument)('', false, JSON.stringify(args.options ?? this.options));
+    const toScratch = new Map<number, number>();
+    const fromScratch = new Map<number, number>();
+    for (const document of documents) {
+      const records: NativeNodeRecord[] = JSON.parse(document.exportTree());
+      const roots = records.filter((record) => record.parent == null).map((record) => record.id);
+      if (!scratch.adopt) throw new Error('The native addon does not support native document copies.');
+      const copied: { mapping: [number, number][] } = JSON.parse(scratch.adopt(document, roots, false));
+      for (const [local, copy] of copied.mapping) {
+        const global = this.global(document, local);
+        toScratch.set(global, copy); fromScratch.set(copy, global);
+      }
+    }
+    const translated = { ...args };
+    for (const key of ['ids', 'contexts']) if (Array.isArray(args[key])) translated[key] = args[key].map((id: number) => toScratch.get(id)).filter((id: number | undefined) => id !== undefined);
+    if (args.pseudoMatches) translated.pseudoMatches = Object.fromEntries(Object.entries(args.pseudoMatches).map(([key, values]) => [key, (values as number[]).map((id) => toScratch.get(id)).filter((id) => id !== undefined)]));
+    const result = this.call(scratch, command, translated);
+    return ['select', 'matches', 'uniqueSort'].includes(command) ? (result as number[]).map((id) => fromScratch.get(id)!).filter((id) => id !== undefined) : result;
+  }
+
+  select(selector: string, contexts?: number[]): number[] {
+    const ids = contexts ?? [this.rootId()];
+    if (!ids.length) return this.call(this.raw, 'select', { selector, contexts: [] });
+    const groups = this.groups(ids);
+    if (new Set(groups.map((group) => group.document)).size > 1) return this.scratch('select', { selector, contexts: ids }, ids);
+    const group = groups[0];
+    const found = group.document === this.raw ? group.document.select(selector, group.ids) : this.call<number[]>(group.document, 'select', { selector, contexts: group.ids });
+    return this.globals(group.document, found);
+  }
+  text(ids: number[]): string { return this.groups(ids).map((group) => group.document.text(group.ids)).join(''); }
+  innerHtml(id: number): string { const handle = this.lookup(id); registry.snapshots.delete(handle.document); return handle.document === this.raw ? handle.document.innerHtml(handle.local) : this.call(handle.document, 'html', { ids: [handle.local] }); }
+  outerHtml(ids: number[]): string { return this.groups(ids).map((group) => group.document === this.raw ? group.document.outerHtml(group.ids) : this.call<string>(group.document, 'render', { ids: group.ids })).join(''); }
+  attr(id: number, name: string): string | undefined { const handle = this.lookup(id); return this.call(handle.document, 'attr', { ids: [handle.local], name }) ?? undefined; }
+  tagName(id: number): string | undefined { const handle = this.lookup(id); return rawOperation<NativeNodeRecord | null>(handle.document, 'node', { id: handle.local })?.name; }
+  exportTree(): string { return JSON.stringify((JSON.parse(this.raw.exportTree()) as NativeNodeRecord[]).map((record) => this.record(this.raw, record))); }
+  create(html: string, contextId?: number): number[] { return JSON.parse(this.op('create', JSON.stringify({ html, contextId }))); }
+
+  op(command: string, json: string): string { return JSON.stringify(this.operate(command, JSON.parse(json)) ?? null); }
+
+  operate(command: string, args: any): any {
+    const options = args.options ?? this.options;
+    let result: any;
+    if (command === 'node') {
+      const handle = this.lookup(args.id);
+      let snapshots = registry.snapshots.get(handle.document);
+      if (!snapshots) registry.snapshots.set(handle.document, snapshots = new Map());
+      if (!snapshots.has(handle.local)) snapshots.set(handle.local, rawOperation(handle.document, 'node', { id: handle.local }));
+      result = this.record(handle.document, snapshots.get(handle.local)!);
+    } else if (command === 'createNode') result = this.global(this.raw, this.call<number>(this.raw, command, args));
+    else if (command === 'create') {
+      const context = args.contextId == null ? undefined : this.lookup(args.contextId);
+      const document = context?.document ?? this.raw;
+      if (hasParserHooks(options)) {
+        const contextRecord = context ? rawOperation<NativeNodeRecord>(context.document, 'node', { id: context.local }) : undefined;
+        const parsed = parseNativeDocument(args.html, { ...options, ...(contextRecord ? { __contextName: contextRecord.name, __contextNamespace: contextRecord.namespace } : {}) }, false);
+        const children = rawOperation<NativeNodeRecord>(parsed, 'node', { id: parsed.rootId() }).children;
+        this.move(document, children);
+        result = children;
+      } else result = this.globals(document, this.call(document, command, { ...args, contextId: context?.local }));
+    } else if (command === 'import') result = this.globals(this.raw, this.call(this.raw, command, args));
+    else if (command === 'setNode') {
+      let handle = this.lookup(args.id);
+      let value = args.value;
+      if (args.field === 'children') value = this.move(handle.document, value ?? []);
+      else if (['parent', 'parentNode', 'prev', 'previousSibling', 'next', 'nextSibling'].includes(args.field) && value != null) {
+        const pointer = this.lookup(value);
+        if (pointer.document !== handle.document) { this.move(pointer.document, [args.id]); handle = this.lookup(args.id); }
+        value = this.lookup(args.value).local;
+      }
+      result = this.call(handle.document, command, { ...args, id: handle.local, value });
+    } else if (command === 'insert') {
+      const targets: number[] = args.targetIds ?? [];
+      const nodes: number[] = args.nodeIds ?? [];
+      result = [];
+      for (let index = 0; index < targets.length; index++) {
+        const target = this.lookup(targets[index]);
+        const local = this.move(target.document, nodes, index + 1 < targets.length);
+        const inserted = this.call<number[]>(target.document, command, { ...args, targetIds: [target.local], nodeIds: local });
+        result.push(...this.globals(target.document, inserted));
+      }
+    } else if (command === 'html' && Object.hasOwn(args, 'value') && hasParserHooks(options)) {
+      result = null;
+      for (const id of args.ids ?? []) {
+        const target = this.lookup(id);
+        const record = rawOperation<NativeNodeRecord>(target.document, 'node', { id: target.local });
+        if (!['root', 'tag', 'script', 'style', 'cdata'].includes(record.type)) continue;
+        const parsed = parseNativeDocument(String(args.value), { ...options, __contextName: record.name, __contextNamespace: record.namespace }, false);
+        const children = rawOperation<NativeNodeRecord>(parsed, 'node', { id: parsed.rootId() }).children;
+        const local = this.move(target.document, children);
+        result = this.call(target.document, 'setNode', { id: target.local, field: 'children', value: local, options });
+      }
+    } else if (command === 'contains') {
+      const parent = this.lookup(args.container ?? args.parent);
+      const child = this.lookup(args.contained ?? args.child);
+      result = parent.document === child.document && this.call(parent.document, command, { container: parent.local, contained: child.local });
+    } else if (command === 'prop' && Object.hasOwn(args, 'value') && ['children', 'childNodes', 'parent', 'parentNode', 'prev', 'previousSibling', 'next', 'nextSibling'].includes(args.name)) {
+      result = null;
+      for (const id of args.ids ?? []) {
+        let handle = this.lookup(id);
+        let value = args.value;
+        if (args.name === 'children' || args.name === 'childNodes') value = this.move(handle.document, value ?? []);
+        else if (value != null) {
+          const pointer = this.lookup(value);
+          if (pointer.document !== handle.document) { this.move(pointer.document, [id]); handle = this.lookup(id); }
+          value = this.lookup(args.value).local;
+        }
+        result = this.call(handle.document, command, { ...args, ids: [handle.local], value });
+      }
+    } else {
+      const ids: number[] = command === 'select' ? args.contexts ?? [this.rootId()] : args.ids ?? [];
+      const groups = this.groups(ids);
+      const mixed = new Set(groups.map((group) => group.document)).size > 1;
+      if (mixed && ['select', 'matches', 'uniqueSort', 'serializeArray', 'serialize', 'extractPlan'].includes(command)) result = this.scratch(command, { ...args, options }, ids);
+      else if (command === 'extractPlan') {
+        const group = groups[0];
+        result = this.call(group?.document ?? this.raw, command, { ...args, options, ids: group?.ids ?? [] });
+      }
+      else if (['select', 'matches', 'uniqueSort', 'traverse', 'clone'].includes(command)) {
+        result = [];
+        if (!groups.length && (command === 'select' || command === 'matches')) result = this.call(this.raw, command, { ...args, options, ids: [], ...(command === 'select' ? { contexts: [] } : {}) });
+        for (const group of groups) {
+          const values = this.call<number[]>(group.document, command, { ...args, options, ids: group.ids, ...(command === 'select' ? { contexts: group.ids } : {}), ...(args.pseudoMatches ? { pseudoMatches: Object.fromEntries(Object.entries(args.pseudoMatches).map(([key, values]) => [key, (values as number[]).map((id) => this.lookup(id)).filter((handle) => handle.document === group.document).map((handle) => handle.local)])) } : {}) });
+          result.push(...this.globals(group.document, values));
+        }
+      } else if (['render', 'outerHtml', 'text'].includes(command) && !Object.hasOwn(args, 'value')) result = groups.map((group) => this.call<string>(group.document, command, { ...args, options, ids: group.ids })).join('');
+      else if (command === 'hasClass') result = groups.some((group) => this.call<boolean>(group.document, command, { ...args, options, ids: group.ids }));
+      else if (['serializeArray', 'serialize'].includes(command)) result = groups.length ? this.call(groups[0].document, command, { ...args, options, ids: groups[0].ids }) : command === 'serializeArray' ? [] : '';
+      else {
+        if (command === 'html') for (const group of groups) registry.snapshots.delete(group.document);
+        const writes = Object.hasOwn(args, 'value') || ['remove', 'removeAttr', 'removeData', 'addClass', 'removeClass', 'toggleClass'].includes(command);
+        const active = writes ? groups : groups.slice(0, 1);
+        result = null;
+        for (const group of active) result = this.call(group.document, command, { ...args, options, ids: group.ids });
+      }
+    }
+    return result ?? null;
+  }
+}
+
+export function routeDocument(document: NativeDocument, options: CheerioOptions = {}): NativeDocument {
+  return document.nodeSpace === registry.space ? document : new RoutedDocument(document, options);
+}
+
+export function sameNodeSpace(first: NativeDocument, second: NativeDocument): boolean {
+  return first === second || !!first.nodeSpace && first.nodeSpace === second.nodeSpace;
+}