rusteerio 1.0.1 → 1.1.0

package/src/snapshot.ts

@@ -0,0 +1,255 @@
+import { decodeString } from './codec.js';
+import type { NativeNodeRecord } from './native.js';
+
+/**
+ * The compact record copy returned by `NativeDocument.snapshot()`: the
+ * lengths of the node, child, attribute and string lists, whether any string
+ * holds codec escapes, then the lists.
+ */
+export interface NativeSnapshot {
+  data: Uint32Array;
+  text: string;
+}
+const HEADER = 5;
+
+const STRIDE = 15;
+const ABSENT = 0xffffffff;
+const HAS_START_INDEX = 1;
+const HAS_END_INDEX = 2;
+const HAS_NAMESPACE = 4;
+const EMPTY_ATTRIBUTE_MAPS = 8;
+const OPAQUE = 16;
+const RELEASED = 32;
+const noChildren: number[] = Object.freeze([]) as unknown as number[];
+const noAttributes: Record<string, string> = Object.freeze({}) as Record<string, string>;
+
+/**
+ * A record read from a snapshot. It stores only its position; fields decode
+ * on read, and strings and lists are kept once decoded. Every instance has
+ * the same fields, so reads stay monomorphic. Absent fields read `undefined`.
+ */
+class SnapshotRecord {
+  private decodedData: string | undefined;
+  private decodedAttributes: Record<string, string> | undefined;
+  private decodedChildren: number[] | undefined;
+
+  constructor(private readonly snapshot: NodeSnapshot, readonly id: number, private readonly base: number) {
+    this.decodedData = undefined;
+    this.decodedAttributes = undefined;
+    this.decodedChildren = undefined;
+  }
+
+  get type(): string { return this.snapshot.name(this.snapshot.nodes[this.base]); }
+  get name(): string | undefined { const name = this.snapshot.nodes[this.base + 6]; return name ? this.snapshot.name(name - 1) : undefined; }
+  get data(): string | undefined {
+    if (this.decodedData !== undefined) return this.decodedData;
+    const data = this.snapshot.nodes[this.base + 7];
+    return data ? this.decodedData = this.snapshot.string(data - 1) : undefined;
+  }
+  get parent(): number | null { const parent = this.snapshot.nodes[this.base + 1]; return parent ? parent - 1 : null; }
+  get prev(): number | null { const prev = this.snapshot.nodes[this.base + 2]; return prev ? prev - 1 : null; }
+  get next(): number | null { const next = this.snapshot.nodes[this.base + 3]; return next ? next - 1 : null; }
+  get startIndex(): number | null | undefined { return this.index(HAS_START_INDEX, 11); }
+  get endIndex(): number | null | undefined { return this.index(HAS_END_INDEX, 12); }
+  get namespace(): string | undefined { const nodes = this.snapshot.nodes; return nodes[this.base + 10] & HAS_NAMESPACE ? this.snapshot.name(nodes[this.base + 13]) : undefined; }
+  get attribsNamespace(): Record<string, string> | undefined { return this.snapshot.nodes[this.base + 10] & EMPTY_ATTRIBUTE_MAPS ? {} : undefined; }
+  get attribsPrefix(): Record<string, string> | undefined { return this.snapshot.nodes[this.base + 10] & EMPTY_ATTRIBUTE_MAPS ? {} : undefined; }
+  get attribs(): Record<string, string> { return this.decodedAttributes ??= this.snapshot.attributesOf(this.id); }
+  get children(): number[] { return this.decodedChildren ??= this.snapshot.childrenOf(this.id); }
+
+  private index(flag: number, offset: number): number | null | undefined {
+    const nodes = this.snapshot.nodes;
+    if (!(nodes[this.base + 10] & flag)) return undefined;
+    const value = nodes[this.base + offset];
+    return value === ABSENT ? null : value;
+  }
+}
+
+/** Snapshot records extended with fields stored as JSON, which are rare. */
+const recordFields = ['type', 'name', 'data', 'parent', 'prev', 'next', 'startIndex', 'endIndex', 'namespace', 'attribsNamespace', 'attribsPrefix', 'attribs', 'children'] as const;
+
+/** A plain copy of a record, for callers that spread or serialize it. */
+export function plainRecord(record: NativeNodeRecord): NativeNodeRecord {
+  if (!(record instanceof SnapshotRecord)) return record;
+  const copy: Record<string, unknown> = { id: record.id };
+  for (const field of recordFields) { const value = (record as any)[field]; if (value !== undefined) copy[field] = value; }
+  for (const key of Object.keys(record)) if (!key.startsWith('decoded') && key !== 'snapshot' && key !== 'base' && key !== 'id') copy[key] = (record as any)[key];
+  return copy as NativeNodeRecord;
+}
+
+/** Decodes node records from a snapshot on demand, exactly as `node()` returns them. */
+export class NodeSnapshot {
+  readonly size: number;
+  readonly nodes: Uint32Array;
+  private readonly children: Uint32Array;
+  private readonly attributes: Uint32Array;
+  private readonly strings: Uint32Array;
+  private readonly text: string;
+  private readonly isEncoded: boolean;
+  private readonly names: (string | undefined)[] = [];
+  /** Node object constructors by interned type, resolved once per snapshot. */
+  viewConstructors: unknown = undefined;
+
+  constructor(raw: NativeSnapshot) {
+    const { data } = raw;
+    const childrenStart = HEADER + data[0];
+    const attributesStart = childrenStart + data[1];
+    const stringsStart = attributesStart + data[2];
+    this.text = raw.text;
+    this.isEncoded = data[4] === 1;
+    this.nodes = data.subarray(HEADER, childrenStart);
+    this.children = data.subarray(childrenStart, attributesStart);
+    this.attributes = data.subarray(attributesStart, stringsStart);
+    this.strings = data.subarray(stringsStart, stringsStart + data[3]);
+    this.size = this.nodes.length / STRIDE;
+  }
+
+  /** The record, `null` for a released node, or `undefined` when it must be read individually. */
+  record(local: number): NativeNodeRecord | null | undefined {
+    if (local >= this.size) return undefined;
+    const base = local * STRIDE;
+    const flags = this.nodes[base + 10];
+    if (flags & RELEASED) return null;
+    if (flags & OPAQUE) return undefined;
+    const record = new SnapshotRecord(this, local, base);
+    const extras = this.nodes[base + 14];
+    if (extras) {
+      // Fields stored as JSON, such as foreign attribute namespaces, shadow the decoded getters.
+      const fields = JSON.parse(this.string(extras - 1));
+      for (const key of Object.keys(fields)) Object.defineProperty(record, key, { value: fields[key], writable: true, enumerable: true, configurable: true });
+    }
+    return record as unknown as NativeNodeRecord;
+  }
+
+  /** Whether a node's fields all live in the arrays, so callers may read them without a record. */
+  isPlain(local: number): boolean {
+    if (local >= this.size) return false;
+    const base = local * STRIDE;
+    return (this.nodes[base + 10] & (OPAQUE | RELEASED)) === 0 && this.nodes[base + 14] === 0;
+  }
+
+  typeOf(local: number): string {
+    return this.name(this.nodes[local * STRIDE]);
+  }
+
+  nameOf(local: number): string | undefined {
+    const name = this.nodes[local * STRIDE + 6];
+    return name ? this.name(name - 1) : undefined;
+  }
+
+  dataOf(local: number): string | undefined {
+    const data = this.nodes[local * STRIDE + 7];
+    return data ? this.string(data - 1) : undefined;
+  }
+
+  /** The parent, previous or next sibling (`offset` 1, 2 or 3), or `null`. */
+  linkOf(local: number, offset: number): number | null {
+    const link = this.nodes[local * STRIDE + offset];
+    return link ? link - 1 : null;
+  }
+
+  namespaceOf(local: number): string | undefined {
+    const base = local * STRIDE;
+    return this.nodes[base + 10] & HAS_NAMESPACE ? this.name(this.nodes[base + 13]) : undefined;
+  }
+
+  /** A node's attributes as parse5 attribute objects; plain nodes have no namespaced ones. */
+  attributeObjects(local: number): { name: string; value: string }[] {
+    const base = local * STRIDE;
+    const count = this.nodes[base + 9];
+    const first = this.nodes[base + 8];
+    const attributes = this.attributes;
+    const result: { name: string; value: string }[] = new Array(count);
+    for (let index = 0; index < count; index++) {
+      const pair = (first + index) * 2;
+      result[index] = { name: this.name(attributes[pair]), value: this.string(attributes[pair + 1]) };
+    }
+    return result;
+  }
+
+  /** Copies a node's attributes onto `target`, in order. */
+  copyAttributes(local: number, target: Record<string, string>): void {
+    const base = local * STRIDE;
+    const count = this.nodes[base + 9];
+    const first = this.nodes[base + 8];
+    const attributes = this.attributes;
+    for (let index = 0; index < count; index++) {
+      const pair = (first + index) * 2;
+      const name = this.name(attributes[pair]);
+      const value = this.string(attributes[pair + 1]);
+      if (name === '__proto__') Object.defineProperty(target, name, { value, writable: true, enumerable: true, configurable: true });
+      else target[name] = value;
+    }
+  }
+
+  /** The flat child id list; a node's children start at `childStart(local)`. */
+  get childIds(): Uint32Array { return this.children; }
+
+  childStart(local: number): number {
+    return this.nodes[local * STRIDE + 4];
+  }
+
+  /** The interned reference of a node's type, comparable across nodes of this snapshot. */
+  typeReference(local: number): number {
+    return this.nodes[local * STRIDE];
+  }
+
+  /** Child ids without materializing the record. */
+  childCount(local: number): number {
+    return this.nodes[local * STRIDE + 5];
+  }
+
+  childAt(local: number, index: number): number {
+    return this.children[this.nodes[local * STRIDE + 4] + index];
+  }
+
+  childrenOf(local: number): number[] {
+    const base = local * STRIDE;
+    const count = this.nodes[base + 5];
+    if (count === 0) return noChildren;
+    const first = this.nodes[base + 4];
+    return Array.from(this.children.subarray(first, first + count));
+  }
+
+  attributesOf(local: number): Record<string, string> {
+    const base = local * STRIDE;
+    const count = this.nodes[base + 9];
+    if (count === 0) return noAttributes;
+    const first = this.nodes[base + 8];
+    const attributes = this.attributes;
+    const result: Record<string, string> = {};
+    for (let index = 0; index < count; index++) {
+      const pair = (first + index) * 2;
+      const name = this.name(attributes[pair]);
+      const value = this.string(attributes[pair + 1]);
+      if (name === '__proto__') Object.defineProperty(result, name, { value, writable: true, enumerable: true, configurable: true });
+      else result[name] = value;
+    }
+    return result;
+  }
+
+  /** One attribute's value, without decoding the rest. */
+  attributeValue(local: number, name: string): string | undefined {
+    const base = local * STRIDE;
+    const count = this.nodes[base + 9];
+    const first = this.nodes[base + 8];
+    const attributes = this.attributes;
+    // A repeated name keeps its last value, as decoded attribute maps do.
+    for (let index = count - 1; index >= 0; index--) {
+      const pair = (first + index) * 2;
+      if (this.name(attributes[pair]) === name) return this.string(attributes[pair + 1]);
+    }
+    return undefined;
+  }
+
+  string(reference: number): string {
+    const strings = this.strings;
+    const value = this.text.slice(strings[reference * 2], strings[reference * 2 + 1]);
+    return this.isEncoded ? decodeString(value) : value;
+  }
+
+  /** Names repeat across nodes, so each decodes once. */
+  name(reference: number): string {
+    return this.names[reference] ??= this.string(reference);
+  }
+}

