@depup/cheerio 1.2.0-depup.2

package/src/cheerio.ts

@@ -0,0 +1,143 @@
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+import type { InternalOptions } from './options.js';
+import type { AnyNode, Document, ParentNode } from 'domhandler';
+import type { BasicAcceptedElems } from './types.js';
+
+import * as Attributes from './api/attributes.js';
+import * as Traversing from './api/traversing.js';
+import * as Manipulation from './api/manipulation.js';
+import * as Css from './api/css.js';
+import * as Forms from './api/forms.js';
+import * as Extract from './api/extract.js';
+
+type MethodsType = typeof Attributes &
+  typeof Traversing &
+  typeof Manipulation &
+  typeof Css &
+  typeof Forms &
+  typeof Extract;
+
+/**
+ * The cheerio class is the central class of the library. It wraps a set of
+ * elements and provides an API for traversing, modifying, and interacting with
+ * the set.
+ *
+ * Loading a document will return the Cheerio class bound to the root element of
+ * the document. The class will be instantiated when querying the document (when
+ * calling `$('selector')`).
+ *
+ * @example This is the HTML markup we will be using in all of the API examples:
+ *
+ * ```html
+ * <ul id="fruits">
+ *   <li class="apple">Apple</li>
+ *   <li class="orange">Orange</li>
+ *   <li class="pear">Pear</li>
+ * </ul>
+ * ```
+ */
+export abstract class Cheerio<T> implements ArrayLike<T> {
+  length = 0;
+  [index: number]: T;
+
+  options: InternalOptions;
+  /**
+   * The root of the document. Can be set by using the `root` argument of the
+   * constructor.
+   *
+   * @private
+   */
+  _root: Cheerio<Document> | null;
+
+  /**
+   * Instance of cheerio. Methods are specified in the modules. Usage of this
+   * constructor is not recommended. Please use `$.load` instead.
+   *
+   * @private
+   * @param elements - The new selection.
+   * @param root - Sets the root node.
+   * @param options - Options for the instance.
+   */
+  constructor(
+    elements: ArrayLike<T> | undefined,
+    root: Cheerio<Document> | null,
+    options: InternalOptions,
+  ) {
+    this.options = options;
+    this._root = root;
+
+    if (elements) {
+      for (let idx = 0; idx < elements.length; idx++) {
+        this[idx] = elements[idx];
+      }
+      this.length = elements.length;
+    }
+  }
+
+  prevObject: Cheerio<any> | undefined;
+  /**
+   * Make a cheerio object.
+   *
+   * @private
+   * @param dom - The contents of the new object.
+   * @param context - The context of the new object.
+   * @returns The new cheerio object.
+   */
+  abstract _make<T>(
+    dom: ArrayLike<T> | T | string,
+    context?: BasicAcceptedElems<AnyNode>,
+  ): Cheerio<T>;
+
+  /**
+   * Parses some content.
+   *
+   * @private
+   * @param content - Content to parse.
+   * @param options - Options for parsing.
+   * @param isDocument - Allows parser to be switched to fragment mode.
+   * @returns A document containing the `content`.
+   */
+  abstract _parse(
+    content: string | Document | AnyNode | AnyNode[] | Buffer,
+    options: InternalOptions,
+    isDocument: boolean,
+    context: ParentNode | null,
+  ): Document;
+
+  /**
+   * Render an element or a set of elements.
+   *
+   * @private
+   * @param dom - DOM to render.
+   * @returns The rendered DOM.
+   */
+  abstract _render(dom: AnyNode | ArrayLike<AnyNode>): string;
+}
+
+export interface Cheerio<T> extends MethodsType, Iterable<T> {
+  cheerio: '[cheerio object]';
+
+  splice: typeof Array.prototype.splice;
+}
+
+/** Set a signature of the object. */
+Cheerio.prototype.cheerio = '[cheerio object]';
+
+/*
+ * Make cheerio an array-like object
+ */
+Cheerio.prototype.splice = Array.prototype.splice;
+
+// Support for (const element of $(...)) iteration:
+Cheerio.prototype[Symbol.iterator] = Array.prototype[Symbol.iterator];
+
+// Plug in the API
+Object.assign(
+  Cheerio.prototype,
+  Attributes,
+  Traversing,
+  Manipulation,
+  Css,
+  Forms,
+  Extract,
+);

package/src/index-browser.mts

@@ -0,0 +1,10 @@
+export type * from './types.js';
+export type {
+  Cheerio,
+  CheerioAPI,
+  CheerioOptions,
+  HTMLParser2Options,
+} from './slim.js';
+export { contains, merge } from './static.js';
+
+export * from './load-parse.js';

package/src/index.ts

