rusteerio 1.0.1 → 1.1.0

package/src/selection.ts

@@ -1,10 +1,11 @@
 import type { AnyNode, Document, Element, ParentNode, CheerioAPI, CheerioOptions, AcceptedFilters, BasicAcceptedElems, AcceptedElems, ExtractMap, ExtractedMap } from './types.js';
 import { requireNative, type NativeDocument } from './native.js';
-import { getNode, importNodes, nodeBinding, nodeId, nodeRecord, operation, isTag } from './nodes.js';
+import { getNode, importNodes, nodeBinding, nodeId, nodeRecord, operation, isTag, traverseRecords, viewId } from './nodes.js';
 import { installAttributes, type AttributeMethods } from './attributes.js';
 import { extract } from './extract.js';
-import { sameNodeSpace, retainNodes } from './router.js';
+import { API, DOCUMENT, exposeDocumentTo, IDS, IS_PLAIN, LEASE, leaseNodes, routeDocument, sameNodeSpace, updateLease, VALUES, type Lease } from './router.js';
 import { parse } from './parse.js';
+import { matchSimpleSelector, selectSimpleWithin } from './match.js';
 const numeric = /^(?:0|[1-9]\d*)$/;
 const isMarkup = (value: string) => /<[a-zA-Z!/?]/.test(value);
 function* customPseudoArguments(selector: string, name: string): Generator<string | undefined> {
@@ -75,137 +76,199 @@ function* customPseudoArguments(selector: string, name: string): Generator<strin
         index = end;
     }
 }
-/** An array-like selection of stable handles into the Rust document arena. */
+const isIndex = (property: string | symbol): boolean => {
+    if (typeof property !== 'string') return false;
+    const first = property.charCodeAt(0);
+    return first >= 48 && first <= 57 && numeric.test(property);
+};
+/** Results up to this size are plain objects holding their nodes, like Cheerio's own selections. */
+const plainSelectionLimit = 16;
+const lengthOf = (target: Cheerio<any>): number => target[VALUES]?.length ?? target[IDS].length;
+function nodeAt(target: Cheerio<any>, index: number): any {
+    if (target[VALUES]) return target[VALUES][index];
+    const id = target[IDS][index];
+    return id === undefined ? undefined : getNode(target[DOCUMENT], id);
+}
+function releaseIds(target: Cheerio<any>): void {
+    if (target[LEASE]) updateLease(target[DOCUMENT], target[LEASE], target[VALUES] ? [] : target[IDS]);
+}
+function writeIndex(target: Cheerio<any>, index: number, value: any): void {
+    if (target[VALUES]) target[VALUES][index] = value;
+    else {
+        const id = importNodes(target[DOCUMENT], [value])[0];
+        if (id === undefined) {
+            target[VALUES] = target[IDS].map((existing) => getNode(target[DOCUMENT], existing));
+            target[VALUES][index] = value;
+        }
+        else target[IDS][index] = id;
+    }
+    releaseIds(target);
+}
+/** Large selections resolve nodes only when an index is read. */
+const selectionHandler: ProxyHandler<Cheerio<any>> = {
+    get: (target, property) => isIndex(property) ? nodeAt(target, Number(property)) : property === 'length' ? lengthOf(target) : Reflect.get(target, property),
+    set: (target, property, value) => {
+        if (isIndex(property)) { writeIndex(target, Number(property), value); return true; }
+        if (property === 'length') {
+            if (target[VALUES]) target[VALUES].length = value;
+            else target[IDS].length = value;
+            releaseIds(target);
+            return true;
+        }
+        return Reflect.set(target, property, value);
+    },
+    has: (target, property) => isIndex(property) ? Number(property) < lengthOf(target) : property === 'length' || Reflect.has(target, property),
+    ownKeys: (target) => [...Array.from({ length: lengthOf(target) }, (_, i) => String(i)), 'length', ...Reflect.ownKeys(target)],
+    getOwnPropertyDescriptor: (target, property) => {
+        if (isIndex(property) && Number(property) < lengthOf(target))
+            return { value: nodeAt(target, Number(property)), writable: true, configurable: true, enumerable: true };
+        if (property === 'length') return { value: lengthOf(target), writable: true, configurable: true, enumerable: true };
+        return Reflect.getOwnPropertyDescriptor(target, property);
+    },
+    deleteProperty: (target, property) => {
+        if (isIndex(property)) {
+            if (target[VALUES])
+                delete target[VALUES][Number(property)];
+            else
+                delete target[IDS][Number(property)];
+            releaseIds(target);
+            return true;
+        }
+        return Reflect.deleteProperty(target, property);
+    },
+};
+/** An array-like selection of native nodes. */
 export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     [index: number]: T;
