rusteerio 0.0.0-stage → 0.1.0

package/src/transport.ts

@@ -0,0 +1,104 @@
+import { decodeJson, decodeString, encodeJson, encodeOptions, encodeString } from './codec.js';
+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 globals = globalThis as typeof globalThis & { [key: symbol]: TransportRegistry | undefined };
+const registry = globals[registryKey] ??= { documents: new WeakMap(), originals: new WeakMap(), userErrors: new WeakSet() };
+
+/** 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 restoreError = (error: unknown): never => {
+    if (error instanceof Error && !userErrors.has(error)) {
+      const message = decodeString(error.message);
+      if (message !== error.message) {
+        const stack = error.stack;
+        error.message = message;
+        if (stack) error.stack = decodeString(stack);
+      }
+    }
+    throw error;
+  };
+  const invoke = <T>(call: () => T): T => {
+    try {
+      const result = call();
+      return result instanceof Promise ? result.catch(restoreError) as T : result;
+    } catch (error) { return restoreError(error); }
+  };
+  const wrapBridge = (bridge: (request: string) => string) => (request: string): string => {
+    try { return encodeJson(bridge(decodeJson(request))); }
+    catch (error) {
+      if (error !== null && (typeof error === 'object' || typeof error === 'function')) userErrors.add(error);
+      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;
+  };
+  const wrapStream = (stream: any) => {
+    let carry = '';
+    return {
+      async write(chunk: string) {
+        let source = carry + chunk;
+        carry = '';
+        const last = source.charCodeAt(source.length - 1);
+        if (last >= 0xd800 && last <= 0xdbff) { carry = source.slice(-1); source = source.slice(0, -1); }
+        if (source) await invoke(() => stream.write(encodeString(source)));
+      },
+      async finish() {
+        if (carry) { const final = carry; carry = ''; await invoke(() => stream.write(encodeString(final))); }
+        return wrapDocument(await invoke(() => stream.finish()));
+      },
+      abort() { carry = ''; return invoke(() => stream.abort()); },
+    };
+  };
+  const wrapConstructor = (Constructor: any, argumentsFor: (args: any[]) => any[], wrap: (value: any) => any) => new Proxy(Constructor, {
+    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);
+  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.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;
+}

package/src/types.ts

@@ -0,0 +1,186 @@
+import type { Cheerio } from './selection.js';
+import type { ParserErrorHandler, TreeAdapter, TokenizerConstructor } from './parser-types.js';
+export type * from './parser-types.js';
+
+/** DOM-compatible views over stable nodes owned by the native document. */
+export declare enum ElementType {
+  Root = 'root', Text = 'text', Directive = 'directive', Comment = 'comment',
+  Script = 'script', Style = 'style', Tag = 'tag', CDATA = 'cdata', Doctype = 'doctype',
+}
+
+export interface SourceCodeLocation {
+  startLine: number; startCol: number; startOffset: number;
+  endLine: number; endCol: number; endOffset: number;
+}
+export interface TagSourceCodeLocation extends SourceCodeLocation { startTag?: SourceCodeLocation; endTag?: SourceCodeLocation; attrs?: Record<string, SourceCodeLocation> }
+
+export interface Node {
+  readonly type: ElementType;
+  parent: ParentNode | null;
+  prev: ChildNode | null;
+  next: ChildNode | null;
+  startIndex: number | null;
+  endIndex: number | null;
+  readonly nodeType: number;
+  parentNode: ParentNode | null;
+  previousSibling: ChildNode | null;
+  nextSibling: ChildNode | null;
+  sourceCodeLocation?: SourceCodeLocation | null;
+  cloneNode<T extends Node>(this: T, recursive?: boolean): T;
+}
+
+export interface DataNode extends Node { data: string; nodeValue: string }
+export interface Text extends DataNode { type: ElementType.Text; readonly nodeType: 3 }
+export interface Comment extends DataNode { type: ElementType.Comment; readonly nodeType: 8 }
+export interface ProcessingInstruction extends DataNode {
+  type: ElementType.Directive;
+  name: string;
+  readonly nodeType: 1;
+  'x-name'?: string;
+  'x-publicId'?: string;
+  'x-systemId'?: string;
+}
+export interface NodeWithChildren extends Node {
+  children: ChildNode[];
+  childNodes: ChildNode[];
+  readonly firstChild: ChildNode | null;
+  readonly lastChild: ChildNode | null;
+}
+export interface Document extends NodeWithChildren { type: ElementType.Root; readonly nodeType: 9; 'x-mode'?: 'quirks' | 'limited-quirks' | 'no-quirks' }
+export interface CDATA extends NodeWithChildren { type: ElementType.CDATA; readonly nodeType: 4 }
+export interface Element extends NodeWithChildren {
+  type: ElementType.Tag | ElementType.Script | ElementType.Style;
+  readonly nodeType: 1;
+  name: string;
+  tagName: string;
+  attribs: Record<string, string>;
+  namespace?: string;
+  sourceCodeLocation?: TagSourceCodeLocation | null;
+  readonly attributes: { name: string; value: string; namespace?: string; prefix?: string }[];
+  'x-attribsNamespace'?: Record<string, string>;
+  'x-attribsPrefix'?: Record<string, string>;
+}
+export type ParentNode = Document | Element | CDATA;
+export type ChildNode = Text | Comment | ProcessingInstruction | Element | CDATA | Document;
+export type AnyNode = ParentNode | ChildNode;
+
+export interface HTMLParser2Options {
+  xmlMode?: boolean;
+  decodeEntities?: boolean;
+  encodeEntities?: boolean | 'utf8';
+  lowerCaseTags?: boolean;
+  lowerCaseAttributeNames?: boolean;
+  recognizeCDATA?: boolean;
+  recognizeSelfClosing?: boolean;
+  withStartIndices?: boolean;
+  withEndIndices?: boolean;
+  emptyAttrs?: boolean;
+  selfClosingTags?: boolean;
+  Tokenizer?: TokenizerConstructor;
+  [key: string]: any;
+}
+
+export interface CheerioOptions extends HTMLParser2Options {
+  xml?: boolean | HTMLParser2Options;
+  baseURI?: string | URL;
+  quirksMode?: boolean;
+  scriptingEnabled?: boolean;
+  sourceCodeLocationInfo?: boolean;
+  treeAdapter?: TreeAdapter;
+  onParseError?: ParserErrorHandler | null;
+  pseudos?: Record<string, string | ((element: Element, value?: string | null) => boolean)>;
+  _useHtmlParser2?: boolean;
+}
+export type InternalOptions = CheerioOptions;
+
+type LowercaseLetters = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
+type AlphaNumeric = LowercaseLetters | Uppercase<LowercaseLetters> | `${number}`;
+export type SelectorType = `${'.' | '#' | ':' | '|' | '>' | '+' | '~' | '['}${AlphaNumeric}${string}` | `${AlphaNumeric}${string}`;
+export type BasicAcceptedElems<T extends AnyNode = AnyNode> = ArrayLike<T> | T | string;
+export type AcceptedElems<T extends AnyNode = AnyNode> = BasicAcceptedElems<T> | ((this: T, index: number, element: T) => BasicAcceptedElems<T>);
+export type FilterFunction<T> = (this: T, index: number, element: T) => boolean;
+export type AcceptedFilters<T> = string | FilterFunction<T> | T | Cheerio<T>;
+export type LoadContent = string | Buffer | AnyNode | ArrayLike<AnyNode>;
+
+export interface CheerioAPI {
+  <T extends AnyNode, S extends string>(
+    selector?: S | BasicAcceptedElems<T>,
+    context?: BasicAcceptedElems<AnyNode> | null,
+    root?: BasicAcceptedElems<Document>,
+    options?: CheerioOptions,
+  ): Cheerio<S extends SelectorType ? Element : T>;
+  <T extends AnyNode, S extends string>(
+    selector?: S | BasicAcceptedElems<T>,
+    context?: BasicAcceptedElems<AnyNode> | null,
+    root?: BasicAcceptedElems<Document>,
+    options?: CheerioOptions,
+  ): Cheerio<AnyNode>;
+  html(options?: CheerioOptions): string;
+  html(dom?: BasicAcceptedElems<AnyNode> | Cheerio<AnyNode>, options?: CheerioOptions): string;
+  xml(dom?: BasicAcceptedElems<AnyNode> | Cheerio<AnyNode>): string;
+  text(elements?: ArrayLike<AnyNode>): string;
+  root(): Cheerio<Document>;
+  contains(container: AnyNode, contained: AnyNode): boolean;
+  merge<T>(first: ArrayLike<T>, second: ArrayLike<T>): ArrayLike<T> | undefined;
+  parseHTML(data: string, context?: unknown, keepScripts?: boolean): AnyNode[];
+  parseHTML(data?: '' | null): null;
+  load(content: LoadContent, options?: CheerioOptions | null, isDocument?: boolean): CheerioAPI;
+  extract<M extends ExtractMap>(this: CheerioAPI, map: M): ExtractedMap<M>;
+  extract<M extends ExtractMap>(this: CheerioAPI, map: M): Record<string, unknown>;
+  fn: typeof Cheerio.prototype;
+  _root: Document;
+  _options: InternalOptions;
+  [key: string]: any;
+}
+
+type ExtractDescriptorFn = (element: Element, key: string, result: Record<string, unknown>) => unknown;
+export interface ExtractDescriptor {
+  selector: string;
+  value?: string | ExtractDescriptorFn | ExtractMap;
+}
+type ExtractValue = string | ExtractDescriptor | [string | ExtractDescriptor];
+export type ExtractMap = Record<string, ExtractValue>;
+export type ExtractedValue<V extends ExtractValue> = V extends [string | ExtractDescriptor]
+  ? NonNullable<ExtractedValue<V[0]>>[]
+  : V extends string ? string | undefined
+  : V extends ExtractDescriptor ? V['value'] extends infer U
+    ? U extends ExtractMap ? ExtractedMap<U> | undefined
+    : U extends ExtractDescriptorFn ? ReturnType<U> | undefined
+    : string | undefined
+    : never
+  : never;
+export type ExtractedMap<M extends ExtractMap> = {
+  [key in keyof M]: ExtractedValue<M[key]>;
+};
+export type ExtractionDescriptor = ExtractDescriptor;
+export type ExtractionMap = ExtractMap;
+export type ExtractionResult<M extends ExtractMap> = ExtractedMap<M>;
+
+export interface EncodingOptions { defaultEncoding?: string; transportLayerEncodingLabel?: string | null; userEncoding?: string; maxBytes?: number }
+export interface DecodeStreamOptions extends CheerioOptions { encoding?: EncodingOptions }
+/** Structural Node/Undici FormData compatibility without importing its package. */
+export interface FormDataLike extends Iterable<[string, string | import('node:buffer').Blob]> {
+  append(name: string, value: unknown, filename?: string): void;
+  get(name: string): string | import('node:buffer').Blob | null;
+}
+export interface CheerioRequestOptions extends DecodeStreamOptions {
+  requestOptions?: {
+    method?: string;
+    headers?: Record<string, string | string[] | undefined> | string[] | Iterable<[string, string | string[] | undefined]> | Headers | null;
+    body?: string | Buffer | Uint8Array | import('node:stream').Readable | FormData | FormDataLike | null;
+    query?: import('node:querystring').ParsedUrlQueryInput;
+    onInfo?: (info: { statusCode: number; headers: Record<string, string | string[]> }) => void;
+    reset?: boolean;
+    typeOfService?: number | null;
+    highWaterMark?: number;
+    maxRedirections?: number;
+    throwOnError?: boolean;
+    signal?: unknown;
+    headersTimeout?: number | null;
+    bodyTimeout?: number | null;
+    dispatcher?: unknown;
+    [key: string]: unknown;
+  };
+}
+export interface ParallelOptions extends CheerioOptions { threads?: number }
+export type SerializedField = { name: string; value: string };