@@ -0,0 +1,294 @@
+/**
+ * @file Batteries-included version of Cheerio. This module includes several
+ *   convenience methods for loading documents from various sources.
+ */
+
+export * from './load-parse.js';
+export { contains, merge } from './static.js';
+export type * from './types.js';
+export type {
+  Cheerio,
+  CheerioAPI,
+  CheerioOptions,
+  HTMLParser2Options,
+} from './slim.js';
+
+import { adapter as htmlparser2Adapter } from 'parse5-htmlparser2-tree-adapter';
+import * as htmlparser2 from 'htmlparser2';
+import { ParserStream as Parse5Stream } from 'parse5-parser-stream';
+import {
+  decodeBuffer,
+  DecodeStream,
+  type SnifferOptions,
+} from 'encoding-sniffer';
+import * as undici from 'undici';
+import MIMEType from 'whatwg-mimetype';
+import { Writable, finished } from 'node:stream';
+import type { CheerioAPI } from './load.js';
+import {
+  flattenOptions,
+  type InternalOptions,
+  type CheerioOptions,
+} from './options.js';
+import { load } from './load-parse.js';
+
+/**
+ * Sniffs the encoding of a buffer, then creates a querying function bound to a
+ * document created from the buffer.
+ *
+ * @category Loading
+ * @example
+ *
+ * ```js
+ * import * as cheerio from 'cheerio';
+ *
+ * const buffer = fs.readFileSync('index.html');
+ * const $ = cheerio.loadBuffer(buffer);
+ * ```
+ *
+ * @param buffer - The buffer to sniff the encoding of.
+ * @param options - The options to pass to Cheerio.
+ * @returns The loaded document.
+ */
+export function loadBuffer(
+  buffer: Buffer,
+  options: DecodeStreamOptions = {},
+): CheerioAPI {
+  const opts = flattenOptions(options);
+  const str = decodeBuffer(buffer, {
+    defaultEncoding: opts?.xmlMode ? 'utf8' : 'windows-1252',
+    ...options.encoding,
+  });
+
+  return load(str, opts);
+}
+
+function _stringStream(
+  options: InternalOptions | undefined,
+  cb: (err: Error | null | undefined, $: CheerioAPI) => void,
+): Writable {
+  if (options?._useHtmlParser2) {
+    const parser = htmlparser2.createDocumentStream(
+      (err, document) => cb(err, load(document, options)),
+      options,
+    );
+
+    return new Writable({
+      decodeStrings: false,
+      write(chunk, _encoding, callback) {
+        if (typeof chunk !== 'string') {
+          throw new TypeError('Expected a string');
+        }
+
+        parser.write(chunk);
+        callback();
+      },
+      final(callback) {
+        parser.end();
+        callback();
+      },
+    });
+  }
+
+  options ??= {};
+  options.treeAdapter ??= htmlparser2Adapter;
+
+  if (options.scriptingEnabled !== false) {
+    options.scriptingEnabled = true;
+  }
+
+  const stream = new Parse5Stream(options);
+
+  finished(stream, (err) => cb(err, load(stream.document, options)));
+
+  return stream;
+}
+
+/**
+ * Creates a stream that parses a sequence of strings into a document.
+ *
+ * The stream is a `Writable` stream that accepts strings. When the stream is
+ * finished, the callback is called with the loaded document.
+ *
+ * @category Loading
+ * @example
+ *
+ * ```js
+ * import * as cheerio from 'cheerio';
+ * import * as fs from 'fs';
+ *
+ * const writeStream = cheerio.stringStream({}, (err, $) => {
+ *   if (err) {
+ *     // Handle error
+ *   }
+ *
+ *   console.log($('h1').text());
+ *   // Output: Hello, world!
+ * });
+ *
+ * fs.createReadStream('my-document.html', { encoding: 'utf8' }).pipe(
+ *   writeStream,
+ * );
+ * ```
+ *
+ * @param options - The options to pass to Cheerio.
+ * @param cb - The callback to call when the stream is finished.
+ * @returns The writable stream.
+ */
+export function stringStream(
+  options: CheerioOptions,
+  cb: (err: Error | null | undefined, $: CheerioAPI) => void,
+): Writable {
+  return _stringStream(flattenOptions(options), cb);
+}
+
+export interface DecodeStreamOptions extends CheerioOptions {
+  encoding?: SnifferOptions;
+}
+
+/**
+ * Parses a stream of buffers into a document.
+ *
+ * The stream is a `Writable` stream that accepts buffers. When the stream is
+ * finished, the callback is called with the loaded document.
+ *
+ * @category Loading
+ * @param options - The options to pass to Cheerio.
+ * @param cb - The callback to call when the stream is finished.
+ * @returns The writable stream.
+ */
+export function decodeStream(
+  options: DecodeStreamOptions,
+  cb: (err: Error | null | undefined, $: CheerioAPI) => void,
+): Writable {
+  const { encoding = {}, ...cheerioOptions } = options;
+  const opts = flattenOptions(cheerioOptions);
+
+  // Set the default encoding to UTF-8 for XML mode
+  encoding.defaultEncoding ??= opts?.xmlMode ? 'utf8' : 'windows-1252';
+
+  const decodeStream = new DecodeStream(encoding);
+  const loadStream = _stringStream(opts, cb);
+
+  decodeStream.pipe(loadStream);
+
+  return decodeStream;
+}
+
+type UndiciStreamOptions = Omit<
+  undici.Dispatcher.RequestOptions<unknown>,
+  'path'
+>;
+
+export interface CheerioRequestOptions extends DecodeStreamOptions {
+  /** The options passed to `undici`'s `stream` method. */
+  requestOptions?: UndiciStreamOptions;
+}
+
+const defaultRequestOptions: UndiciStreamOptions = {
+  method: 'GET',
+  // Set an Accept header
+  headers: {
+    accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+  },
+};
+
+/**
+ * `fromURL` loads a document from a URL.
+ *
+ * By default, redirects are allowed and non-2xx responses are rejected.
+ *
+ * @category Loading
+ * @example
+ *
+ * ```js
+ * import * as cheerio from 'cheerio';
+ *
+ * const $ = await cheerio.fromURL('https://example.com');
+ * ```
+ *
+ * @param url - The URL to load the document from.
+ * @param options - The options to pass to Cheerio.
+ * @returns The loaded document.
+ */
+export async function fromURL(
+  url: string | URL,
+  options: CheerioRequestOptions = {},
+): Promise<CheerioAPI> {
+  const {
+    requestOptions = defaultRequestOptions,
+    encoding = {},
+    ...cheerioOptions
+  } = options;
+  let undiciStream: Promise<undici.Dispatcher.StreamData<unknown>> | undefined;
+
+  // Add headers if none were supplied.
+  const urlObject = typeof url === 'string' ? new URL(url) : url;
+  const streamOptions = {
+    headers: defaultRequestOptions.headers,
+    path: urlObject.pathname + urlObject.search,
+    ...requestOptions,
+  };
+
+  const promise = new Promise<CheerioAPI>((resolve, reject) => {
+    undiciStream = new undici.Client(urlObject.origin)
+      .compose(undici.interceptors.redirect({ maxRedirections: 5 }))
+      .stream(streamOptions, (res) => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          throw new undici.errors.ResponseError(
+            'Response Error',
+            res.statusCode,
+            {
+              headers: res.headers,
+            },
+          );
+        }
+
+        const contentTypeHeader = res.headers['content-type'] ?? 'text/html';
+        const mimeType = new MIMEType(
+          Array.isArray(contentTypeHeader)
+            ? contentTypeHeader[0]
+            : contentTypeHeader,
+        );
+
+        if (!mimeType.isHTML() && !mimeType.isXML()) {
+          throw new RangeError(
+            `The content-type "${mimeType.essence}" is neither HTML nor XML.`,
+          );
+        }
+
+        // Forward the charset from the header to the decodeStream.
+        encoding.transportLayerEncodingLabel =
+          mimeType.parameters.get('charset');
+
+        /*
+         * If we allow redirects, we will have entries in the history.
+         * The last entry will be the final URL.
+         */
+        const history = (
+          res.context as
+            | {
+                history?: URL[];
+              }
+            | undefined
+        )?.history;
+        // Set the `baseURI` to the final URL.
+        const baseURI = history ? history[history.length - 1] : urlObject;
+
+        const opts: DecodeStreamOptions = {
+          encoding,
+          // Set XML mode based on the MIME type.
+          xmlMode: mimeType.isXML(),
+          baseURI,
+          ...cheerioOptions,
+        };
+
+        return decodeStream(opts, (err, $) => (err ? reject(err) : resolve($)));
+      });
+  });
+
+  // Let's make sure the request is completed before returning the promise.
+  await undiciStream;
+
+  return promise;
+}

