crawlee-one 1.0.0

package/dist/cjs/lib/dataset.d.ts

@@ -0,0 +1,98 @@
+import type { CrawlingContext } from 'crawlee';
+export interface ActorEntryMetadata {
+    actorId: string | null;
+    actorRunId: string | null;
+    actorRunUrl: string | null;
+    contextId: string;
+    requestId: string | null;
+    /** The URL given to the crawler */
+    originalUrl: string | null;
+    /** The URL given to the crawler after possible redirects */
+    loadedUrl: string | null;
+    /** ISO datetime string that indicates the time when the request has been processed. */
+    dateHandled: string;
+    numberOfRetries: number;
+}
+/** Add metadata to the object */
+export type WithActorEntryMetadata<T> = T & {
+    metadata: ActorEntryMetadata;
+};
+/** Functions that generates a "redacted" version of a value */
+export type PrivateValueGen<V, K, O> = (val: V, key: K, obj: O) => any;
+/**
+ * Given a property value (and its position) this function
+ * determines if the property is considered private (and
+ * hence should be hidden for privacy reasons).
+ *
+ * Property is private if the function returns truthy value.
+ */
+export type PrivacyFilter<V, K, O> = (val: V, key: K, obj: O, options?: {
+    setCustomPrivateValue: (val: V) => any;
+    privateValueGen: PrivateValueGen<V, K, O>;
+}) => any;
+/**
+ * PrivacyMask determines which (potentally nested) properties
+ * of an object are considered private.
+ *
+ * PrivacyMask copies the structure of another object, but each
+ * non-object property on PrivacyMask is a PrivacyFilter - function
+ * that determines if the property is considered private.
+ *
+ * Property is private if the function returns truthy value.
+ */
+export type PrivacyMask<T extends object> = {
+    [Key in keyof T]?: T[Key] extends Date | any[] ? PrivacyFilter<T[Key], Key, T> : T[Key] extends object ? PrivacyMask<T[Key]> : PrivacyFilter<T[Key], Key, T>;
+};
+export interface PushDataOptions<T extends object> {
+    /**
+     * Whether items should be enriched with request and run metadata.
+     *
+     * If truthy, the metadata is set under the `metadata` property.
+     */
+    includeMetadata?: boolean;
+    /**
+     * Whether properties that are considered personal data should be shown as is.
+     *
+     * If falsy or not set, these properties are redacted to hide the actual information.
+     *
+     * Which properties are personal data is determined by `privacyMask`.
+     */
+    showPrivate?: boolean;
+    /**
+     * Determine which properties are considered personal data.
+     *
+     * See {@link PrivacyMask}.
+     **/
+    privacyMask: PrivacyMask<T>;
+    /**
+     * Option to select which keys (fields) of an entry to keep (discarding the rest)
+     * before pushing the entries to the dataset.
+     *
+     * This serves mainly to allow users to select the keys from actor input UI.
+     *
+     * This is done before `remapKeys`.
+     *
+     * Keys can be nested, e.g. `"someProp.value[0]"`. Nested path is
+     * resolved using Lodash.get().
+     */
+    pickKeys?: string[];
+    /**
+     * Option to remap the keys before pushing the entries to the dataset.
+     *
+     * This serves mainly to allow users to remap the keys from actor input UI.
+     *
+     * Keys can be nested, e.g. `"someProp.value[0]"`. Nested path is
+     * resolved using Lodash.get().
+     */
+    remapKeys?: Record<string, string>;
+    /** ID or name of the dataset to which the data should be pushed */
+    datasetIdOrName?: string;
+}
+/**
+ * `Actor.pushData` with extra features:
+ *
+ * - (Optionally) Add metadata to entries before they are pushed to dataset.
+ * - (Optionally) Set which (nested) properties are personal data and allow to
+ * redact them for privacy compliance.
+ */
+export declare const pushData: <Ctx extends CrawlingContext<unknown, import("crawlee").Dictionary>, T extends Record<any, any> = Record<any, any>>(oneOrManyItems: T | T[], ctx: Ctx, options: PushDataOptions<T>) => Promise<Pick<T | WithActorEntryMetadata<Record<any, any>>, string>[]>;

package/dist/cjs/lib/dataset.js