-    /** @internal */ declare _document: NativeDocument;
-    /** @internal */ declare _api: CheerioAPI;
-    /** @internal */ declare _ids: number[];
-    /** @internal */ declare _values: T[] | undefined;
-    /** @internal */ declare _lease: object;
+    /** @internal */ declare [DOCUMENT]: NativeDocument;
+    /** @internal */ declare [API]: CheerioAPI;
+    /** @internal */ declare [IDS]: number[];
+    /** @internal */ declare [VALUES]: T[] | undefined;
+    /** @internal */ declare [LEASE]: Lease | undefined;
+    /** @internal Whether the selection holds its items as own index properties, as Cheerio's selections do. */ declare [IS_PLAIN]: boolean;
+    /** @internal */ get _document(): NativeDocument { return this[DOCUMENT]; }
+    /** @internal */ get _api(): CheerioAPI { return this[API]; }
+    /** @internal */ get _ids(): number[] { return this[IDS]; }
+    declare length: number;
     declare options: CheerioOptions;
     declare _root: Cheerio<Document> | null;
     declare prevObject: Cheerio<any> | undefined;
-    declare length: number;
-    cheerio = '[cheerio object]' as const;
+    declare cheerio: '[cheerio object]';
     constructor(api: CheerioAPI, document: NativeDocument, ids: number[] = [], root: Cheerio<Document> | null = null, options: CheerioOptions = {}, values?: T[]) {
-        Object.defineProperties(this, {
-            _document: { value: document, writable: true, configurable: true },
-            _api: { value: api, writable: true, configurable: true },
-            _ids: { value: ids, writable: true, configurable: true },
-            _values: { value: values, writable: true, configurable: true },
-            _lease: { value: retainNodes(document, ids), writable: true, configurable: true },
-            options: { value: options, writable: true, configurable: true, enumerable: true },
-            _root: { value: root, writable: true, configurable: true, enumerable: true },
-            length: { configurable: true, enumerable: true, get: () => this._values?.length ?? this._ids.length, set: (value: number) => { if (this._values)
-                    this._values.length = value;
-                else
-                    this._ids.length = value; this._lease = retainNodes(document, this._values ? [] : this._ids); } },
-        });
-        delete (this as any).cheerio;
-        return new Proxy(this, {
-            get: (target, property, receiver) => typeof property === 'string' && numeric.test(property)
-                ? (target._values ? target._values[Number(property)] : target._ids[Number(property)] === undefined ? undefined : getNode(document, target._ids[Number(property)]))
-                : Reflect.get(target, property, receiver),
-            set: (target, property, value, receiver) => {
-                if (typeof property === 'string' && numeric.test(property)) {
-                    if (target._values)
-                        target._values[Number(property)] = value;
-                    else {
-                        const id = importNodes(document, [value])[0];
-                        if (id === undefined) {
-                            target._values = target._ids.map((existing) => getNode(document, existing)) as T[];
-                            target._values[Number(property)] = value;
-                        }
-                        else
-                            target._ids[Number(property)] = id;
-                    }
-                    target._lease = retainNodes(document, target._values ? [] : target._ids);
-                    return true;
-                }
-                return Reflect.set(target, property, value, receiver);
-            },
-            has: (target, property) => typeof property === 'string' && numeric.test(property) ? Number(property) < target.length : Reflect.has(target, property),
-            ownKeys: (target) => [...Array.from({ length: target.length }, (_, i) => String(i)), ...Reflect.ownKeys(target)],
-            getOwnPropertyDescriptor: (target, property) => typeof property === 'string' && numeric.test(property) && Number(property) < target.length
-                ? { value: target._values ? target._values[Number(property)] : getNode(document, target._ids[Number(property)]), writable: true, configurable: true, enumerable: true }
-                : Reflect.getOwnPropertyDescriptor(target, property),
-            deleteProperty: (target, property) => {
-                if (typeof property === 'string' && numeric.test(property)) {
-                    if (target._values)
-                        delete target._values[Number(property)];
-                    else
-                        delete target._ids[Number(property)];
-                    target._lease = retainNodes(document, target._values ? [] : target._ids);
-                    return true;
-                }
-                return Reflect.deleteProperty(target, property);
-            },
-        });
+        this[DOCUMENT] = document;
+        this[API] = api;
+        this[IDS] = ids;
+        this[VALUES] = values;
+        this[LEASE] = undefined;
+        const count = values ? values.length : ids.length;
+        const isPlain = count <= plainSelectionLimit;
+        this[IS_PLAIN] = isPlain;
+        // Own keys enumerate in Cheerio's order: length, options, _root.
+        if (isPlain) this.length = count;
+        this.options = options;
+        this._root = root;
+        if (isPlain) {
+            // Each node object keeps its own node alive, so a plain selection needs no lease.
+            if (values) for (let index = 0; index < count; index++) this[index] = values[index];
+            else for (let index = 0; index < count; index++) this[index] = getNode(document, ids[index]) as T;
+            return;
+        }
+        if (!values) this[LEASE] = leaseNodes(document, this, ids);
+        return new Proxy(this, selectionHandler);
     }
