crawlee-one 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# Crawlee One
+
+_The crawler framework you can't refuse._
+
+Crawlee One is a framework built on top of Crawlee and Apify\* for writing robust and highly configurable web scrapers.
+
+Crawlee One should be your choice if:
+
+- You're developing a long-lasting integration.
+- Or your scraper will be part of a data pipeline.
+- Or you wish to make your scrapers available to others in your team / org, whether it's programmatically or via Apify UI.
+
+Conversely, Crawlee One is NOT suitable for:
+
+- People not familiar with web scraping or Apify
+- One-off data extractions
+
+[Read here](./docs/scraping-workflow-summary.md) for the recap of how Crawlee and Apify work.
+
+## Use cases
+
+Web crawlers written with Crawlee One can be configured via their input to handle following advanced use cases:
+
+- [1. Import URLs to scrape from your database (or elsewhere)](./docs/playbook-01-import-urls.md)
+- [2. Proxy: Avoid rate limiting and geo-blocking](./docs/playbook-02-proxy.md)
+- [3. Simple transformations: Select and rename columns, set how many entries to scrape](./docs/playbook-03-results-mapping-simple.md)
+- [4. Advanced transformations & aggregations](./docs/playbook-04-results-mapping-advanced.md)
+- [5. Filtering results](./docs/playbook-05-results-filtering.md)
+- [6. Deciding what URLs to scrape: Filtering and transforming requests](./docs/playbook-06-requests-mapping-filtering.md)
+- [7. Caching: Extract only new or only previously-seen entries](./docs/playbook-07-caching.md)
+- [8. Configure crawler settings and performance](./docs/playbook-08-settings-performance.md)
+- [9. Create data pipelines from scrapers using metamorph](./docs/playbook-09-data-pipelines-metamorph.md)
+- [10. Privacy compliance: Include or omit personal data](./docs/playbook-10-privacy-compliance.md)
+- [11. Capture errors](./docs/playbook-11-errors.md)
+- [12. Source control: Keep scraper configuration in sync](./docs/playbook-12-source-control.md)
+
+## Library contents
+
+Crawlee One includes a set of utility functions for:
+
+- Actor boilterplating
+  - Allows to set crawler settings from Apify input
+  - Enrich data with metadata
+  - Configure logging level
+  - Routing
+  - Error handling
+    - Save errors to separate Apify dataset
+    - Send errors to Sentry
+- Testing actors
+- Manipulating DOM
+- Actor migration (conceptually similar to database migration)
+  - CLI utility for updating actors via apify-client
+- Apify's `actor.json` generation
+- Privacy compliance
+- Metamorphing
+
+## Actor Input Reference
+
+[See here](./docs/reference-input.md) the full list of all possible input options that a Crawlee One crawler can have.
+
+Crawlee One allows you to configure the following via the input:
+
+- [Programmatically-defined input](./docs/reference-input.md#programmatic-input-advanced)
+- [Starting URLs](./docs/reference-input.md#starting-urls)
+- [Proxy](./docs/reference-input.md#proxy)
+- [Privacy & Data governance (GDPR)](./docs/reference-input.md#privacy--data-governance-gdpr)
+- [Requests limit, transformation & filtering](./docs/reference-input.md#requests-limit-transformation--filtering-advanced)
+- [Output size, transformation & filtering (T in ETL)](./docs/reference-input.md#output-size-transformation--filtering-t-in-etl-advanced)
+- [Output Dataset & Caching (L in ETL)](./docs/reference-input.md#output-dataset--caching-l-in-etl-advanced)
+- [Crawler configuration](./docs/reference-input.md#crawler-configuration-advanced)
+- [Performance configuration](./docs/reference-input.md#performance-configuration-advanced)
+- [Logging & Error handling](./docs/reference-input.md#logging--error-handling-advanced)
+- [Integrations (Metamorphing)](./docs/reference-input.md#integrations-metamorphing-advanced)
+
+## Example project
+
+// TODO
+
+---
+
+\* Apify can be replaced with your own implementation, so the data can be sent elsewhere, not just to Apify. This is set by the `io` options.

package/dist/cjs/cli/cli.d.ts

@@ -0,0 +1 @@
+export declare const cli: () => void;

package/dist/cjs/cli/cli.js

@@ -0,0 +1,61 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cli = void 0;
+const commander_1 = require("commander");
+const path_1 = __importDefault(require("path"));
+const package_1 = require("../utils/package");
+const localMigrator_1 = require("../lib/migrate/localMigrator");
+const pkgJson = (0, package_1.getPackageJsonInfo)(module, ['name', 'version']);
+commander_1.program //
+    .name(pkgJson.name)
+    .description('CLI to run crawlee-one tools')
+    .version(pkgJson.version);
+commander_1.program
+    .command('migrate')
+    .description('Run a migration script specified by the version number')
+    .requiredOption('-t --target <target-version>', 'migration version to execute, eg "v1"')
+    .requiredOption('-d --dir <path>', 'path to the migrations directory')
+    .option('--delimeter [delimeter]', 'delimeter between version and rest of file name, eg "v1_filename"')
+    .option('--ext --extension [ext-glob]', 'glob pattern for valid extensions for migration files, eg ".js" or ".{js,ts}"')
+    .addHelpText('after', `
+
+Example call:
+  $ crawlee-one migrate -d ./path/to/migrations-dir -t v1`)
+    .action(({ dir, target, extension, delimeter }) => __awaiter(void 0, void 0, void 0, function* () {
+    const migrationsDir = path_1.default.resolve(process.cwd(), dir);
+    const { migrate } = (0, localMigrator_1.createLocalMigrator)({ migrationsDir, extension, delimeter });
+    yield migrate(target);
+}));
+commander_1.program
+    .command('unmigrate')
+    .description('Run an un-migration script specified by the version number')
+    .requiredOption('-t --target <target-version>', 'migration version to execute, eg "v1"')
+    .requiredOption('-d --dir <path>', 'path to the migrations directory')
+    .option('--delimeter [delimeter]', 'delimeter between version and rest of file name, eg "v1_filename"')
+    .option('--ext --extension [ext-glob]', 'glob pattern for valid extensions for migration files, eg ".js" or ".{js,ts}"')
+    .addHelpText('after', `
+
+Example call:
+  $ crawlee-one unmigrate -d ./path/to/migrations-dir -t v1`)
+    .action(({ dir, target, extension, delimeter }) => __awaiter(void 0, void 0, void 0, function* () {
+    const migrationsDir = path_1.default.resolve(process.cwd(), dir);
+    const { unmigrate } = (0, localMigrator_1.createLocalMigrator)({ migrationsDir, extension, delimeter });
+    yield unmigrate(target);
+}));
+const cli = () => {
+    commander_1.program.parse();
+};
+exports.cli = cli;
+//# sourceMappingURL=cli.js.map

package/dist/cjs/cli/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../src/cli/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,yCAAoC;AACpC,gDAAwB;AAExB,8CAAsD;AACtD,gEAAmE;AAEnE,MAAM,OAAO,GAAG,IAAA,4BAAkB,EAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEhE,mBAAO,CAAC,EAAE;KACP,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;KAClB,WAAW,CAAC,8BAA8B,CAAC;KAC3C,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAE5B,mBAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CAAC,wDAAwD,CAAC;KACrE,cAAc,CAAC,8BAA8B,EAAE,uCAAuC,CAAC;KACvF,cAAc,CAAC,iBAAiB,EAAE,kCAAkC,CAAC;KACrE,MAAM,CACL,yBAAyB,EACzB,mEAAmE,CACpE;KACA,MAAM,CACL,8BAA8B,EAC9B,+EAA+E,CAChF;KACA,WAAW,CACV,OAAO,EACP;;;0DAGsD,CACvD;KACA,MAAM,CAAC,CAAO,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE;IACtD,MAAM,aAAa,GAAG,cAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAA,mCAAmB,EAAC,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;IACjF,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC,CAAA,CAAC,CAAC;AAEL,mBAAO;KACJ,OAAO,CAAC,WAAW,CAAC;KACpB,WAAW,CAAC,4DAA4D,CAAC;KACzE,cAAc,CAAC,8BAA8B,EAAE,uCAAuC,CAAC;KACvF,cAAc,CAAC,iBAAiB,EAAE,kCAAkC,CAAC;KACrE,MAAM,CACL,yBAAyB,EACzB,mEAAmE,CACpE;KACA,MAAM,CACL,8BAA8B,EAC9B,+EAA+E,CAChF;KACA,WAAW,CACV,OAAO,EACP;;;4DAGwD,CACzD;KACA,MAAM,CAAC,CAAO,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE;IACtD,MAAM,aAAa,GAAG,cAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,EAAE,SAAS,EAAE,GAAG,IAAA,mCAAmB,EAAC,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;IACnF,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC,CAAA,CAAC,CAAC;AAEE,MAAM,GAAG,GAAG,GAAG,EAAE;IACtB,mBAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC,CAAC;AAFW,QAAA,GAAG,OAEd","sourcesContent":["import { program } from 'commander';\nimport path from 'path';\n\nimport { getPackageJsonInfo } from '../utils/package';\nimport { createLocalMigrator } from '../lib/migrate/localMigrator';\n\nconst pkgJson = getPackageJsonInfo(module, ['name', 'version']);\n\nprogram //\n  .name(pkgJson.name)\n  .description('CLI to run crawlee-one tools')\n  .version(pkgJson.version);\n\nprogram\n  .command('migrate')\n  .description('Run a migration script specified by the version number')\n  .requiredOption('-t --target <target-version>', 'migration version to execute, eg \"v1\"')\n  .requiredOption('-d --dir <path>', 'path to the migrations directory')\n  .option(\n    '--delimeter [delimeter]',\n    'delimeter between version and rest of file name, eg \"v1_filename\"'\n  )\n  .option(\n    '--ext --extension [ext-glob]',\n    'glob pattern for valid extensions for migration files, eg \".js\" or \".{js,ts}\"'\n  )\n  .addHelpText(\n    'after',\n    `\n\nExample call:\n  $ crawlee-one migrate -d ./path/to/migrations-dir -t v1`\n  )\n  .action(async ({ dir, target, extension, delimeter }) => {\n    const migrationsDir = path.resolve(process.cwd(), dir);\n    const { migrate } = createLocalMigrator({ migrationsDir, extension, delimeter });\n    await migrate(target);\n  });\n\nprogram\n  .command('unmigrate')\n  .description('Run an un-migration script specified by the version number')\n  .requiredOption('-t --target <target-version>', 'migration version to execute, eg \"v1\"')\n  .requiredOption('-d --dir <path>', 'path to the migrations directory')\n  .option(\n    '--delimeter [delimeter]',\n    'delimeter between version and rest of file name, eg \"v1_filename\"'\n  )\n  .option(\n    '--ext --extension [ext-glob]',\n    'glob pattern for valid extensions for migration files, eg \".js\" or \".{js,ts}\"'\n  )\n  .addHelpText(\n    'after',\n    `\n\nExample call:\n  $ crawlee-one unmigrate -d ./path/to/migrations-dir -t v1`\n  )\n  .action(async ({ dir, target, extension, delimeter }) => {\n    const migrationsDir = path.resolve(process.cwd(), dir);\n    const { unmigrate } = createLocalMigrator({ migrationsDir, extension, delimeter });\n    await unmigrate(target);\n  });\n\nexport const cli = () => {\n  program.parse();\n};\n"]}

package/dist/cjs/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cjs/cli/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("./cli");
+(0, cli_1.cli)();
+//# sourceMappingURL=index.js.map

package/dist/cjs/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";;;AACA,+BAA4B;AAE5B,IAAA,SAAG,GAAE,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { cli } from './cli';\n\ncli();\n"]}

package/dist/cjs/index.d.ts

@@ -0,0 +1,24 @@
+export { createAndRunCrawleeOne, createHttpCrawlerOptions } from './lib/actor/actor';
+export * from './lib/actor/types';
+export * from './lib/actorSpec';
+export * from './lib/config';
+export * from './lib/io/dataset';
+export * from './lib/io/requestQueue';
+export * from './lib/io/pushData';
+export * from './lib/io/pushRequests';
+export * from './lib/actions/dom';
+export * from './lib/actions/domUtils';
+export * from './lib/actions/page';
+export * from './lib/actions/scrapeListing';
+export * from './lib/error/errorHandler';
+export * from './lib/error/sentry';
+export * from './lib/migrate/localMigrator';
+export * from './lib/migrate/localState';
+export * from './lib/migrate/types';
+export * from './lib/readme/readme';
+export * from './lib/readme/types';
+export * from './lib/router';
+export * from './lib/log';
+export * from './lib/test/actor';
+export * from './lib/test/mockApifyClient';
+export type { CrawlerUrl, CrawlerType } from './types';

package/dist/cjs/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHttpCrawlerOptions = exports.createAndRunCrawleeOne = void 0;
+var actor_1 = require("./lib/actor/actor");
+Object.defineProperty(exports, "createAndRunCrawleeOne", { enumerable: true, get: function () { return actor_1.createAndRunCrawleeOne; } });
+Object.defineProperty(exports, "createHttpCrawlerOptions", { enumerable: true, get: function () { return actor_1.createHttpCrawlerOptions; } });
+__exportStar(require("./lib/actor/types"), exports);
+__exportStar(require("./lib/actorSpec"), exports);
+__exportStar(require("./lib/config"), exports);
+__exportStar(require("./lib/io/dataset"), exports);
+__exportStar(require("./lib/io/requestQueue"), exports);
+__exportStar(require("./lib/io/pushData"), exports);
+__exportStar(require("./lib/io/pushRequests"), exports);
+__exportStar(require("./lib/actions/dom"), exports);
+__exportStar(require("./lib/actions/domUtils"), exports);
+__exportStar(require("./lib/actions/page"), exports);
+__exportStar(require("./lib/actions/scrapeListing"), exports);
+__exportStar(require("./lib/error/errorHandler"), exports);
+__exportStar(require("./lib/error/sentry"), exports);
+__exportStar(require("./lib/migrate/localMigrator"), exports);
+__exportStar(require("./lib/migrate/localState"), exports);
+__exportStar(require("./lib/migrate/types"), exports);
+__exportStar(require("./lib/readme/readme"), exports);
+__exportStar(require("./lib/readme/types"), exports);
+__exportStar(require("./lib/router"), exports);
+__exportStar(require("./lib/log"), exports);
+__exportStar(require("./lib/test/actor"), exports);
+__exportStar(require("./lib/test/mockApifyClient"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,2CAAqF;AAA5E,+GAAA,sBAAsB,OAAA;AAAE,iHAAA,wBAAwB,OAAA;AACzD,oDAAkC;AAClC,kDAAgC;AAChC,+CAA6B;AAC7B,mDAAiC;AACjC,wDAAsC;AACtC,oDAAkC;AAClC,wDAAsC;AACtC,oDAAkC;AAClC,yDAAuC;AACvC,qDAAmC;AACnC,8DAA4C;AAC5C,2DAAyC;AACzC,qDAAmC;AACnC,8DAA4C;AAC5C,2DAAyC;AACzC,sDAAoC;AACpC,sDAAoC;AACpC,qDAAmC;AACnC,+CAA6B;AAC7B,4CAA0B;AAC1B,mDAAiC;AACjC,6DAA2C","sourcesContent":["export { createAndRunCrawleeOne, createHttpCrawlerOptions } from './lib/actor/actor';\nexport * from './lib/actor/types';\nexport * from './lib/actorSpec';\nexport * from './lib/config';\nexport * from './lib/io/dataset';\nexport * from './lib/io/requestQueue';\nexport * from './lib/io/pushData';\nexport * from './lib/io/pushRequests';\nexport * from './lib/actions/dom';\nexport * from './lib/actions/domUtils';\nexport * from './lib/actions/page';\nexport * from './lib/actions/scrapeListing';\nexport * from './lib/error/errorHandler';\nexport * from './lib/error/sentry';\nexport * from './lib/migrate/localMigrator';\nexport * from './lib/migrate/localState';\nexport * from './lib/migrate/types';\nexport * from './lib/readme/readme';\nexport * from './lib/readme/types';\nexport * from './lib/router';\nexport * from './lib/log';\nexport * from './lib/test/actor';\nexport * from './lib/test/mockApifyClient';\nexport type { CrawlerUrl, CrawlerType } from './types';\n"]}

package/dist/cjs/lib/actions/dom.d.ts

@@ -0,0 +1,102 @@
+import { AnyNode, Cheerio } from 'cheerio';
+import type { ElementHandle, Locator, Page } from 'playwright';
+import { StrAsNumOptions } from '../../utils/format';
+import { FormatUrlOptions } from '../../utils/url';
+import type { MaybeArray, MaybePromise } from '../../utils/types';
+/**
+ * Common interface for working with DOM despite different environments.
+ *
+ * Consider these environments:
+ * 1) Browser (via Playwright & Chromium) - uses Browser API to work with DOM
+ * 2) Cheerio - uses own API to work with DOM
+ *
+ * This common interfaces makes the scraping code more portable between the two.
+ */
+export interface DOMLib<El extends BaseEl, BaseEl> {
+    node: El | null;
+    /** Get element's text (trimmed) */
+    text: (options?: {
+        allowEmpty?: boolean;
+    }) => MaybePromise<string | null>;
+    /** Get element's text as uppercase (trimmed) */
+    textAsUpper: (options?: {
+        allowEmpty?: boolean;
+    }) => MaybePromise<string | null>;
+    /** Get element's text as lowercase (trimmed) */
+    textAsLower: (options?: {
+        allowEmpty?: boolean;
+    }) => MaybePromise<string | null>;
+    /** Get element's text and convert it to number */
+    textAsNumber: (options?: StrAsNumOptions) => MaybePromise<number | null>;
+    /** Get element's attribute */
+    attr: (attrName: string, options?: {
+        allowEmpty?: boolean;
+    }) => MaybePromise<string | null>;
+    /** Get element's attributes */
+    attrs: <T extends string>(attrNames: T[], options?: {
+        allowEmpty?: boolean;
+    }) => MaybePromise<Record<T, string | null>>;
+    /** Get element's property */
+    prop: <R = unknown>(
+    /** Single or nested prop path */
+    propName: MaybeArray<string>, options?: {
+        allowEmpty?: boolean;
+    }) => MaybePromise<R>;
+    /** Get element's properties */
+    props: <R extends any[]>(
+    /** List of single or nested prop paths */
+    propName: MaybeArray<string>[], options?: {
+        allowEmpty?: boolean;
+    }) => MaybePromise<R>;
+    /** Get element's href */
+    href: (options?: {
+        allowEmpty?: boolean;
+    } & FormatUrlOptions) => MaybePromise<string | null>;
+    /** Get element's src */
+    src: (options?: {
+        allowEmpty?: boolean;
+    } & FormatUrlOptions) => MaybePromise<string | null>;
+    /** Get element's nodeName */
+    nodeName: () => MaybePromise<string | null>;
+    /** Get URL of website associated with the DOM */
+    url: () => MaybePromise<string | null>;
+    /** Freely modify the underlying DOM node */
+    map: <TVal>(map: (node: El | null) => TVal) => MaybePromise<TVal>;
+    /** Get a single descendant matching the selector */
+    findOne: <TNewEl extends BaseEl = El>(selector: string) => MaybePromise<DOMLib<TNewEl, BaseEl> | null>;
+    /** Get all descendants matching the selector */
+    findMany: <TNewEl extends BaseEl = El>(selector: string) => MaybePromise<DOMLib<TNewEl, BaseEl>[]>;
+    /** Get a single ancestor (or itself) matching the selector */
+    closest: <TNewEl extends BaseEl = El>(selector: string) => MaybePromise<DOMLib<TNewEl, BaseEl> | null>;
+    /** Get element's parent */
+    parent: <TNewEl extends BaseEl = El>() => MaybePromise<DOMLib<TNewEl, BaseEl> | null>;
+    /** Get element's children */
+    children: <TNewEl extends BaseEl = El>() => MaybePromise<DOMLib<TNewEl, BaseEl>[]>;
+    /** Get remove the element */
+    remove: () => MaybePromise<void>;
+    /** Get root element */
+    root: <TNewEl extends BaseEl = El>() => MaybePromise<DOMLib<TNewEl, BaseEl> | null>;
+    /**
+     * Given two elements, return closest ancestor element that encompases them both,
+     * or `null` if none such found.
+     */
+    getCommonAncestor: <TNewEl extends BaseEl = El>(otherEl: El) => MaybePromise<DOMLib<TNewEl, BaseEl> | null>;
+    /**
+     * Given a selector, find all DOM elements that match the selector,
+     * and return closest ancestor element that encompases them all,
+     * or `null` if none such found.
+     */
+    getCommonAncestorFromSelector: <TNewEl extends BaseEl = El>(selector: string) => MaybePromise<DOMLib<TNewEl, BaseEl> | null>;
+}
+export type BrowserDOMLib<T extends Element = Element> = DOMLib<T, Element>;
+/** Implementation of DOMLib in browser (using Browser API) */
+export declare const browserDOMLib: <El extends Element>(node: El) => BrowserDOMLib<El>;
+export type CheerioDOMLib<El extends Cheerio<AnyNode> = Cheerio<AnyNode>> = DOMLib<El, Cheerio<AnyNode>>;
+/** Implementation of DOMLib in Cheerio */
+export declare const cheerioDOMLib: <El extends Cheerio<AnyNode>>(cheerioNode: El, srcUrl: string | null) => CheerioDOMLib<El>;
+export type PlaywrightHandleDOMLib<El extends Locator | ElementHandle<Node> = Locator | ElementHandle<Node>> = DOMLib<El, Locator | ElementHandle<Node>>;
+/** Implementation of DOMLib in Playwright using Handles */
+export declare const playwrightHandleDOMLib: <El extends ElementHandle<Node> | Locator>(node: El, page: Page) => PlaywrightHandleDOMLib<El>;
+export type PlaywrightLocatorDOMLib<El extends Locator = Locator> = DOMLib<El, Locator>;
+/** Implementation of DOMLib in Playwright using Locators */
+export declare const playwrightLocatorDOMLib: <El extends Locator>(node: El, page: Page) => PlaywrightLocatorDOMLib<El>;