@@ -0,0 +1,122 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushData = void 0;
+const apify_1 = require("apify");
+const lodash_1 = require("lodash");
+const createMetadataMapper = (ctx) => {
+    const { actorId, actorRunId } = apify_1.Actor.getEnv();
+    const actorRunUrl = actorId != null && actorRunId != null
+        ? `https://console.apify.com/actors/${actorId}/runs/${actorRunId}`
+        : null;
+    const handledAt = new Date().toISOString();
+    const addMetadataToData = (item) => {
+        var _a, _b, _c;
+        return (Object.assign(Object.assign({}, item), { metadata: {
+                actorId,
+                actorRunId,
+                actorRunUrl,
+                contextId: ctx.id,
+                requestId: (_a = ctx.request.id) !== null && _a !== void 0 ? _a : null,
+                originalUrl: (_b = ctx.request.url) !== null && _b !== void 0 ? _b : null,
+                loadedUrl: (_c = ctx.request.loadedUrl) !== null && _c !== void 0 ? _c : null,
+                dateHandled: ctx.request.handledAt || handledAt,
+                numberOfRetries: ctx.request.retryCount,
+            } }));
+    };
+    return addMetadataToData;
+};
+const applyPrivacyMask = (item, options) => {
+    const { showPrivate, privacyMask, privateValueGen = (_, key) => `<Redacted property "${key}">`, } = options;
+    const resolvePrivateValue = (key, val) => {
+        // Allow to set custom "redacted" value by calling
+        // `setCustomPrivateValue` from inside the filter function.
+        let customPrivateValue;
+        let setCustomPrivateValueCalled = false;
+        const setCustomPrivateValue = (val) => {
+            customPrivateValue = val;
+            setCustomPrivateValueCalled = true;
+        };
+        const privacyFilter = privacyMask[key];
+        const isPrivate = privacyFilter
+            ? privacyFilter(val, key, item, { setCustomPrivateValue, privateValueGen })
+            : false;
+        // prettier-ignore
+        const privateValue = (
+        // Don't redact anything if we're asked to show private data
+        showPrivate ? val
+            // Otherwise, if custom value was given, use that
+            : setCustomPrivateValueCalled ? customPrivateValue
+                // Otherwise, decide based on filter truthiness
+                : isPrivate ? privateValueGen(key, val, item) : val);
+        return privateValue;
+    };
+    const redactedObj = Object.entries(item).reduce((agg, [key, val]) => {
+        var _a;
+        const isNestedObj = typeof val === 'object' && val != null && !(val instanceof Date) && !Array.isArray(val);
+        if (isNestedObj) {
+            // Recursively process nested objects
+            const subObj = applyPrivacyMask(val, {
+                showPrivate,
+                privacyMask: ((_a = privacyMask[key]) !== null && _a !== void 0 ? _a : {}),
+                privateValueGen,
+            });
+            agg[key] = subObj;
+        }
+        else {
+            agg[key] = resolvePrivateValue(key, val);
+        }
+        return agg;
+    }, {});
+    return redactedObj;
+};
+/** Rename object properties in place */
+const renameKeys = (item, keyNameMap) => {
+    Object.entries(keyNameMap || {}).forEach(([oldPath, newPath]) => {
+        if (oldPath === newPath)
+            return;
+        const val = (0, lodash_1.get)(item, oldPath);
+        (0, lodash_1.set)(item, newPath, val);
+        (0, lodash_1.unset)(item, oldPath);
+    });
+    return item;
+};
+/**
+ * `Actor.pushData` with extra features:
+ *
+ * - (Optionally) Add metadata to entries before they are pushed to dataset.
+ * - (Optionally) Set which (nested) properties are personal data and allow to
+ * redact them for privacy compliance.
+ */
+const pushData = (oneOrManyItems, ctx, options) => __awaiter(void 0, void 0, void 0, function* () {
+    const { includeMetadata, showPrivate, privacyMask, remapKeys, pickKeys, datasetIdOrName } = options;
+    const items = Array.isArray(oneOrManyItems) ? oneOrManyItems : [oneOrManyItems];
+    ctx.log.debug(`Preparing entries before pushing ${items.length} items to dataset`); // prettier-ignore
+    const addMetadataToData = createMetadataMapper(ctx);
+    const adjustedItems = items.map((item) => {
+        const itemWithMetadata = includeMetadata ? addMetadataToData(item) : item;
+        const maskedItem = applyPrivacyMask(itemWithMetadata, {
+            showPrivate,
+            privacyMask,
+            privateValueGen: (val, key) => `<Redacted property "${key}". To include the actual value, toggle ON the Actor input option "Include personal data">`,
+        });
+        const pickedItem = pickKeys ? (0, lodash_1.pick)(maskedItem, pickKeys) : maskedItem;
+        const renamedItem = remapKeys ? renameKeys(pickedItem, remapKeys) : pickedItem;
+        return renamedItem;
+    });
+    ctx.log.info(`Pushing ${adjustedItems.length} entries to dataset`);
+    const dataset = datasetIdOrName ? yield apify_1.Actor.openDataset(datasetIdOrName) : apify_1.Actor;
+    yield dataset.pushData(adjustedItems);
+    ctx.log.info(`Done pushing ${adjustedItems.length} entries to dataset`);
+    return adjustedItems;
+});
+exports.pushData = pushData;
+//# sourceMappingURL=dataset.js.map