-    /** @internal */ get ids(): number[] { return this._values ? importNodes(this._document, this._values) : this._ids; }
-    /** @internal */ op<R = any>(command: string, args: unknown = {}): R { const values = args as Record<string, unknown>; return operation<R>(this._document, command, { ...values, options: values.options ?? this.options }); }
+    /** @internal Re-reads a plain selection after direct index writes or after its nodes moved documents. */
+    _syncIndices(): void {
+        const length = this.length;
+        const values = this[VALUES];
+        const ids = this[IDS];
+        let isChanged = (values ?? ids).length !== length;
+        for (let index = 0; !isChanged && index < length; index++) isChanged = values ? this[index] !== values[index] : viewId(this[index]) !== ids[index];
+        if (!isChanged) return;
+        const items: T[] = Array.from({ length }, (_unused, index) => this[index]);
+        const isAllNodes = items.every((value: any) => value && typeof value === 'object' && typeof value.type === 'string');
+        this[VALUES] = isAllNodes ? undefined : items;
+        this[IDS] = isAllNodes ? importNodes(this[DOCUMENT], items) : [];
+    }
+    /** @internal */ get ids(): number[] {
+        if (this[IS_PLAIN]) this._syncIndices();
+        return this[VALUES] ? importNodes(this[DOCUMENT], this[VALUES]) : this[IDS];
+    }
+    /** @internal */ op<R = any>(command: string, args: unknown = {}): R { const values = args as Record<string, unknown>; return operation<R>(this[DOCUMENT], command, { ...values, options: values.options ?? this.options }); }
     /** @internal */ _query(command: 'select' | 'matches', args: {
         selector: string;
         ids?: number[];
         contexts?: number[];
         options?: CheerioOptions;
     }): number[] {
-        const callbacks = Object.entries(this.options.pseudos ?? {}).filter((entry): entry is [
+        const pseudos = this.options.pseudos;
+        const callbacks = pseudos ? Object.entries(pseudos).filter((entry): entry is [
             string,
             (element: Element, argument?: string | null) => boolean
-        ] => typeof entry[1] === 'function');
-        if (!callbacks.length)
-            return command === 'select' && !args.options ? this._document.select(args.selector, args.contexts) : this.op(command, args);
+        ] => typeof entry[1] === 'function') : [];
+        if (!callbacks.length) {
+            if (command === 'matches' && args.ids) {
+                const matched = matchSimpleSelector(this[DOCUMENT], args.ids, args.selector, args.options ?? this.options);
+                if (matched) return matched;
+            }
+            if (command === 'select' && args.contexts) {
+                const found = selectSimpleWithin(this[DOCUMENT], args.contexts, args.selector, args.options ?? this.options);
+                if (found) return found;
+            }
+            return command === 'select' && !args.options ? this[DOCUMENT].select(args.selector, args.contexts) : this.op(command, args);
+        }
         const pseudoMatches: Record<string, number[]> = {};
-        const candidates = [...new Set([...this._document.select('*'), ...(args.ids ?? []), ...(args.contexts ? this._document.select('*', args.contexts) : [])])];
+        const candidates = [...new Set([...this[DOCUMENT].select('*'), ...(args.ids ?? []), ...(args.contexts ? this[DOCUMENT].select('*', args.contexts) : [])])];
         for (const [name, callback] of callbacks) {
             for (const argument of customPseudoArguments(args.selector, name)) {
                 if (argument !== undefined && callback.length < 2)
                     throw new Error(`Pseudo-class :${name} doesn't have any arguments`);
                 if (argument === undefined && callback.length >= 2)
                     throw new Error(`Pseudo-class :${name} requires an argument`);
-                pseudoMatches[`${name}(${argument ?? ''})`] = candidates.filter((id) => callback(getNode(this._document, id) as Element, argument ?? null));
+                pseudoMatches[`${name}(${argument ?? ''})`] = candidates.filter((id) => callback(getNode(this[DOCUMENT], id) as Element, argument ?? null));
             }
         }
         return this.op(command, { ...args, pseudoMatches });
     }
     /** @internal */ _fromIds<R = AnyNode>(ids: number[]): Cheerio<R> {
-        const result = new (this._api.fn.constructor as typeof Cheerio)<R>(this._api, this._document, ids, this._root, this.options);
+        const result = new (this[API].fn.constructor as typeof Cheerio)<R>(this[API], this[DOCUMENT], ids, this._root, this.options);
         result.prevObject = this;
         return result;
     }
     /** @internal */ _fromValues<R>(values: R[]): Cheerio<R> {
         const allNodes = values.every((value: any) => value && typeof value === 'object' && typeof value.type === 'string');
-        const result = new (this._api.fn.constructor as typeof Cheerio)<R>(this._api, this._document, allNodes ? importNodes(this._document, values) : [], this._root, this.options, allNodes ? undefined : values);
+        const result = new (this[API].fn.constructor as typeof Cheerio)<R>(this[API], this[DOCUMENT], allNodes ? importNodes(this[DOCUMENT], values) : [], this._root, this.options, allNodes ? undefined : values);
         result.prevObject = this;
         return result;
     }
     _make<R>(value: ArrayLike<R> | R | string, context?: BasicAcceptedElems<AnyNode>): Cheerio<R>;
     _make<R>(value: any, context?: any): Cheerio<R> {
-        const result = typeof value === 'string' || value?.cheerio ? this._api(value, context) : this._fromValues<R>(value == null ? [] : typeof value === 'object' && 'length' in value && !value.type ? Array.from(value) : [value]);
+        const result = typeof value === 'string' || value?.cheerio ? this[API](value, context) : this._fromValues<R>(value == null ? [] : typeof value === 'object' && 'length' in value && !value.type ? Array.from(value) : [value]);
         result.prevObject = this;
         return result as Cheerio<R>;
     }
     _parse(content: any, options: CheerioOptions, isDocument: boolean, context: ParentNode | null): Document {
         return parse(content, options, isDocument, context);
     }