package/src/utils.ts

@@ -0,0 +1,29 @@
+import type { AnyNode, Element } from './types.js';
+import type { Cheerio } from './selection.js';
+
+export function isCheerio(value: unknown): value is Cheerio<AnyNode> {
+  return value !== null && typeof value === 'object' && 'cheerio' in value;
+}
+
+export function camelCase(value: string): string {
+  return value.replace(/[._-](\w|$)/g, (_match, character: string) => character.toUpperCase());
+}
+
+export function cssCase(value: string): string {
+  return value.replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`);
+}
+
+export function domEach<T, A extends ArrayLike<T>>(array: A, callback: (element: T, index: number) => void): A {
+  for (let index = 0; index < array.length; index += 1) callback(array[index], index);
+  return array;
+}
+
+export function isHtml(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const start = value.indexOf('<');
+  return start >= 0 && /[A-Za-z!]/.test(value[start + 1] ?? '') && value.indexOf('>', start + 2) >= 0;
+}
+
+export function isTag(node: AnyNode): node is Element {
+  return node.type === 'tag' || node.type === 'script' || node.type === 'style';
+}

package/src/workers.ts

@@ -0,0 +1,21 @@
+import { requireNative, type NativeWorkerPoolInfo } from './native.js';
+
+export interface WorkerOptions { threads: number }
+export type WorkerPoolInfo = NativeWorkerPoolInfo;
+
+/** Set the process-wide native CPU-worker budget before starting async work. */
+export function configureWorkers(options: WorkerOptions | number): WorkerPoolInfo {
+  const threads = typeof options === 'number' ? options : options?.threads;
+  if (!Number.isSafeInteger(threads) || threads < 1 || threads > 256) throw new RangeError('threads must be an integer from 1 to 256');
+  const binding = requireNative();
+  if (!binding.configureWorkerPool || !binding.workerPoolInfo) throw new Error('This native build does not support a shared worker pool');
+  binding.configureWorkerPool(threads);
+  return binding.workerPoolInfo();
+}
+
+/** Observe the configured budget and actual concurrent native CPU work. */
+export function workerPoolInfo(): WorkerPoolInfo {
+  const binding = requireNative();
+  if (!binding.workerPoolInfo) throw new Error('This native build does not support worker pool diagnostics');
+  return binding.workerPoolInfo();
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "stripInternal": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "tsup.config.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/slim.ts', 'src/utils.ts'],
+  format: ['cjs', 'esm'],
+  outExtension({ format }) { return { js: format === 'esm' ? '.mjs' : '.cjs' }; },
+  target: 'node20',
+  platform: 'node',
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  esbuildOptions(options) {
+    // The CommonJS loader uses __dirname, so its import.meta branch is dead.
+    options.logOverride = { 'empty-import-meta': 'silent' };
+  },
+});