package/dist/cjs/lib/dataset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../../../src/lib/dataset.ts"],"names":[],"mappings":"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","sourcesContent":["import { Actor } from 'apify';\nimport type { CrawlingContext } from 'crawlee';\nimport { get, pick, set, unset } from 'lodash';\n\nexport interface ActorEntryMetadata {\n  actorId: string | null;\n  actorRunId: string | null;\n  actorRunUrl: string | null;\n  contextId: string;\n  requestId: string | null;\n\n  /** The URL given to the crawler */\n  originalUrl: string | null;\n  /** The URL given to the crawler after possible redirects */\n  loadedUrl: string | null;\n\n  /** ISO datetime string that indicates the time when the request has been processed. */\n  dateHandled: string;\n  numberOfRetries: number;\n}\n\n/** Add metadata to the object */\nexport type WithActorEntryMetadata<T> = T & { metadata: ActorEntryMetadata };\n\n/** Functions that generates a \"redacted\" version of a value */\nexport type PrivateValueGen<V, K, O> = (val: V, key: K, obj: O) => any;\n\n/**\n * Given a property value (and its position) this function\n * determines if the property is considered private (and\n * hence should be hidden for privacy reasons).\n *\n * Property is private if the function returns truthy value.\n */\nexport type PrivacyFilter<V, K, O> = (\n  val: V,\n  key: K,\n  obj: O,\n  options?: {\n    setCustomPrivateValue: (val: V) => any;\n    privateValueGen: PrivateValueGen<V, K, O>;\n  }\n) => any;\n\n/**\n * PrivacyMask determines which (potentally nested) properties\n * of an object are considered private.\n *\n * PrivacyMask copies the structure of another object, but each\n * non-object property on PrivacyMask is a PrivacyFilter - function\n * that determines if the property is considered private.\n *\n * Property is private if the function returns truthy value.\n */\nexport type PrivacyMask<T extends object> = {\n  [Key in keyof T]?: T[Key] extends Date | any[] // Consider Data and Array as non-objects\n    ? PrivacyFilter<T[Key], Key, T>\n    : T[Key] extends object\n    ? PrivacyMask<T[Key]>\n    : PrivacyFilter<T[Key], Key, T>;\n};\n\nexport interface PushDataOptions<T extends object> {\n  /**\n   * Whether items should be enriched with request and run metadata.\n   *\n   * If truthy, the metadata is set under the `metadata` property.\n   */\n  includeMetadata?: boolean;\n  /**\n   * Whether properties that are considered personal data should be shown as is.\n   *\n   * If falsy or not set, these properties are redacted to hide the actual information.\n   *\n   * Which properties are personal data is determined by `privacyMask`.\n   */\n  showPrivate?: boolean;\n  /**\n   * Determine which properties are considered personal data.\n   *\n   * See {@link PrivacyMask}.\n   **/\n  privacyMask: PrivacyMask<T>;\n  /**\n   * Option to select which keys (fields) of an entry to keep (discarding the rest)\n   * before pushing the entries to the dataset.\n   *\n   * This serves mainly to allow users to select the keys from actor input UI.\n   *\n   * This is done before `remapKeys`.\n   *\n   * Keys can be nested, e.g. `\"someProp.value[0]\"`. Nested path is\n   * resolved using Lodash.get().\n   */\n  pickKeys?: string[];\n  /**\n   * Option to remap the keys before pushing the entries to the dataset.\n   *\n   * This serves mainly to allow users to remap the keys from actor input UI.\n   *\n   * Keys can be nested, e.g. `\"someProp.value[0]\"`. Nested path is\n   * resolved using Lodash.get().\n   */\n  remapKeys?: Record<string, string>;\n  /** ID or name of the dataset to which the data should be pushed */\n  datasetIdOrName?: string;\n}\n\nconst createMetadataMapper = <Ctx extends CrawlingContext>(ctx: Ctx) => {\n  const { actorId, actorRunId } = Actor.getEnv();\n  const actorRunUrl =\n    actorId != null && actorRunId != null\n      ? `https://console.apify.com/actors/${actorId}/runs/${actorRunId}`\n      : null;\n  const handledAt = new Date().toISOString();\n\n  const addMetadataToData = <T extends Record<any, any> = Record<any, any>>(\n    item\n  ): WithActorEntryMetadata<T> => ({\n    ...item,\n    metadata: {\n      actorId,\n      actorRunId,\n      actorRunUrl,\n      contextId: ctx.id,\n      requestId: ctx.request.id ?? null,\n\n      originalUrl: ctx.request.url ?? null,\n      loadedUrl: ctx.request.loadedUrl ?? null,\n\n      dateHandled: ctx.request.handledAt || handledAt,\n      numberOfRetries: ctx.request.retryCount,\n    },\n  });\n  return addMetadataToData;\n};\n\nconst applyPrivacyMask = <T extends Record<any, any> = Record<any, any>>(\n  item: T,\n  options: {\n    showPrivate?: boolean;\n    privacyMask: PrivacyMask<T>;\n    privateValueGen?: (val: any, key: string, item: T) => any;\n  }\n) => {\n  const {\n    showPrivate,\n    privacyMask,\n    privateValueGen = (_, key) => `<Redacted property \"${key}\">`,\n  } = options;\n\n  const resolvePrivateValue = (key: string, val: any) => {\n    // Allow to set custom \"redacted\" value by calling\n    // `setCustomPrivateValue` from inside the filter function.\n    let customPrivateValue;\n    let setCustomPrivateValueCalled = false;\n    const setCustomPrivateValue = (val: any) => {\n      customPrivateValue = val;\n      setCustomPrivateValueCalled = true;\n    };\n\n    const privacyFilter = privacyMask[key] as PrivacyFilter<any, any, any> | undefined;\n    const isPrivate = privacyFilter\n      ? privacyFilter(val, key, item, { setCustomPrivateValue, privateValueGen })\n      : false;\n\n    // prettier-ignore\n    const privateValue = (\n      // Don't redact anything if we're asked to show private data\n      showPrivate ? val\n      // Otherwise, if custom value was given, use that\n      : setCustomPrivateValueCalled ? customPrivateValue\n      // Otherwise, decide based on filter truthiness\n      : isPrivate ? privateValueGen(key, val, item) : val\n    );\n    return privateValue;\n  };\n\n  const redactedObj = Object.entries(item).reduce((agg, [key, val]) => {\n    const isNestedObj =\n      typeof val === 'object' && val != null && !(val instanceof Date) && !Array.isArray(val);\n\n    if (isNestedObj) {\n      // Recursively process nested objects\n      const subObj = applyPrivacyMask(val, {\n        showPrivate,\n        privacyMask: (privacyMask[key] ?? {}) as any,\n        privateValueGen,\n      });\n      agg[key as keyof T] = subObj as any;\n    } else {\n      agg[key as keyof T] = resolvePrivateValue(key, val);\n    }\n    return agg;\n  }, {} as T);\n\n  return redactedObj;\n};\n\n/** Rename object properties in place */\nconst renameKeys = <T extends object>(item: T, keyNameMap: Partial<Record<keyof T, string>>) => {\n  Object.entries(keyNameMap || {}).forEach(([oldPath, newPath]) => {\n    if (oldPath === newPath) return;\n    const val = get(item, oldPath);\n    set(item, newPath as string, val);\n    unset(item, oldPath);\n  });\n  return item;\n};\n\n/**\n * `Actor.pushData` with extra features:\n *\n * - (Optionally) Add metadata to entries before they are pushed to dataset.\n * - (Optionally) Set which (nested) properties are personal data and allow to\n * redact them for privacy compliance.\n */\nexport const pushData = async <\n  Ctx extends CrawlingContext,\n  T extends Record<any, any> = Record<any, any>\n>(\n  oneOrManyItems: T | T[],\n  ctx: Ctx,\n  options: PushDataOptions<T>\n) => {\n  const { includeMetadata, showPrivate, privacyMask, remapKeys, pickKeys, datasetIdOrName } =\n    options;\n\n  const items = Array.isArray(oneOrManyItems) ? oneOrManyItems : [oneOrManyItems];\n\n  ctx.log.debug(`Preparing entries before pushing ${items.length} items to dataset`); // prettier-ignore\n  const addMetadataToData = createMetadataMapper(ctx);\n  const adjustedItems = items.map((item) => {\n    const itemWithMetadata = includeMetadata ? addMetadataToData(item) : item;\n    const maskedItem = applyPrivacyMask(itemWithMetadata, {\n      showPrivate,\n      privacyMask,\n      privateValueGen: (val, key) =>\n        `<Redacted property \"${key}\". To include the actual value, toggle ON the Actor input option \"Include personal data\">`,\n    });\n\n    const pickedItem = pickKeys ? pick(maskedItem, pickKeys) : maskedItem;\n    const renamedItem = remapKeys ? renameKeys(pickedItem, remapKeys) : pickedItem;\n\n    return renamedItem;\n  });\n\n  ctx.log.info(`Pushing ${adjustedItems.length} entries to dataset`);\n  const dataset = datasetIdOrName ? await Actor.openDataset(datasetIdOrName) : Actor;\n  await dataset.pushData(adjustedItems);\n  ctx.log.info(`Done pushing ${adjustedItems.length} entries to dataset`);\n\n  return adjustedItems;\n};\n"]}

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

@@ -0,0 +1,78 @@
+import { AnyNode, Cheerio } from 'cheerio';
+import { StrAsNumOptions } from '../utils/format';
+import { FormatUrlOptions } from '../utils/url';
+/**
+ * Common interface for work 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;
+    }) => string | null;
+    /** Get element's text as uppercase (trimmed) */
+    textAsUpper: (options?: {
+        allowEmpty?: boolean;
+    }) => string | null;
+    /** Get element's text as lowercase (trimmed) */
+    textAsLower: (options?: {
+        allowEmpty?: boolean;
+    }) => string | null;
+    /** Get element's text and convert it to number */
+    textAsNumber: (options?: StrAsNumOptions) => number | null;
+    /** Get element's attribute */
+    attr: (attrName: string, options?: {
+        allowEmpty?: boolean;
+    }) => string | null;
+    /** Get element's property */
+    prop: (propName: string, options?: {
+        allowEmpty?: boolean;
+    }) => string | null;
+    /** Get element's href */
+    href: (options?: {
+        allowEmpty?: boolean;
+    } & FormatUrlOptions) => string | null;
+    /** Get element's src */
+    src: (options?: {
+        allowEmpty?: boolean;
+    } & FormatUrlOptions) => string | null;
+    /** Get element's nodeName */
+    nodeName: () => string | null;
+    /** Get URL of website associated with the DOM */
+    url: () => string | null;
+    /** Freely modify the underlying DOM node */
+    map: <TVal>(map: (node: El | null) => TVal) => TVal;
+    /** Get a single descendant matching the selector */
+    findOne: <TNewEl extends BaseEl = El>(selector: string) => DOMLib<TNewEl, BaseEl> | null;
+    /** Get all descendants matching the selector */
+    findMany: <TNewEl extends BaseEl = El>(selector: string) => DOMLib<TNewEl, BaseEl>[];
+    /** Get element's parent */
+    parent: <TNewEl extends BaseEl = El>() => DOMLib<TNewEl, BaseEl> | null;
+    /** Get element's children */
+    children: <TNewEl extends BaseEl = El>() => DOMLib<TNewEl, BaseEl>[];
+    /** Get remove the element */
+    remove: () => void;
+    /** Get root element */
+    root: <TNewEl extends BaseEl = El>() => 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: <T extends Element>(node: T) => BrowserDOMLib<T>;
+export type CheerioDOMLib<T extends Cheerio<AnyNode> = Cheerio<AnyNode>> = DOMLib<T, Cheerio<AnyNode>>;
+/**
+ * Given a Cheerio selection, split it into an array of Cheerio selections,
+ * where each has only one element.
+ *
+ * From `Cheerio[el, el, el, el]`
+ *
+ * To `[Cheerio[el], Cheerio[el], Cheerio[el], Cheerio[el]]`
+ */
+export declare const splitCheerioSelection: (cheerioSel: Cheerio<AnyNode>) => Cheerio<import("cheerio").Document | import("cheerio").Element | import("domhandler").CDATA | import("domhandler").Text | import("domhandler").Comment | import("domhandler").ProcessingInstruction>[];
+/** Implementation of DOMLib in Cheerio */
+export declare const cheerioDOMLib: <T extends Cheerio<AnyNode>>(cheerioNode: T, srcUrl: string | null) => CheerioDOMLib<T>;

package/dist/cjs/lib/dom.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cheerioDOMLib = exports.splitCheerioSelection = exports.browserDOMLib = void 0;
+const cheerio_1 = require("cheerio");
+const format_1 = require("../utils/format");
+const url_1 = require("../utils/url");
+/** Implementation of DOMLib in browser (using Browser API) */
+const browserDOMLib = (node) => {
+    ///////////////////////
+    // SCALAR OPERATIONS
+    ///////////////////////
+    const text = ({ allowEmpty } = {}) => {
+        var _a, _b;
+        const txt = (_b = (_a = node.textContent) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : null;
+        return (0, format_1.strOrNull)(txt, allowEmpty);
+    };
+    const textAsUpper = (options) => {
+        const txt = text(options);
+        return txt ? txt.toLocaleUpperCase() : txt;
+    };
+    const textAsLower = (options) => {
+        const txt = text(options);
+        return txt ? txt.toLocaleLowerCase() : txt;
+    };
+    const textAsNumber = (options) => {
+        const txt = text(options);
+        return (0, format_1.strAsNumber)(txt, options);
+    };
+    const prop = (propName, { allowEmpty } = {}) => {
+        var _a;
+        let propVal = (_a = node[propName]) !== null && _a !== void 0 ? _a : null;
+        propVal = typeof propVal === 'string' ? propVal.trim() : propVal;
+        return (0, format_1.strOrNull)(propVal, allowEmpty);
+    };
+    const attr = (propName, { allowEmpty } = {}) => {
+        var _a;
+        let attrVal = (_a = node.getAttribute(propName)) !== null && _a !== void 0 ? _a : null;
+        attrVal = typeof attrVal === 'string' ? attrVal.trim() : attrVal;
+        return (0, format_1.strOrNull)(attrVal, allowEmpty);
+    };
+    const href = ({ allowEmpty, allowRelative, baseUrl } = {}) => {
+        const val = prop('href', { allowEmpty });
+        return (0, url_1.formatUrl)(val, { allowRelative, baseUrl });
+    };
+    const src = ({ allowEmpty, allowRelative, baseUrl } = {}) => {
+        const val = prop('src', { allowEmpty });
+        return (0, url_1.formatUrl)(val, { allowRelative, baseUrl });
+    };
+    const nodeName = () => {
+        // On UPPER- vs lower-case https://stackoverflow.com/questions/27223756/
+        const val = prop('nodeName');
+        return typeof val === 'string' ? val.toLocaleUpperCase() : val;
+    };
+    const url = () => {
+        var _a, _b;
+        const doc = node.ownerDocument;
+        // See https://stackoverflow.com/a/16010322/9788634
+        const urlVal = ((_b = (_a = doc.defaultView) === null || _a === void 0 ? void 0 : _a.location) === null || _b === void 0 ? void 0 : _b.href) || null;
+        return urlVal;
+    };
+    const map = (mapFn) => {
+        return mapFn(node);
+    };
+    ///////////////////////
+    // NODE OPERATIONS
+    ///////////////////////
+    const findOne = (selector) => {
+        var _a;
+        if (![Node.ELEMENT_NODE, Node.DOCUMENT_NODE].includes(node.nodeType))
+            return null;
+        const resultEl = ((_a = node.querySelector(selector)) !== null && _a !== void 0 ? _a : null);
+        return resultEl ? (0, exports.browserDOMLib)(resultEl) : null;
+    };
+    const findMany = (selector) => {
+        if (![Node.ELEMENT_NODE, Node.DOCUMENT_NODE].includes(node.nodeType))
+            return [];
+        const resultEls = [...node.querySelectorAll(selector)]; // prettier-ignore
+        return resultEls.map((el) => (0, exports.browserDOMLib)(el));
+    };
+    const parent = () => {
+        const parentEl = (node.parentNode || null);
+        return parentEl ? (0, exports.browserDOMLib)(parentEl) : null;
+    };
+    const children = () => {
+        const childEls = [...node.childNodes];
+        return childEls.map((el) => (0, exports.browserDOMLib)(el));
+    };
+    const root = () => {
+        var _a;
+        const rootEl = (((_a = node.ownerDocument) === null || _a === void 0 ? void 0 : _a.documentElement) || null);
+        return rootEl ? (0, exports.browserDOMLib)(rootEl) : null;
+    };
+    const remove = () => {
+        var _a;
+        const parentEl = parent();
+        (_a = parentEl === null || parentEl === void 0 ? void 0 : parentEl.node) === null || _a === void 0 ? void 0 : _a.removeChild(node);
+    };
+    return {
+        node,
+        text,
+        textAsLower,
+        textAsUpper,
+        textAsNumber,
+        attr,
+        prop,
+        href,
+        src,
+        nodeName,
+        url,
+        map,
+        findOne,
+        findMany,
+        parent,
+        children,
+        root,
+        remove,
+    };
+};
+exports.browserDOMLib = browserDOMLib;
+/**
+ * Given a Cheerio selection, split it into an array of Cheerio selections,
+ * where each has only one element.
+ *
+ * From `Cheerio[el, el, el, el]`
+ *
+ * To `[Cheerio[el], Cheerio[el], Cheerio[el], Cheerio[el]]`
+ */
+const splitCheerioSelection = (cheerioSel) => {
+    return cheerioSel.toArray().map((el) => {
+        const cheerioInst = (0, cheerio_1.load)(el);
+        return cheerioInst(el);
+    });
+};
+exports.splitCheerioSelection = splitCheerioSelection;
+/** Implementation of DOMLib in Cheerio */
+const cheerioDOMLib = (cheerioNode, srcUrl) => {
+    ///////////////////////
+    // SCALAR OPERATIONS
+    ///////////////////////
+    const text = ({ allowEmpty } = {}) => {
+        var _a, _b;
+        const txt = (_b = (_a = cheerioNode.text()) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : null;
+        return (0, format_1.strOrNull)(txt, allowEmpty);
+    };
+    const textAsUpper = (options) => {
+        const txt = text(options);
+        return txt ? txt.toLocaleUpperCase() : txt;
+    };
+    const textAsLower = (options) => {
+        const txt = text(options);
+        return txt ? txt.toLocaleLowerCase() : txt;
+    };
+    const textAsNumber = (options) => {
+        const txt = text(options);
+        return (0, format_1.strAsNumber)(txt, options);
+    };
+    const attr = (attrName, { allowEmpty } = {}) => {
+        var _a;
+        let attrVal = (_a = cheerioNode.attr(attrName)) !== null && _a !== void 0 ? _a : null;
+        attrVal = typeof attrVal === 'string' ? attrVal.trim() : attrVal;
+        return (0, format_1.strOrNull)(attrVal, allowEmpty);
+    };
+    const prop = (propName, { allowEmpty } = {}) => {
+        var _a;
+        let propVal = (_a = cheerioNode.prop(propName)) !== null && _a !== void 0 ? _a : null;
+        propVal = typeof propVal === 'string' ? propVal.trim() : propVal;
+        return (0, format_1.strOrNull)(propVal, allowEmpty);
+    };
+    const href = ({ allowEmpty, allowRelative, baseUrl } = {}) => {
+        const val = prop('href', { allowEmpty });
+        return (0, url_1.formatUrl)(val, { allowRelative, baseUrl });
+    };
+    const src = ({ allowEmpty, allowRelative, baseUrl } = {}) => {
+        const val = prop('src', { allowEmpty });
+        return (0, url_1.formatUrl)(val, { allowRelative, baseUrl });
+    };
+    const nodeName = () => {
+        // On UPPER- vs lower-case https://stackoverflow.com/questions/27223756/
+        const val = prop('nodeName');
+        return typeof val === 'string' ? val.toLocaleUpperCase() : val;
+    };
+    const url = () => {
+        return srcUrl !== null && srcUrl !== void 0 ? srcUrl : null;
+    };
+    const map = (mapFn) => {
+        return mapFn(cheerioNode);
+    };
+    ///////////////////////
+    // NODE OPERATIONS
+    ///////////////////////
+    const findOne = (selector) => {
+        const resultEl = cheerioNode.find(selector).first();
+        if (!resultEl.get(0))
+            return null;
+        return (0, exports.cheerioDOMLib)(resultEl, srcUrl);
+    };
+    const findMany = (selector) => {
+        const resultEls = (0, exports.splitCheerioSelection)(cheerioNode.find(selector));
+        return resultEls.map((ch) => (0, exports.cheerioDOMLib)(ch, srcUrl));
+    };
+    const parent = () => {
+        const parentEl = cheerioNode.parent().first();
+        if (!parentEl.get(0))
+            return null;
+        return (0, exports.cheerioDOMLib)(parentEl, srcUrl);
+    };
+    const children = () => {
+        const childEls = (0, exports.splitCheerioSelection)(cheerioNode.children());
+        return childEls.map((ch) => (0, exports.cheerioDOMLib)(ch, srcUrl));
+    };
+    const root = () => {
+        var _a;
+        const rootEl = (_a = cheerioNode._root) === null || _a === void 0 ? void 0 : _a.first();
+        if (!(rootEl === null || rootEl === void 0 ? void 0 : rootEl.get(0)))
+            return null;
+        return (0, exports.cheerioDOMLib)(rootEl, srcUrl);
+    };
+    const remove = () => {
+        cheerioNode.remove();
+    };
+    return {
+        node: cheerioNode,
+        text,
+        textAsLower,
+        textAsUpper,
+        textAsNumber,
+        attr,
+        prop,
+        href,
+        src,
+        nodeName,
+        url,
+        map,
+        findOne,
+        findMany,
+        parent,
+        children,
+        root,
+        remove,
+    };
+};
+exports.cheerioDOMLib = cheerioDOMLib;
+//# sourceMappingURL=dom.js.map

package/dist/cjs/lib/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../../src/lib/dom.ts"],"names":[],"mappings":"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","sourcesContent":["import { load as loadCheerio, AnyNode, Cheerio } from 'cheerio';\n\nimport { StrAsNumOptions, strAsNumber, strOrNull } from '../utils/format';\nimport { FormatUrlOptions, formatUrl } from '../utils/url';\n\n/**\n * Common interface for work working with DOM despite different environments.\n *\n * Consider these environments:\n * 1) Browser (via Playwright & Chromium) - uses Browser API to work with DOM\n * 2) Cheerio - uses own API to work with DOM\n *\n * This common interfaces makes the scraping code more portable between the two.\n */\nexport interface DOMLib<El extends BaseEl, BaseEl> {\n  node: El | null;\n\n  ///////////////////////\n  // SCALAR OPERATIONS\n  ///////////////////////\n\n  /** Get element's text (trimmed) */\n  text: (options?: { allowEmpty?: boolean }) => string | null;\n  /** Get element's text as uppercase (trimmed) */\n  textAsUpper: (options?: { allowEmpty?: boolean }) => string | null;\n  /** Get element's text as lowercase (trimmed) */\n  textAsLower: (options?: { allowEmpty?: boolean }) => string | null;\n  /** Get element's text and convert it to number */\n  textAsNumber: (options?: StrAsNumOptions) => number | null;\n  /** Get element's attribute */\n  attr: (attrName: string, options?: { allowEmpty?: boolean }) => string | null;\n  /** Get element's property */\n  prop: (propName: string, options?: { allowEmpty?: boolean }) => string | null;\n  /** Get element's href */\n  href: (options?: { allowEmpty?: boolean } & FormatUrlOptions) => string | null;\n  /** Get element's src */\n  src: (options?: { allowEmpty?: boolean } & FormatUrlOptions) => string | null;\n  /** Get element's nodeName */\n  nodeName: () => string | null;\n  /** Get URL of website associated with the DOM */\n  url: () => string | null;\n  /** Freely modify the underlying DOM node */\n  map: <TVal>(map: (node: El | null) => TVal) => TVal;\n\n  ///////////////////////\n  // NODE OPERATIONS\n  ///////////////////////\n\n  /** Get a single descendant matching the selector */\n  findOne: <TNewEl extends BaseEl = El>(selector: string) => DOMLib<TNewEl, BaseEl> | null;\n  /** Get all descendants matching the selector */\n  findMany: <TNewEl extends BaseEl = El>(selector: string) => DOMLib<TNewEl, BaseEl>[];\n  /** Get element's parent */\n  parent: <TNewEl extends BaseEl = El>() => DOMLib<TNewEl, BaseEl> | null;\n  /** Get element's children */\n  children: <TNewEl extends BaseEl = El>() => DOMLib<TNewEl, BaseEl>[];\n  /** Get remove the element */\n  remove: () => void;\n  /** Get root element */\n  root: <TNewEl extends BaseEl = El>() => DOMLib<TNewEl, BaseEl> | null;\n}\n\nexport type BrowserDOMLib<T extends Element = Element> = DOMLib<T, Element>;\n\n/** Implementation of DOMLib in browser (using Browser API) */\nexport const browserDOMLib = <T extends Element>(node: T): BrowserDOMLib<T> => {\n  ///////////////////////\n  // SCALAR OPERATIONS\n  ///////////////////////\n\n  const text: BrowserDOMLib<T>['text'] = ({ allowEmpty } = {}) => {\n    const txt = node.textContent?.trim() ?? null;\n    return strOrNull(txt, allowEmpty);\n  };\n\n  const textAsUpper: BrowserDOMLib<T>['textAsUpper'] = (options) => {\n    const txt = text(options);\n    return txt ? txt.toLocaleUpperCase() : txt;\n  };\n\n  const textAsLower: BrowserDOMLib<T>['textAsLower'] = (options) => {\n    const txt = text(options);\n    return txt ? txt.toLocaleLowerCase() : txt;\n  };\n\n  const textAsNumber: BrowserDOMLib<T>['textAsNumber'] = (options) => {\n    const txt = text(options);\n    return strAsNumber(txt, options);\n  };\n\n  const prop: BrowserDOMLib<T>['prop'] = (propName, { allowEmpty } = {}) => {\n    let propVal = node[propName] ?? null;\n    propVal = typeof propVal === 'string' ? propVal.trim() : propVal;\n    return strOrNull(propVal, allowEmpty);\n  };\n\n  const attr: BrowserDOMLib<T>['attr'] = (propName, { allowEmpty } = {}) => {\n    let attrVal = node.getAttribute(propName) ?? null;\n    attrVal = typeof attrVal === 'string' ? attrVal.trim() : attrVal;\n    return strOrNull(attrVal, allowEmpty);\n  };\n\n  const href: BrowserDOMLib<T>['href'] = ({ allowEmpty, allowRelative, baseUrl } = {}) => {\n    const val = prop('href', { allowEmpty });\n    return formatUrl(val, { allowRelative, baseUrl });\n  };\n\n  const src: BrowserDOMLib<T>['src'] = ({ allowEmpty, allowRelative, baseUrl } = {}) => {\n    const val = prop('src', { allowEmpty });\n    return formatUrl(val, { allowRelative, baseUrl });\n  };\n\n  const nodeName: BrowserDOMLib<T>['nodeName'] = () => {\n    // On UPPER- vs lower-case https://stackoverflow.com/questions/27223756/\n    const val = prop('nodeName');\n    return typeof val === 'string' ? val.toLocaleUpperCase() : val;\n  };\n\n  const url: BrowserDOMLib<T>['url'] = () => {\n    const doc = node.ownerDocument;\n    // See https://stackoverflow.com/a/16010322/9788634\n    const urlVal = doc.defaultView?.location?.href || null;\n    return urlVal;\n  };\n\n  const map: BrowserDOMLib<T>['map'] = <TVal>(mapFn: (node: T) => TVal) => {\n    return mapFn(node);\n  };\n\n  ///////////////////////\n  // NODE OPERATIONS\n  ///////////////////////\n\n  const findOne: BrowserDOMLib<T>['findOne'] = <TNewEl extends Element = T>(selector) => {\n    if (![Node.ELEMENT_NODE, Node.DOCUMENT_NODE].includes(node.nodeType as any)) return null;\n    const resultEl = (node.querySelector(selector) ?? null) as TNewEl | null;\n    return resultEl ? browserDOMLib(resultEl) : null;\n  };\n\n  const findMany: BrowserDOMLib<T>['findMany'] = <TNewEl extends Element = T>(selector) => {\n    if (![Node.ELEMENT_NODE, Node.DOCUMENT_NODE].includes(node.nodeType as any)) return [];\n    const resultEls = [...node.querySelectorAll(selector)] as TNewEl[]; // prettier-ignore\n    return resultEls.map((el) => browserDOMLib(el));\n  };\n\n  const parent: BrowserDOMLib<T>['parent'] = <TNewEl extends Element = T>() => {\n    const parentEl = (node.parentNode || null) as TNewEl | null;\n    return parentEl ? browserDOMLib(parentEl) : null;\n  };\n\n  const children: BrowserDOMLib<T>['children'] = <TNewEl extends Element = T>() => {\n    const childEls = [...node.childNodes] as TNewEl[];\n    return childEls.map((el) => browserDOMLib(el));\n  };\n\n  const root: BrowserDOMLib<T>['root'] = <TNewEl extends Element = T>() => {\n    const rootEl = ((node.ownerDocument?.documentElement as any) || null) as TNewEl | null;\n    return rootEl ? browserDOMLib(rootEl) : null;\n  };\n\n  const remove: BrowserDOMLib<T>['remove'] = () => {\n    const parentEl = parent();\n    parentEl?.node?.removeChild(node);\n  };\n\n  return {\n    node,\n\n    text,\n    textAsLower,\n    textAsUpper,\n    textAsNumber,\n    attr,\n    prop,\n    href,\n    src,\n    nodeName,\n    url,\n    map,\n\n    findOne,\n    findMany,\n    parent,\n    children,\n    root,\n    remove,\n  } satisfies DOMLib<T, Element>;\n};\n\nexport type CheerioDOMLib<T extends Cheerio<AnyNode> = Cheerio<AnyNode>> = DOMLib<\n  T,\n  Cheerio<AnyNode>\n>;\n\n/**\n * Given a Cheerio selection, split it into an array of Cheerio selections,\n * where each has only one element.\n *\n * From `Cheerio[el, el, el, el]`\n *\n * To `[Cheerio[el], Cheerio[el], Cheerio[el], Cheerio[el]]`\n */\nexport const splitCheerioSelection = (cheerioSel: Cheerio<AnyNode>) => {\n  return cheerioSel.toArray().map((el) => {\n    const cheerioInst = loadCheerio(el);\n    return cheerioInst(el);\n  });\n};\n\n/** Implementation of DOMLib in Cheerio */\nexport const cheerioDOMLib = <T extends Cheerio<AnyNode>>(\n  cheerioNode: T,\n  srcUrl: string | null\n): CheerioDOMLib<T> => {\n  ///////////////////////\n  // SCALAR OPERATIONS\n  ///////////////////////\n\n  const text: CheerioDOMLib<T>['text'] = ({ allowEmpty } = {}) => {\n    const txt = cheerioNode.text()?.trim() ?? null;\n    return strOrNull(txt, allowEmpty);\n  };\n\n  const textAsUpper: CheerioDOMLib<T>['textAsUpper'] = (options) => {\n    const txt = text(options);\n    return txt ? txt.toLocaleUpperCase() : txt;\n  };\n\n  const textAsLower: CheerioDOMLib<T>['textAsLower'] = (options) => {\n    const txt = text(options);\n    return txt ? txt.toLocaleLowerCase() : txt;\n  };\n\n  const textAsNumber: CheerioDOMLib<T>['textAsNumber'] = (options) => {\n    const txt = text(options);\n    return strAsNumber(txt, options);\n  };\n\n  const attr: CheerioDOMLib<T>['attr'] = (attrName, { allowEmpty } = {}) => {\n    let attrVal = cheerioNode.attr(attrName) ?? null;\n    attrVal = typeof attrVal === 'string' ? attrVal.trim() : attrVal;\n    return strOrNull(attrVal, allowEmpty);\n  };\n\n  const prop: CheerioDOMLib<T>['prop'] = (propName, { allowEmpty } = {}) => {\n    let propVal = cheerioNode.prop(propName) ?? null;\n    propVal = typeof propVal === 'string' ? propVal.trim() : propVal;\n    return strOrNull(propVal, allowEmpty);\n  };\n\n  const href: CheerioDOMLib<T>['href'] = ({ allowEmpty, allowRelative, baseUrl } = {}) => {\n    const val = prop('href', { allowEmpty });\n    return formatUrl(val, { allowRelative, baseUrl });\n  };\n\n  const src: CheerioDOMLib<T>['src'] = ({ allowEmpty, allowRelative, baseUrl } = {}) => {\n    const val = prop('src', { allowEmpty });\n    return formatUrl(val, { allowRelative, baseUrl });\n  };\n\n  const nodeName: CheerioDOMLib<T>['nodeName'] = () => {\n    // On UPPER- vs lower-case https://stackoverflow.com/questions/27223756/\n    const val = prop('nodeName');\n    return typeof val === 'string' ? val.toLocaleUpperCase() : val;\n  };\n\n  const url: CheerioDOMLib<T>['url'] = () => {\n    return srcUrl ?? null;\n  };\n\n  const map: CheerioDOMLib<T>['map'] = <TVal>(mapFn: (node: T) => TVal) => {\n    return mapFn(cheerioNode);\n  };\n\n  ///////////////////////\n  // NODE OPERATIONS\n  ///////////////////////\n\n  const findOne: CheerioDOMLib<T>['findOne'] = <TNewEl extends Cheerio<AnyNode> = T>(selector) => {\n    const resultEl = cheerioNode.find(selector).first() as TNewEl;\n    if (!resultEl.get(0)) return null;\n    return cheerioDOMLib(resultEl, srcUrl);\n  };\n\n  const findMany: CheerioDOMLib<T>['findMany'] = <TNewEl extends Cheerio<AnyNode> = T>(\n    selector\n  ) => {\n    const resultEls = splitCheerioSelection(cheerioNode.find(selector)) as TNewEl[];\n    return resultEls.map((ch) => cheerioDOMLib(ch, srcUrl));\n  };\n\n  const parent: CheerioDOMLib<T>['parent'] = <TNewEl extends Cheerio<AnyNode> = T>() => {\n    const parentEl = cheerioNode.parent().first() as TNewEl;\n    if (!parentEl.get(0)) return null;\n    return cheerioDOMLib(parentEl, srcUrl);\n  };\n\n  const children: CheerioDOMLib<T>['children'] = <TNewEl extends Cheerio<AnyNode> = T>() => {\n    const childEls = splitCheerioSelection(cheerioNode.children()) as TNewEl[];\n    return childEls.map((ch) => cheerioDOMLib(ch, srcUrl));\n  };\n\n  const root: CheerioDOMLib<T>['root'] = <TNewEl extends Cheerio<AnyNode> = T>() => {\n    const rootEl = cheerioNode._root?.first() as TNewEl | null;\n    if (!rootEl?.get(0)) return null;\n    return cheerioDOMLib(rootEl, srcUrl);\n  };\n\n  const remove: CheerioDOMLib<T>['remove'] = () => {\n    cheerioNode.remove();\n  };\n\n  return {\n    node: cheerioNode,\n\n    text,\n    textAsLower,\n    textAsUpper,\n    textAsNumber,\n    attr,\n    prop,\n    href,\n    src,\n    nodeName,\n    url,\n    map,\n\n    findOne,\n    findMany,\n    parent,\n    children,\n    root,\n    remove,\n  } satisfies CheerioDOMLib<T>;\n};\n"]}