-    _render(content: any): string { return this._document.outerHtml(importNodes(this._document, content)); }
+    _render(content: any): string { return this[DOCUMENT].outerHtml(importNodes(this[DOCUMENT], content)); }
     /** @internal */ _domIds(content: any, contextId?: number): number[] {
         if (content == null || content === false)
             return [];
         if (typeof content === 'string')
             return this.op('create', { html: content, contextId, options: this.options });
-        if (content?.cheerio)
-            return content._document && sameNodeSpace(this._document, content._document) ? content.ids : importNodes(this._document, content.toArray());
+        if (content?.cheerio) {
+            if (!content[DOCUMENT] || !sameNodeSpace(this[DOCUMENT], content[DOCUMENT]))
+                return importNodes(this[DOCUMENT], content.toArray());
+            exposeDocumentTo(this[DOCUMENT], content[DOCUMENT]);
+            return content.ids;
+        }
         if (typeof content === 'object' && 'length' in content && !content.type)
             return Array.from(content as ArrayLike<any>).flatMap((item) => this._domIds(item, contextId));
-        return importNodes(this._document, [content]);
+        return importNodes(this[DOCUMENT], [content]);
     }
     _makeDomArray<T extends AnyNode>(this: Cheerio<T>, elem?: BasicAcceptedElems<AnyNode> | BasicAcceptedElems<AnyNode>[], clone?: boolean): AnyNode[];
     _makeDomArray(this: Cheerio<any>, content: any, clone: any = false): any {
         const ids = this._domIds(content);
-        return (clone ? this.op<number[]>('clone', { ids, deep: true }) : ids).map((id) => getNode(this._document, id));
+        return (clone ? this.op<number[]>('clone', { ids, deep: true }) : ids).map((id) => getNode(this[DOCUMENT], id));
     }
     find<T extends AnyNode>(this: Cheerio<T>, selectorOrHaystack?: string | Cheerio<Element> | Element): Cheerio<Element>;
     find(this: Cheerio<any>, selector?: any): any {
@@ -213,7 +276,7 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
             return this._fromIds([]);
         if (typeof selector === 'string')
             return this._findBySelector(selector, Infinity);
-        const ids = importNodes(this._document, selector);
+        const ids = importNodes(this[DOCUMENT], selector);
         return this._fromIds(ids.filter((id) => this.ids.some((container) => this.op<boolean>('contains', { container, contained: id }))));
     }
     _findBySelector<T extends AnyNode>(this: Cheerio<T>, selector: string, limit: number): Cheerio<Element>;
@@ -226,19 +289,19 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
             return ids;
         if (typeof selector === 'string')
             return this._query('matches', { ids, selector, options: this.options });