package/src/load-parse.ts

@@ -0,0 +1,39 @@
+import { type CheerioAPI, getLoad } from './load.js';
+import { getParse } from './parse.js';
+import { renderWithParse5, parseWithParse5 } from './parsers/parse5-adapter.js';
+import type { CheerioOptions } from './options.js';
+import renderWithHtmlparser2 from 'dom-serializer';
+import { parseDocument as parseWithHtmlparser2 } from 'htmlparser2';
+import type { AnyNode } from 'domhandler';
+
+const parse = getParse((content, options, isDocument, context) =>
+  options._useHtmlParser2
+    ? parseWithHtmlparser2(content, options)
+    : parseWithParse5(content, options, isDocument, context),
+);
+
+// Duplicate docs due to https://github.com/TypeStrong/typedoc/issues/1616
+/**
+ * Create a querying function, bound to a document created from the provided
+ * markup.
+ *
+ * Note that similar to web browser contexts, this operation may introduce
+ * `<html>`, `<head>`, and `<body>` elements; set `isDocument` to `false` to
+ * switch to fragment mode and disable this.
+ *
+ * @category Loading
+ * @param content - Markup to be loaded.
+ * @param options - Options for the created instance.
+ * @param isDocument - Allows parser to be switched to fragment mode.
+ * @returns The loaded document.
+ * @see {@link https://cheerio.js.org/docs/basics/loading#load} for additional usage information.
+ */
+export const load: (
+  content: string | AnyNode | AnyNode[] | Buffer,
+  options?: CheerioOptions | null,
+  isDocument?: boolean,
+) => CheerioAPI = getLoad(parse, (dom, options) =>
+  options._useHtmlParser2
+    ? renderWithHtmlparser2(dom, options)
+    : renderWithParse5(dom),
+);