package/src/transport.ts

@@ -2,18 +2,29 @@ import { decodeJson, decodeString, encodeJson, encodeOptions, encodeString } fro
 import type { NativeBinding, NativeDocument } from './native.js';
 
 interface TransportRegistry {
-  documents: WeakMap<object, NativeDocument>;
-  originals: WeakMap<object, NativeDocument>;
   userErrors: WeakSet<object>;
 }
-const registryKey = Symbol.for('rusteerio.native-transport.v1');
+const registryKey = Symbol.for('rusteerio.native-transport.v2');
 const globals = globalThis as typeof globalThis & { [key: symbol]: TransportRegistry | undefined };
-const registry = globals[registryKey] ??= { documents: new WeakMap(), originals: new WeakMap(), userErrors: new WeakSet() };
+const registry = globals[registryKey] ??= { userErrors: new WeakSet() };
+const transportedKey = Symbol.for('rusteerio.native-transport.prototype');
+
+const jsonMethods = new Set(['op', 'node', 'exportTree', 'parserDiagnostics', 'adopt']);
+/** String arguments each document method takes, by position, and how to encode them. */
+const argumentEncoders: Record<string, (args: any[]) => void> = {
+  op: (args) => { args[1] = encodeJson(args[1]); },
+  create: (args) => { args[0] = encodeString(args[0]); if (typeof args[2] === 'string') args[2] = encodeOptions(args[2]); },
+  select: (args) => { args[0] = encodeString(args[0]); },
+  matches: (args) => { args[0] = encodeString(args[0]); },
+  attr: (args) => { args[1] = encodeString(args[1]); },
+  setAttribute: (args) => { args[1] = encodeString(args[1]); if (typeof args[2] === 'string') args[2] = encodeString(args[2]); },
+  render: (args) => { if (typeof args[1] === 'string') args[1] = encodeJson(args[1]); },
+};
 
 /** Keep the codec at the private addon boundary, including callback RPC. */
 export function wrapNativeBinding(binding: NativeBinding): NativeBinding {
   const raw = binding as NativeBinding & Record<string, any>;
-  const { documents, originals, userErrors } = registry;
+  const { userErrors } = registry;
   const restoreError = (error: unknown): never => {
     if (error instanceof Error && !userErrors.has(error)) {
       const message = decodeString(error.message);
@@ -38,39 +49,33 @@ export function wrapNativeBinding(binding: NativeBinding): NativeBinding {
       throw error;
     }
   };
-  const jsonMethods = new Set(['op', 'node', 'exportTree', 'parserDiagnostics', 'adopt']);
-  const wrapDocument = (document: NativeDocument): NativeDocument => {
-    const cached = documents.get(document);
-    if (cached) return cached;
-    const methods = new Map<PropertyKey, unknown>();
-    const wrapped = new Proxy(document, {
-      get(target, property) {
-        const value = Reflect.get(target, property, target);
-        if (typeof value !== 'function') return value;
-        if (property === 'constructor') return value;
-        if (methods.has(property)) return methods.get(property);
-        const method = (...input: any[]) => invoke(() => {
-          const args = input.slice();
-          if (property === 'op') args[1] = encodeJson(args[1]);
-          else if (property === 'create') { args[0] = encodeString(args[0]); if (typeof args[2] === 'string') args[2] = encodeOptions(args[2]); }
-          else if (property === 'select' || property === 'matches') args[0] = encodeString(args[0]);
-          else if (property === 'attr') args[1] = encodeString(args[1]);
-          else if (property === 'adopt') args[0] = originals.get(args[0]) ?? args[0];
-          const result = Reflect.apply(value, target, args);
-          if (property === 'op' && args[0] === 'serialize' && typeof result === 'string' && result.startsWith('{')) {
-            const error = JSON.parse(result).__nativeError;
-            if (error?.name === 'URIError') throw new URIError(error.message);
-          }
-          return typeof result === 'string' ? jsonMethods.has(String(property)) ? decodeJson(result) : decodeString(result) : result;
-        });
-        methods.set(property, method);
-        return method;
-      },
-    });
-    documents.set(document, wrapped);
-    originals.set(wrapped, document);
-    return wrapped;
+  // Wrapping the class's methods once, rather than each document in a proxy,
+  // keeps native calls free of per-document and per-call allocations.
+  const transportMethod = (name: string, method: (...args: any[]) => unknown) => {
+    const encodeArguments = argumentEncoders[name];
+    const decode = jsonMethods.has(name) ? decodeJson : decodeString;
+    const isOperation = name === 'op';
+    return function transported(this: NativeDocument, ...args: any[]): unknown {
+      try {
+        if (encodeArguments) encodeArguments(args);
+        const result = method.apply(this, args);
+        if (typeof result !== 'string') return result;
+        if (isOperation && args[0] === 'serialize' && result.startsWith('{')) {
+          const error = JSON.parse(result).__nativeError;
+          if (error?.name === 'URIError') throw new URIError(error.message);
+        }
+        return decode(result);
+      } catch (error) { return restoreError(error); }
+    };
   };
+  const prototype = raw.NativeDocument.prototype as Record<PropertyKey, unknown>;
+  if (!Object.hasOwn(prototype, transportedKey)) {
+    for (const name of Object.getOwnPropertyNames(prototype)) {
+      const method = prototype[name];
+      if (name !== 'constructor' && typeof method === 'function') prototype[name] = transportMethod(name, method as (...args: any[]) => unknown);
+    }
+    Object.defineProperty(prototype, transportedKey, { value: true });
+  }
   const wrapStream = (stream: any) => {
     let carry = '';
     return {
@@ -83,7 +88,7 @@ export function wrapNativeBinding(binding: NativeBinding): NativeBinding {
       },
       async finish() {
         if (carry) { const final = carry; carry = ''; await invoke(() => stream.write(encodeString(final))); }
-        return wrapDocument(await invoke(() => stream.finish()));
+        return invoke(() => stream.finish());
       },
       abort() { carry = ''; return invoke(() => stream.abort()); },
     };
@@ -92,12 +97,16 @@ export function wrapNativeBinding(binding: NativeBinding): NativeBinding {
     construct(target, args) { return wrap(invoke(() => Reflect.construct(target, argumentsFor(args)))); },
   });
   const wrapped: NativeBinding & Record<string, any> = { ...raw };
-  wrapped.NativeDocument = wrapConstructor(raw.NativeDocument, ([html, isDocument, options]) => [encodeString(html), isDocument, encodeOptions(options)], wrapDocument);
+  const Document = raw.NativeDocument;
+  wrapped.NativeDocument = function NativeDocument(html: string, isDocument?: boolean, options?: string) {
+    try { return new Document(encodeString(html), isDocument, encodeOptions(options)); }
+    catch (error) { return restoreError(error); }
+  } as unknown as NativeBinding['NativeDocument'];
   if (raw.NativeStream) wrapped.NativeStream = wrapConstructor(raw.NativeStream, ([options, isDocument, bridge]) => [encodeOptions(options), isDocument, bridge && wrapBridge(bridge)], wrapStream);
   if (raw.NativeHookStream) wrapped.NativeHookStream = wrapConstructor(raw.NativeHookStream, ([isDocument, options, bridge]) => [isDocument, encodeOptions(options), wrapBridge(bridge)], wrapStream);
-  if (raw.parseWithTreeAdapter) wrapped.parseWithTreeAdapter = (source: string, isDocument: boolean, options: string, bridge: (request: string) => string) => wrapDocument(invoke(() => raw.parseWithTreeAdapter(encodeString(source), isDocument, encodeOptions(options), wrapBridge(bridge))));
-  if (raw.parseAsync) wrapped.parseAsync = async (source, isDocument, options) => wrapDocument(await invoke(() => raw.parseAsync!(encodeString(source), isDocument, encodeOptions(options))));
-  if (raw.parseManyAsync) wrapped.parseManyAsync = async (sources, isDocument, threads, options) => (await invoke(() => raw.parseManyAsync!(sources.map(encodeString), isDocument, threads, encodeOptions(options)))).map(wrapDocument);
+  if (raw.parseWithTreeAdapter) wrapped.parseWithTreeAdapter = (source: string, isDocument: boolean, options: string, bridge: (request: string) => string) => invoke(() => raw.parseWithTreeAdapter(encodeString(source), isDocument, encodeOptions(options), wrapBridge(bridge)));
+  if (raw.parseAsync) wrapped.parseAsync = (source, isDocument, options) => invoke(() => raw.parseAsync!(encodeString(source), isDocument, encodeOptions(options)));
+  if (raw.parseManyAsync) wrapped.parseManyAsync = (sources, isDocument, threads, options) => invoke(() => raw.parseManyAsync!(sources.map(encodeString), isDocument, threads, encodeOptions(options)));
   if (raw.extractPlanManyAsync) wrapped.extractPlanManyAsync = async (sources, plan, threads, options) => decodeJson(await invoke(() => raw.extractPlanManyAsync!(sources.map(encodeString), encodeJson(plan), threads, encodeOptions(options))));
   if (raw.extractManyAsync) wrapped.extractManyAsync = async (sources, queries, threads, isDocument, options) => decodeJson(await invoke(() => raw.extractManyAsync!(sources.map(encodeString), queries.map((query) => ({ ...query, key: encodeString(query.key), selector: encodeString(query.selector), ...(query.attr === undefined ? {} : { attr: encodeString(query.attr) }) })), threads, isDocument, encodeOptions(options))));
   return wrapped;