-        return ids.filter((id, index) => this._predicate(selector, getNode(this._document, id), index));
+        return ids.filter((id, index) => this._predicate(selector, getNode(this[DOCUMENT], id), index));
     }
     /** @internal */ _predicate(selector: any, node: any, index: number): boolean {
         if (typeof selector === 'function')
             return !!selector.call(node, index, node);
         if (typeof selector === 'string')
-            return this._query('matches', { ids: importNodes(this._document, [node]), selector, options: this.options }).length > 0;
+            return this._query('matches', { ids: importNodes(this[DOCUMENT], [node]), selector, options: this.options }).length > 0;
         if (selector?.cheerio)
             return selector.toArray().includes(node);
         return node === selector;
     }
     /** @internal */ _traverse(kind: string, selector?: any): Cheerio<Element> {
-        let ids = this.op<number[]>('traverse', { ids: this.ids, kind });
+        let ids = traverseRecords(this[DOCUMENT], this.ids, kind) ?? this.op<number[]>('traverse', { ids: this.ids, kind });
         ids = this._filterIds(ids, selector);
         if (this.length > 1 && ids.length > 1) {
             if (kind === 'parents' || kind === 'siblings')
@@ -271,8 +334,8 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     /** @internal */ _until(kind: string, until?: any, filter?: any): Cheerio<Element> {
         let ids: number[] = [];
         for (const id of this.ids)
-            for (const candidate of this.op<number[]>('traverse', { ids: [id], kind })) {
-                if (until && this._predicate(until, getNode(this._document, candidate), ids.length))
+            for (const candidate of traverseRecords(this[DOCUMENT], [id], kind) ?? this.op<number[]>('traverse', { ids: [id], kind })) {
+                if (until && this._predicate(until, getNode(this[DOCUMENT], candidate), ids.length))
                     break;
                 ids.push(candidate);
             }
@@ -293,9 +356,11 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
             return this._fromIds([]);
         const result: number[] = [];
         for (const id of this.ids) {
-            const record = nodeRecord(this._document, id);
-            const candidates = [...(['tag', 'script', 'style'].includes(record.type) ? [id] : []), ...this.op<number[]>('traverse', { ids: [id], kind: 'parents' })];
-            const match = candidates.find((candidate) => this._predicate(selector, getNode(this._document, candidate), 0));
+            const record = nodeRecord(this[DOCUMENT], id);
+            const candidates = [...(['tag', 'script', 'style'].includes(record.type) ? [id] : []), ...(traverseRecords(this[DOCUMENT], [id], 'parents') ?? this.op<number[]>('traverse', { ids: [id], kind: 'parents' }))];
+            // One native match for all candidates replaces a round trip per ancestor.
+            const matched = typeof selector === 'string' ? new Set(this._filterIds(candidates, selector)) : undefined;
+            const match = matched ? candidates.find((candidate) => matched.has(candidate)) : candidates.find((candidate) => this._predicate(selector, getNode(this[DOCUMENT], candidate), 0));
             if (match !== undefined && !result.includes(match))
                 result.push(match);
         }
@@ -303,17 +368,29 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     }
     each<T>(this: Cheerio<T>, fn: (this: T, i: number, el: T) => void | boolean): Cheerio<T>;
     each(this: Cheerio<any>, callback: any): any {
-        const length = this.length;
-        for (let i = 0; i < length; i++)
-            if (callback.call(this[i], i, this[i]) === false)
+        if (this[IS_PLAIN]) {
+            const length = this.length;
+            for (let i = 0; i < length; i++)
+                if (callback.call(this[i], i, this[i]) === false)
+                    break;
+            return this;
+        }
+        // Reading ids directly avoids a string-keyed proxy trap per index.
+        const values = this[VALUES], ids = this[IDS], document = this[DOCUMENT];
+        const length = values ? values.length : ids.length;
+        for (let i = 0; i < length; i++) {
+            const node = values ? values[i] : getNode(document, ids[i]);
+            if (callback.call(node, i, node) === false)
                 break;
+        }
         return this;
     }
     map<T, M>(this: Cheerio<T>, fn: (this: T, i: number, el: T) => M[] | M | null | undefined): Cheerio<M>;
     map<R>(this: Cheerio<any>, callback: any): any {
         const result: R[] = [];
-        for (let i = 0; i < this.length; i++) {
-            const value = callback.call(this[i], i, this[i]);
+        const items = this._items();
+        for (let i = 0; i < items.length; i++) {
+            const value = callback.call(items[i], i, items[i]);
             if (value != null)
                 result.push(...(Array.isArray(value) ? value : [value]));
         }
@@ -329,7 +406,7 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
         const matcher: any = match;
         if (typeof match !== 'string')
             return nodes.filter((node: any, index: number) => typeof matcher === 'function' ? matcher.call(node, index, node) : matcher?.cheerio ? matcher.toArray().includes(node) : matcher === node);
-        const document = this?._document ?? nodeBinding(root)?.document ?? nodeBinding(nodes[0])?.document ?? new (requireNative().NativeDocument)('', false);
+        const document = this?.[DOCUMENT] ?? nodeBinding(root)?.document ?? nodeBinding(nodes[0])?.document ?? routeDocument(new (requireNative().NativeDocument)('', false));
         const ids = importNodes(document, nodes);
         const selected = new Set(operation<number[]>(document, 'matches', { ids, selector: match, options: { xmlMode } }));
         return nodes.filter((node: any) => { const id = nodeId(node, document); return id !== undefined && selected.has(id); });
@@ -359,40 +436,63 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
             return this;
         if (index < 0)
             index += this.length;
-        return this._fromValues(this[index] === undefined ? [] : [this[index]]);
+        const item = this._itemAt(index);
+        return this._fromValues(item === undefined ? [] : [item]);
     }
     get<T>(this: Cheerio<T>, i: number): T | undefined;
     get<T>(this: Cheerio<T>): T[];
-    get(this: Cheerio<any>, index?: any): any { return index == null ? this.toArray() : this[index < 0 ? this.length + index : index]; }
+    get(this: Cheerio<any>, index?: any): any { return index == null ? this.toArray() : this._itemAt(index < 0 ? this.length + index : index); }
     toArray<T>(this: Cheerio<T>): T[];
-    toArray(this: Cheerio<any>): any { return Array.from({ length: this.length }, (_unused, i) => this[i]); }
+    toArray(this: Cheerio<any>): any { return this._items(); }
+    /** @internal Every item, read without a proxy trap per index. */
+    _items(): T[] {
+        if (this[IS_PLAIN]) {
+            const length = this.length;
+            const items: T[] = new Array(length);
+            for (let i = 0; i < length; i++) items[i] = this[i];
+            return items;
+        }
+        const values = this[VALUES], ids = this[IDS], document = this[DOCUMENT];
+        return values ? values.slice() : ids.map((id) => getNode(document, id) as T);
+    }
+    /** @internal */ _itemAt(index: number): T | undefined {
+        if (this[IS_PLAIN]) return this[index];
+        const values = this[VALUES];
+        if (values) return values[index];
+        const id = this[IDS][index];
+        return id === undefined ? undefined : getNode(this[DOCUMENT], id) as T;
+    }
     slice<T>(this: Cheerio<T>, start?: number, end?: number): Cheerio<T>;
-    slice(this: Cheerio<any>, start?: any, end?: any): any { return this._values ? this._fromValues(this._values.slice(start, end)) : this._fromIds(this._ids.slice(start, end)); }
+    slice(this: Cheerio<any>, start?: any, end?: any): any { const ids = this.ids; return this[VALUES] ? this._fromValues(this[VALUES].slice(start, end)) : this._fromIds(ids.slice(start, end)); }
     end<T>(this: Cheerio<T>): Cheerio<AnyNode>;
     end(this: Cheerio<any>): any { return this.prevObject ?? this._make([]); }
     add<S extends AnyNode, T extends AnyNode>(this: Cheerio<T>, other: string | Cheerio<S> | S | S[], context?: Cheerio<S> | string): Cheerio<S | T>;
-    add<R extends AnyNode>(this: Cheerio<any>, other: any, context?: any): any { return this._fromIds(this.op('uniqueSort', { ids: [...this.ids, ...this._api(other, context).ids] })); }
+    add<R extends AnyNode>(this: Cheerio<any>, other: any, context?: any): any {
+        const added = this[API](other, context);
+        // Ids of another copy of the package belong to its own id space.
+        const addedIds = added[DOCUMENT] && sameNodeSpace(this[DOCUMENT], added[DOCUMENT]) ? added.ids : importNodes(this[DOCUMENT], added.toArray());
+        return this._fromIds(this.op('uniqueSort', { ids: [...this.ids, ...addedIds] }));
+    }
     addBack<T extends AnyNode>(this: Cheerio<T>, selector?: string): Cheerio<AnyNode>;
     addBack(this: Cheerio<any>, selector?: any): any { return this.prevObject ? this.add(selector ? this.prevObject.filter(selector) : this.prevObject) as any : this as any; }
     index<T extends AnyNode>(this: Cheerio<T>, selectorOrNeedle?: string | Cheerio<AnyNode> | AnyNode): number;
-    index(this: Cheerio<any>, selector?: any): any { const haystack = selector == null ? this.parent().children() : typeof selector === 'string' ? this._api(selector) : this; const needle = selector == null || typeof selector === 'string' ? this[0] : selector?.cheerio ? selector[0] : selector; return haystack.toArray().indexOf(needle); }
+    index(this: Cheerio<any>, selector?: any): any { const haystack = selector == null ? this.parent().children() : typeof selector === 'string' ? this[API](selector) : this; const needle = selector == null || typeof selector === 'string' ? this[0] : selector?.cheerio ? selector[0] : selector; return haystack.toArray().indexOf(needle); }
     splice(start: number, deleteCount?: number): any[];
     splice(start: number, deleteCount: number, ...items: any[]): any[];
     splice(...args: any[]): any[] { return Reflect.apply(Array.prototype.splice, this, args); }
     [Symbol.iterator](): Iterator<T>;
-    *[Symbol.iterator](): IterableIterator<T> { for (let i = 0; i < this.length; i++)
-        yield this[i]; }
+    [Symbol.iterator](): IterableIterator<T> { return this._items()[Symbol.iterator](); }
     /** @internal */ _insert(position: string, content: any[]): this {
-        const targets = this.ids.filter((id) => ['root', 'tag', 'script', 'style', 'cdata'].includes(nodeRecord(this._document, id).type));
+        const targets = this.ids.filter((id) => ['root', 'tag', 'script', 'style', 'cdata'].includes(nodeRecord(this[DOCUMENT], id).type));
         if (!targets.length)
             return this;
         if (typeof content[0] === 'function')
             return (this as Cheerio<any>).each((index, node: any) => {
                 if (!targets.includes(this.ids[index]))
                     return;
-                if ((position === 'before' || position === 'after') && nodeRecord(this._document, this.ids[index]).parent == null)
+                if ((position === 'before' || position === 'after') && nodeRecord(this[DOCUMENT], this.ids[index]).parent == null)
                     return;
-                const value = content[0].call(node, index, this._document.innerHtml(this.ids[index]));
+                const value = content[0].call(node, index, this[DOCUMENT].innerHtml(this.ids[index]));
                 let nodes = this._domIds(value);
                 if (index < this.length - 1)
                     nodes = this.op('clone', { ids: nodes, deep: true });
@@ -421,15 +521,15 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     ] | BasicAcceptedElems<AnyNode>[]): Cheerio<T>;
     after(this: Cheerio<any>, ...content: any[]): any { return this._insert('after', content); }
     appendTo<T extends AnyNode>(this: Cheerio<T>, target: BasicAcceptedElems<AnyNode>): Cheerio<T>;
-    appendTo(this: Cheerio<any>, target: any): any { this._api(target).append(this); return this; }
+    appendTo(this: Cheerio<any>, target: any): any { this[API](target).append(this); return this; }
     prependTo<T extends AnyNode>(this: Cheerio<T>, target: BasicAcceptedElems<AnyNode>): Cheerio<T>;
-    prependTo(this: Cheerio<any>, target: any): any { this._api(target).prepend(this); return this; }
+    prependTo(this: Cheerio<any>, target: any): any { this[API](target).prepend(this); return this; }
     /** @internal */ _insertRelative(target: any, position: string): Cheerio<T> {
-        const targets = this._api(target).ids;
+        const targets = this[API](target).ids;
         (this as Cheerio<any>).remove();
         const inserted: number[] = [];
         for (const id of targets) {
-            if (nodeRecord(this._document, id).parent == null)
+            if (nodeRecord(this[DOCUMENT], id).parent == null)
                 continue;
             const clones = this.op<number[]>('clone', { ids: this.ids, deep: true });
             this.op('insert', { targetIds: [id], nodeIds: clones, position });
@@ -446,7 +546,7 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     replaceWith<T extends AnyNode>(this: Cheerio<T>, content: AcceptedElems<AnyNode>): Cheerio<T>;
     replaceWith(this: Cheerio<any>, content: any): any {
         return this.each((index, node: any) => {
-            if (nodeRecord(this._document, this.ids[index]).parent == null)
+            if (nodeRecord(this[DOCUMENT], this.ids[index]).parent == null)
                 return;
             const value = typeof content === 'function' ? content.call(node, index, node) : content;
             this.op('insert', { targetIds: [this.ids[index]], nodeIds: this._domIds(value), position: 'replace' });
@@ -462,13 +562,13 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     html<T extends AnyNode>(this: Cheerio<T>, str: string | Cheerio<T>): Cheerio<T>;
     html(this: Cheerio<any>, content?: any): any {
         if (content === undefined)
-            return this.length && ['root', 'tag', 'script', 'style', 'cdata'].includes(nodeRecord(this._document, this.ids[0]).type) ? this._document.innerHtml(this.ids[0]) : null;
+            return this.length && ['root', 'tag', 'script', 'style', 'cdata'].includes(nodeRecord(this[DOCUMENT], this.ids[0]).type) ? this[DOCUMENT].innerHtml(this.ids[0]) : null;
         if (!content?.cheerio) {
             this.op('html', { ids: this.ids, value: String(content) });
             return this;
         }
         for (const id of this.ids) {
-            const nodes = content?.cheerio ? importNodes(this._document, content.toArray()) : this._domIds(String(content), id);
+            const nodes = content?.cheerio ? importNodes(this[DOCUMENT], content.toArray()) : this._domIds(String(content), id);
             this.op('setNode', { id, field: 'children', value: nodes });
         }
         return this;
@@ -477,26 +577,26 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     text<T extends AnyNode>(this: Cheerio<T>, str: string | ((this: AnyNode, i: number, text: string) => string)): Cheerio<T>;
     text(this: Cheerio<any>, content?: any): any {
         if (content === undefined)
-            return this._document.text(this.ids);
+            return this[DOCUMENT].text(this.ids);
         if (typeof content !== 'function') {
             this.op('text', { ids: this.ids, value: String(content) });
             return this;
         }
         for (let i = 0; i < this.ids.length; i++) {
             const id = this.ids[i];
-            const value = typeof content === 'function' ? content.call(getNode(this._document, id), i, this._document.text([id])) : content;
+            const value = typeof content === 'function' ? content.call(getNode(this[DOCUMENT], id), i, this[DOCUMENT].text([id])) : content;
             this.op('text', { ids: [id], value: String(value) });
         }
         return this;
     }
     toString<T extends AnyNode>(this: Cheerio<T>): string;
-    toString(this: Cheerio<any>): any { return this._document.outerHtml(this.ids); }
+    toString(this: Cheerio<any>): any { return this[DOCUMENT].outerHtml(this.ids); }
     clone<T extends AnyNode>(this: Cheerio<T>): Cheerio<T>;
     clone(this: Cheerio<any>): any { return this._fromIds(this.op('clone', { ids: this.ids, deep: true })); }
     /** @internal */ _deepest(id: number, tagsOnly = false): number {
         for (;;) {
             const children = this.op<number[]>('traverse', { ids: [id], kind: 'children' });
-            const child = tagsOnly ? children.find((candidate) => nodeRecord(this._document, candidate).type === 'tag') : children[0];
+            const child = tagsOnly ? children.find((candidate) => nodeRecord(this[DOCUMENT], candidate).type === 'tag') : children[0];
             if (child === undefined)
                 return id;
             id = child;
@@ -506,25 +606,25 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
         const lastParent = (this as Cheerio<any>).parents().last();
         for (let i = 0; i < this.length; i++) {
             const id = this.ids[i];
-            const node = getNode(this._document, id);
+            const node = getNode(this[DOCUMENT], id);
             const value = typeof content === 'function' ? content.call(node, i, node) : typeof content === 'string' && !isMarkup(content) ? lastParent.find(content).clone() : content;
             let wrappers = this._domIds(value);
             if (i < this.length - 1)
                 wrappers = this.op('clone', { ids: wrappers, deep: true });
             const wrapper = wrappers[0];
-            if (wrapper === undefined || !['root', 'tag', 'script', 'style'].includes(nodeRecord(this._document, wrapper).type))
+            if (wrapper === undefined || !['root', 'tag', 'script', 'style'].includes(nodeRecord(this[DOCUMENT], wrapper).type))
                 continue;
-            const deepest = this._deepest(wrapper);
             if (inner) {
-                if (!['root', 'tag', 'script', 'style', 'cdata'].includes(nodeRecord(this._document, id).type))
+                if (!['root', 'tag', 'script', 'style', 'cdata'].includes(nodeRecord(this[DOCUMENT], id).type))
                     continue;
                 const contents = this.op<number[]>('traverse', { ids: [id], kind: 'contents' });
-                this.op('setNode', { id: deepest, field: 'children', value: contents });
+                this.op('setNode', { id: this._deepest(wrapper), field: 'children', value: contents });
                 this.op('setNode', { id, field: 'children', value: [wrapper] });
             }
-            else if (nodeRecord(this._document, id).parent != null) {
-                this.op('insert', { targetIds: [id], nodeIds: [wrapper], position: 'before' });
-                this.op('setNode', { id: deepest, field: 'children', value: [id] });
+            else if (nodeRecord(this[DOCUMENT], id).parent != null) {
+                // A wrapper from another document gets new ids when the insertion moves it here.
+                const [inserted = wrapper] = this.op<number[]>('insert', { targetIds: [id], nodeIds: [wrapper], position: 'before' });
+                this.op('setNode', { id: this._deepest(inserted), field: 'children', value: [id] });
             }
         }
         return this;
@@ -541,7 +641,7 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
             return this;
         const first = this[0];
         const wrappers = this._make(typeof content === 'function' ? content.call(first, 0, first) : content).insertBefore(first);
-        const root = [...wrappers.ids].reverse().find((id) => nodeRecord(this._document, id).type === 'tag');
+        const root = [...wrappers.ids].reverse().find((id) => nodeRecord(this[DOCUMENT], id).type === 'tag');
         if (root !== undefined)
             this.op('insert', { targetIds: [this._deepest(root, true)], nodeIds: this.ids, position: 'append' });
         return this;
@@ -553,6 +653,20 @@ export class Cheerio<T = AnyNode> implements ArrayLike<T>, Iterable<T> {
     extract<M extends ExtractMap>(this: Cheerio<any>, map: any): any { return extract.call(this as any, map) as ExtractedMap<M>; }
 }
 Object.defineProperty(Cheerio.prototype, 'cheerio', { value: '[cheerio object]', writable: true, configurable: true });
+const inspectCustom = Symbol.for('nodejs.util.inspect.custom');
+// Inspection shows the selection's own string keys, as Cheerio's selections
+// have, without the internals stored under symbols.
+Object.defineProperty(Cheerio.prototype, inspectCustom, {
+    configurable: true, writable: true,
+    value(this: Cheerio<any>, depth: number, options: { stylize(text: string, style: string): string }, inspect: (value: unknown, options: object) => string): string {
+        const prototype = Object.getPrototypeOf(this);
+        if (depth < 0) return options.stylize(`[${prototype.constructor.name}]`, 'special');
+        const shown: Record<string | symbol, unknown> = Object.create(prototype);
+        Object.defineProperty(shown, inspectCustom, { value: undefined });
+        for (const key of Object.keys(this)) shown[key] = (this as any)[key];
+        return inspect(shown, { ...options, depth });
+    },
+});
 export interface Cheerio<T = AnyNode> extends AttributeMethods<T> {
 }
 installAttributes(Cheerio);