@crawlee/utils 4.0.0-beta.8 → 4.0.0-beta.81

package/README.md

@@ -1,19 +1,23 @@
 <h1 align="center">
     <a href="https://crawlee.dev">
         <picture>
-          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/apify/crawlee/master/website/static/img/crawlee-dark.svg?sanitize=true">
-          <img alt="Crawlee" src="https://raw.githubusercontent.com/apify/crawlee/master/website/static/img/crawlee-light.svg?sanitize=true" width="500">
+          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/apify/crawlee/master/website/static/img/crawlee-dark.svg?sanitize=true" />
+          <img alt="Crawlee" src="https://raw.githubusercontent.com/apify/crawlee/master/website/static/img/crawlee-light.svg?sanitize=true" width="500" />
         </picture>
     </a>
-    <br>
+    <br />
     <small>A web scraping and browser automation library</small>
 </h1>
 
-<p align=center>
-    <a href="https://www.npmjs.com/package/@crawlee/core" rel="nofollow"><img src="https://img.shields.io/npm/v/@crawlee/core.svg" alt="NPM latest version" data-canonical-src="https://img.shields.io/npm/v/@crawlee/core/next.svg" style="max-width: 100%;"></a>
-    <a href="https://www.npmjs.com/package/@crawlee/core" rel="nofollow"><img src="https://img.shields.io/npm/dm/@crawlee/core.svg" alt="Downloads" data-canonical-src="https://img.shields.io/npm/dm/@crawlee/core.svg" style="max-width: 100%;"></a>
-    <a href="https://discord.gg/jyEM2PRvMU" rel="nofollow"><img src="https://img.shields.io/discord/801163717915574323?label=discord" alt="Chat on discord" data-canonical-src="https://img.shields.io/discord/801163717915574323?label=discord" style="max-width: 100%;"></a>
-    <a href="https://github.com/apify/crawlee/actions/workflows/test-ci.yml"><img src="https://github.com/apify/crawlee/actions/workflows/test-ci.yml/badge.svg?branch=master" alt="Build Status" style="max-width: 100%;"></a>
+<p align="center">
+    <a href="https://trendshift.io/repositories/5179" target="_blank"><img src="https://trendshift.io/api/badge/repositories/5179" alt="apify%2Fcrawlee | Trendshift" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+    <a href="https://www.npmjs.com/package/@crawlee/core" rel="nofollow"><img src="https://img.shields.io/npm/v/@crawlee/core.svg" alt="NPM latest version" data-canonical-src="https://img.shields.io/npm/v/@crawlee/core/next.svg" /></a>
+    <a href="https://www.npmjs.com/package/@crawlee/core" rel="nofollow"><img src="https://img.shields.io/npm/dm/@crawlee/core.svg" alt="Downloads" data-canonical-src="https://img.shields.io/npm/dm/@crawlee/core.svg" /></a>
+    <a href="https://discord.gg/jyEM2PRvMU" rel="nofollow"><img src="https://img.shields.io/discord/801163717915574323?label=discord" alt="Chat on discord" data-canonical-src="https://img.shields.io/discord/801163717915574323?label=discord" /></a>
+    <a href="https://github.com/apify/crawlee/actions/workflows/test-ci.yml"><img src="https://github.com/apify/crawlee/actions/workflows/test-ci.yml/badge.svg?branch=master" alt="Build Status" /></a>
 </p>
 
 Crawlee covers your crawling and scraping end-to-end and **helps you build reliable scrapers. Fast.**
@@ -24,7 +28,7 @@ Crawlee is available as the [`crawlee`](https://www.npmjs.com/package/crawlee) N
 
 > 👉 **View full documentation, guides and examples on the [Crawlee project website](https://crawlee.dev)** 👈
 
-> Crawlee for Python is open for early adopters. 🐍  [👉 Checkout the source code 👈](https://github.com/apify/crawlee-python).
+> Do you prefer 🐍 Python instead of JavaScript? [👉 Checkout Crawlee for Python 👈](https://github.com/apify/crawlee-python).
 
 ## Installation
 
@@ -85,7 +89,7 @@ By default, Crawlee stores data to `./storage` in the current working directory.
 We provide automated beta builds for every merged code change in Crawlee. You can find them in the npm [list of releases](https://www.npmjs.com/package/crawlee?activeTab=versions). If you want to test new features or bug fixes before we release them, feel free to install a beta build like this:
 
 ```bash
-npm install crawlee@3.12.3-beta.13
+npm install crawlee@next
 ```
 
 If you also use the [Apify SDK](https://github.com/apify/apify-sdk-js), you need to specify dependency overrides in your `package.json` file so that you don't end up with multiple versions of Crawlee installed:
@@ -94,9 +98,9 @@ If you also use the [Apify SDK](https://github.com/apify/apify-sdk-js), you need
 {
     "overrides": {
        "apify": {
-           "@crawlee/core": "3.12.3-beta.13",
-           "@crawlee/types": "3.12.3-beta.13",
-           "@crawlee/utils": "3.12.3-beta.13"
+           "@crawlee/core": "$crawlee",
+           "@crawlee/types": "$crawlee",
+           "@crawlee/utils": "$crawlee"
        }
     }
 }

package/index.d.ts

@@ -3,15 +3,14 @@ export * from './internals/cheerio.js';
 export * from './internals/chunk.js';
 export * from './internals/extract-urls.js';
 export * from './internals/general.js';
-export * from './internals/memory-info.js';
 export * from './internals/debug.js';
 export * as social from './internals/social.js';
 export * from './internals/typedefs.js';
 export * from './internals/open_graph_parser.js';
 export * from './internals/robots.js';
 export * from './internals/sitemap.js';
+export * from './internals/iterables.js';
+export * from './internals/robots.js';
+export * from './internals/sitemap.js';
 export * from './internals/url.js';
-export { getCurrentCpuTicksV2 } from './internals/systemInfoV2/cpu-info.js';
-export { getMemoryInfoV2 } from './internals/systemInfoV2/memory-info.js';
-export { Dictionary, Awaitable, Constructor } from '@crawlee/types';
-//# sourceMappingURL=index.d.ts.map
+export type { Dictionary, Awaitable, Constructor } from '@crawlee/types';

package/index.js

@@ -3,14 +3,13 @@ export * from './internals/cheerio.js';
 export * from './internals/chunk.js';
 export * from './internals/extract-urls.js';
 export * from './internals/general.js';
-export * from './internals/memory-info.js';
 export * from './internals/debug.js';
 export * as social from './internals/social.js';
 export * from './internals/typedefs.js';
 export * from './internals/open_graph_parser.js';
 export * from './internals/robots.js';
 export * from './internals/sitemap.js';
+export * from './internals/iterables.js';
+export * from './internals/robots.js';
+export * from './internals/sitemap.js';
 export * from './internals/url.js';
-export { getCurrentCpuTicksV2 } from './internals/systemInfoV2/cpu-info.js';
-export { getMemoryInfoV2 } from './internals/systemInfoV2/memory-info.js';
-//# sourceMappingURL=index.js.map

package/internals/blocked.d.ts

@@ -7,4 +7,3 @@ export declare const RETRY_CSS_SELECTORS: string[];
  * Content of proxy errors that should trigger a retry, as the proxy is likely getting blocked / is malfunctioning.
  */
 export declare const ROTATE_PROXY_ERRORS: string[];
-//# sourceMappingURL=blocked.d.ts.map

package/internals/blocked.js

@@ -17,4 +17,3 @@ export const ROTATE_PROXY_ERRORS = [
     'ERR_TUNNEL_CONNECTION_FAILED',
     'Proxy responded with',
 ];
-//# sourceMappingURL=blocked.js.map

package/internals/cheerio.d.ts

@@ -1,5 +1,7 @@
 import type { CheerioAPI } from 'cheerio';
 export type CheerioRoot = CheerioAPI;
+export type { CheerioAPI, Cheerio } from 'cheerio';
+export type { Element } from 'domhandler';
 /**
  * The function converts a HTML document to a plain text.
  *
@@ -27,7 +29,7 @@ export type CheerioRoot = CheerioAPI;
  * @param htmlOrCheerioElement HTML text or parsed HTML represented using a [cheerio](https://www.npmjs.com/package/cheerio) function.
  * @return Plain text
  */
-export declare function htmlToText(htmlOrCheerioElement: string | CheerioRoot): string;
+export declare function htmlToText(htmlOrCheerioElement: string | CheerioRoot): Promise<string>;
 /**
  * Extracts URLs from a given Cheerio object.
  *
@@ -38,4 +40,3 @@ export declare function htmlToText(htmlOrCheerioElement: string | CheerioRoot):
  * @return An array of absolute URLs
  */
 export declare function extractUrlsFromCheerio($: CheerioAPI, selector?: string, baseUrl?: string): string[];
-//# sourceMappingURL=cheerio.d.ts.map

package/internals/cheerio.js

@@ -1,4 +1,3 @@
-import * as cheerio from 'cheerio';
 import { tryAbsoluteURL } from './extract-urls.js';
 // NOTE: We are skipping 'noscript' since it's content is evaluated as text, instead of HTML elements. That damages the results.
 const SKIP_TAGS_REGEX = /^(script|style|canvas|svg|noscript)$/i;
@@ -30,10 +29,11 @@ const BLOCK_TAGS_REGEX = /^(p|h1|h2|h3|h4|h5|h6|ol|ul|li|pre|address|blockquote|
  * @param htmlOrCheerioElement HTML text or parsed HTML represented using a [cheerio](https://www.npmjs.com/package/cheerio) function.
  * @return Plain text
  */
-export function htmlToText(htmlOrCheerioElement) {
+export async function htmlToText(htmlOrCheerioElement) {
+    const { load } = await import('cheerio');
     if (!htmlOrCheerioElement)
         return '';
-    const $ = typeof htmlOrCheerioElement === 'function' ? htmlOrCheerioElement : cheerio.load(htmlOrCheerioElement);
+    const $ = typeof htmlOrCheerioElement === 'function' ? htmlOrCheerioElement : load(htmlOrCheerioElement);
     let text = '';
     const process = (elems) => {
         const len = elems ? elems.length : 0;
@@ -42,7 +42,7 @@ export function htmlToText(htmlOrCheerioElement) {
             if (elem.type === 'text') {
                 // Compress spaces, unless we're inside <pre> element
                 let compr;
-                if (elem.parent && elem.parent.tagName === 'pre')
+                if (elem.parent?.tagName === 'pre')
                     compr = elem.data;
                 else
                     compr = elem.data.replace(/\s+/g, ' ');
@@ -107,4 +107,3 @@ export function extractUrlsFromCheerio($, selector = 'a', baseUrl = '') {
     })
         .filter(Boolean);
 }
-//# sourceMappingURL=cheerio.js.map

package/internals/chunk.d.ts

@@ -1,2 +1 @@
 export declare function chunk<T>(array: readonly T[], chunkSize: number): T[][];
-//# sourceMappingURL=chunk.d.ts.map

package/internals/chunk.js

@@ -37,4 +37,3 @@ export function chunk(array, chunkSize) {
         chunks.push(clone.splice(0, chunkSize));
     return chunks;
 }
-//# sourceMappingURL=chunk.js.map

package/internals/debug.d.ts

@@ -27,5 +27,15 @@ interface Request<UserData extends Dictionary = Dictionary> {
  * @param [additionalFields] Object containing additional fields to be added.
  */
 export declare function createRequestDebugInfo(request: Request, response?: IncomingMessage | Partial<BrowserResponseLike>, additionalFields?: Dictionary): Dictionary;
+/**
+ * Returns a human-readable label for an unknown value,
+ * suitable for embedding in error messages and log output.
+ *
+ * Returns `constructor.name` when available (e.g. `"Configuration"`, `"Number"`),
+ * otherwise falls back to `util.inspect` (e.g. for `null`, `undefined`).
+ *
+ * @internal
+ */
+export declare function inspectValue(value: unknown): string;
+export declare function getObjectType(value: unknown): string;
 export {};
-//# sourceMappingURL=debug.d.ts.map

package/internals/debug.js

@@ -1,3 +1,4 @@
+import { inspect } from 'node:util';
 import ow from 'ow';
 /**
  * Creates a standardized debug info from request and response. This info is usually added to dataset under the hidden `#debug` field.
@@ -26,4 +27,36 @@ export function createRequestDebugInfo(request, response = {}, additionalFields
         ...additionalFields,
     };
 }
-//# sourceMappingURL=debug.js.map
+/**
+ * Returns a human-readable label for an unknown value,
+ * suitable for embedding in error messages and log output.
+ *
+ * Returns `constructor.name` when available (e.g. `"Configuration"`, `"Number"`),
+ * otherwise falls back to `util.inspect` (e.g. for `null`, `undefined`).
+ *
+ * @internal
+ */
+export function inspectValue(value) {
+    if (typeof value === 'object' && value !== null && value.constructor?.name) {
+        return value.constructor.name;
+    }
+    return inspect(value, {
+        depth: 0,
+        compact: true,
+        maxStringLength: 64,
+        breakLength: Infinity,
+        colors: false,
+    });
+}
+export function getObjectType(value) {
+    const simple = typeof value;
+    if (['string', 'number', 'boolean', 'bigint'].includes(simple)) {
+        return simple;
+    }
+    const objectType = Object.prototype.toString.call(value);
+    const type = /\[object (\w+)]/.exec(objectType)[1];
+    if (type === 'Uint8Array') {
+        return 'Buffer';
+    }
+    return ['Date', 'Buffer', 'RegExp'].includes(type) ? type : type.toLowerCase();
+}

package/internals/extract-urls.d.ts

@@ -1,3 +1,4 @@
+import type { BaseHttpClient } from '@crawlee/types';
 export interface DownloadListOfUrlsOptions {
     /**
      * URL to the file
@@ -16,6 +17,10 @@ export interface DownloadListOfUrlsOptions {
     urlRegExp?: RegExp;
     /** Allows to use a proxy for the download request. */
     proxyUrl?: string;
+    /**
+     * Custom HTTP client to use for downloading the file.
+     */
+    httpClient?: BaseHttpClient;
 }
 /**
  * Returns a promise that resolves to an array of urls parsed from the resource available at the provided url.
@@ -41,4 +46,3 @@ export declare function extractUrls(options: ExtractUrlsOptions): string[];
  * Helper function used to validate URLs used when extracting URLs from a page
  */
 export declare function tryAbsoluteURL(href: string, baseUrl: string): string | undefined;
-//# sourceMappingURL=extract-urls.d.ts.map

package/internals/extract-urls.js

@@ -1,4 +1,4 @@
-import { gotScraping } from 'got-scraping';
+import { FetchHttpClient } from '@crawlee/http-client';
 import ow from 'ow';
 import { URL_NO_COMMAS_REGEX } from './general.js';
 /**
@@ -11,15 +11,19 @@ export async function downloadListOfUrls(options) {
         encoding: ow.optional.string,
         urlRegExp: ow.optional.regExp,
         proxyUrl: ow.optional.string,
+        httpClient: ow.optional.object,
     }));
-    const { url, encoding = 'utf8', urlRegExp = URL_NO_COMMAS_REGEX, proxyUrl } = options;
+    const { url, encoding = 'utf8', urlRegExp = URL_NO_COMMAS_REGEX, proxyUrl, httpClient = new FetchHttpClient(), } = options;
     // Try to detect wrong urls and fix them. Currently, detects only sharing url instead of csv download one.
-    const match = url.match(/^(https:\/\/docs\.google\.com\/spreadsheets\/d\/(?:\w|-)+)\/?/);
+    const match = /^(https:\/\/docs\.google\.com\/spreadsheets\/d\/(?:\w|-)+)\/?/.exec(url);
     let fixedUrl = url;
     if (match) {
         fixedUrl = `${match[1]}/gviz/tq?tqx=out:csv`;
     }
-    const { body: string } = await gotScraping({ url: fixedUrl, encoding, proxyUrl });
+    const response = await httpClient.sendRequest(new Request(fixedUrl, { method: 'GET' }), {
+        proxyUrl,
+    });
+    const string = new TextDecoder(encoding).decode(new Uint8Array(await response.arrayBuffer()));
     return extractUrls({ string, urlRegExp });
 }
 /**
@@ -49,4 +53,3 @@ export function tryAbsoluteURL(href, baseUrl) {
         return undefined;
     }
 }
-//# sourceMappingURL=extract-urls.js.map

package/internals/general.d.ts

@@ -8,20 +8,6 @@ export declare const URL_NO_COMMAS_REGEX: RegExp;
  * Note, however, that this may prevent parsing URLs from comma delimited lists, or the URLs may become malformed.
  */
 export declare const URL_WITH_COMMAS_REGEX: RegExp;
-/**
- * Returns a `Promise` that resolves to true if the code is running in a Docker container.
- */
-export declare function isDocker(forceReset?: boolean): Promise<boolean>;
-/**
- * Detects if crawlee is running in a containerized environment.
- */
-export declare function isContainerized(): Promise<boolean>;
-export declare function isLambda(): boolean;
-/**
- * gets the cgroup version by checking for a file at /sys/fs/cgroup/memory
- * @returns "V1" or "V2" for the version of cgroup or null if cgroup is not found.
- */
-export declare function getCgroupsVersion(forceReset?: boolean): Promise<"V1" | "V2" | null>;
 /**
  * Computes a weighted average of an array of numbers, complemented by an array of weights.
  * @ignore
@@ -54,4 +40,20 @@ export declare function snakeCaseToCamelCase(snakeCaseStr: string): string;
  * @ignore
  */
 export declare function expandShadowRoots(document: Document): string;
-//# sourceMappingURL=general.d.ts.map
+/**
+ * Checks if the given value is a Node.js Stream or a Web API ReadableStream.
+ * @ignore
+ */
+export declare function isStream(value: unknown): value is NodeJS.ReadableStream | ReadableStream;
+/**
+ * Checks if the given value is a Node.js Buffer, ArrayBuffer, or TypedArray.
+ * @ignore
+ */
+export declare function isBuffer(value: unknown): value is Buffer | ArrayBuffer | ArrayBufferView;
+/**
+ * Converts a byte-like value (Buffer, ArrayBuffer, or any typed-array / DataView) into a Buffer over
+ * the exact same bytes, honoring `byteOffset` / `byteLength` for views. Existing Buffers are returned
+ * as-is. Used by storage backends, which persist raw bytes regardless of the input's concrete shape.
+ * @ignore
+ */
+export declare function toBuffer(value: Buffer | ArrayBuffer | ArrayBufferView): Buffer;

package/internals/general.js

@@ -1,94 +1,14 @@
-import fs from 'node:fs/promises';
 import { setTimeout } from 'node:timers/promises';
 /**
  * Default regular expression to match URLs in a string that may be plain text, JSON, CSV or other. It supports common URL characters
  * and does not support URLs containing commas or spaces. The URLs also may contain Unicode letters (not symbols).
  */
-export const URL_NO_COMMAS_REGEX = /https?:\/\/(www\.)?([\p{L}0-9]|[\p{L}0-9][-\p{L}0-9@:%._+~#=]{0,254}[\p{L}0-9])\.[a-z]{2,63}(:\d{1,5})?(\/[-\p{L}0-9@:%_+.~#?&/=()]*)?/giu;
+export const URL_NO_COMMAS_REGEX = /https?:\/\/(www\.)?([\p{L}0-9]|[\p{L}0-9][-\p{L}0-9@:%._+~#=]{0,254}[\p{L}0-9])\.[a-z]{2,63}(:\d{1,5})?(\/[-\p{L}0-9@:%_+.~#?&/=()'*]*)?/giu;
 /**
  * Regular expression that, in addition to the default regular expression `URL_NO_COMMAS_REGEX`, supports matching commas in URL path and query.
  * Note, however, that this may prevent parsing URLs from comma delimited lists, or the URLs may become malformed.
  */
-export const URL_WITH_COMMAS_REGEX = /https?:\/\/(www\.)?([\p{L}0-9]|[\p{L}0-9][-\p{L}0-9@:%._+~#=]{0,254}[\p{L}0-9])\.[a-z]{2,63}(:\d{1,5})?(\/[-\p{L}0-9@:%_+,.~#?&/=()]*)?/giu;
-let isDockerPromiseCache;
-async function createIsDockerPromise() {
-    const promise1 = fs
-        .stat('/.dockerenv')
-        .then(() => true)
-        .catch(() => false);
-    const promise2 = fs
-        .readFile('/proc/self/cgroup', 'utf8')
-        .then((content) => content.includes('docker'))
-        .catch(() => false);
-    const [result1, result2] = await Promise.all([promise1, promise2]);
-    return result1 || result2;
-}
-/**
- * Returns a `Promise` that resolves to true if the code is running in a Docker container.
- */
-export async function isDocker(forceReset) {
-    // Parameter forceReset is just internal for unit tests.
-    if (!isDockerPromiseCache || forceReset)
-        isDockerPromiseCache = createIsDockerPromise();
-    return isDockerPromiseCache;
-}
-let isContainerizedResult;
-/**
- * Detects if crawlee is running in a containerized environment.
- */
-export async function isContainerized() {
-    // Value is very unlikley to change. Cache the result after the first execution.
-    if (isContainerizedResult !== undefined) {
-        return isContainerizedResult;
-    }
-    // return false if running in aws lambda
-    if (isLambda()) {
-        isContainerizedResult = false;
-        return isContainerizedResult;
-    }
-    const dockerenvCheck = fs
-        .stat('/.dockerenv')
-        .then(() => true)
-        .catch(() => false);
-    const cgroupCheck = fs
-        .readFile('/proc/self/cgroup', 'utf8')
-        .then((content) => content.includes('docker'))
-        .catch(() => false);
-    const [dockerenvResult, cgroupResult] = await Promise.all([dockerenvCheck, cgroupCheck]);
-    isContainerizedResult = dockerenvResult || cgroupResult || !!process.env.KUBERNETES_SERVICE_HOST;
-    return isContainerizedResult;
-}
-export function isLambda() {
-    return !!process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE;
-}
-let _cgroupsVersion;
-/**
- * gets the cgroup version by checking for a file at /sys/fs/cgroup/memory
- * @returns "V1" or "V2" for the version of cgroup or null if cgroup is not found.
- */
-export async function getCgroupsVersion(forceReset) {
-    // Parameter forceReset is just internal for unit tests.
-    if (_cgroupsVersion !== undefined && !forceReset) {
-        return _cgroupsVersion;
-    }
-    try {
-        // If this directory does not exists, cgroups are not available
-        await fs.access('/sys/fs/cgroup/');
-    }
-    catch (e) {
-        _cgroupsVersion = null;
-        return null;
-    }
-    _cgroupsVersion = 'V1';
-    try {
-        // If this directory does not exists, assume the container is using cgroups V2
-        await fs.access('/sys/fs/cgroup/memory/');
-    }
-    catch (e) {
-        _cgroupsVersion = 'V2';
-    }
-    return _cgroupsVersion;
-}
+export const URL_WITH_COMMAS_REGEX = /https?:\/\/(www\.)?([\p{L}0-9]|[\p{L}0-9][-\p{L}0-9@:%._+~#=]{0,254}[\p{L}0-9])\.[a-z]{2,63}(:\d{1,5})?(\/[-\p{L}0-9@:%_+,.~#?&/=()'*]*)?/giu;
 /**
  * Computes a weighted average of an array of numbers, complemented by an array of weights.
  * @ignore
@@ -164,4 +84,45 @@ export function expandShadowRoots(document) {
     replaceShadowDomsWithHtml(document.body);
     return document.documentElement.outerHTML;
 }
-//# sourceMappingURL=general.js.map
+/**
+ * Checks if the given value is a Node.js Stream or a Web API ReadableStream.
+ * @ignore
+ */
+export function isStream(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    // A Node.js Readable is both pipeable and async-iterable; a Web ReadableStream exposes pipeTo.
+    // Requiring async-iterability for the `pipe` branch rejects plain `{ pipe }` ducks that would
+    // otherwise blow up later in the storage backends' drain loop with a cryptic TypeError.
+    const isNodeStream = typeof value.pipe === 'function' && typeof value[Symbol.asyncIterator] === 'function';
+    const isWebStream = typeof value.pipeTo === 'function';
+    return isNodeStream || isWebStream;
+}
+/**
+ * Checks if the given value is a Node.js Buffer, ArrayBuffer, or TypedArray.
+ * @ignore
+ */
+export function isBuffer(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        (Buffer.isBuffer(value) ||
+            value instanceof ArrayBuffer ||
+            ArrayBuffer.isView(value) ||
+            value.constructor?.name === 'Buffer'));
+}
+/**
+ * Converts a byte-like value (Buffer, ArrayBuffer, or any typed-array / DataView) into a Buffer over
+ * the exact same bytes, honoring `byteOffset` / `byteLength` for views. Existing Buffers are returned
+ * as-is. Used by storage backends, which persist raw bytes regardless of the input's concrete shape.
+ * @ignore
+ */
+export function toBuffer(value) {
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (value instanceof ArrayBuffer) {
+        return Buffer.from(value);
+    }
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+}

package/internals/iterables.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Type guard that checks if a value is iterable (has Symbol.iterator).
+ * @internal
+ *
+ * **Example usage:**
+ * ```ts
+ * if (isIterable(someValue)) {
+ *   for (const item of someValue) {
+ *     console.log(item);
+ *   }
+ * }
+ * ```
+ */
+export declare function isIterable<T>(value: unknown): value is Iterable<T>;
+/**
+ * Type guard that checks if a value is async iterable (has Symbol.asyncIterator).
+ * @internal
+ *
+ * **Example usage:**
+ * ```ts
+ * if (isAsyncIterable(someValue)) {
+ *   for await (const item of someValue) {
+ *     console.log(item);
+ *   }
+ * }
+ * ```
+ */
+export declare function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T>;
+/**
+ * Converts any iterable or async iterable to an async iterable.
+ * @internal
+ *
+ * @yields Each item from the input iterable
+ *
+ * **Example usage:**
+ * ```ts
+ * const syncArray = [1, 2, 3];
+ * for await (const item of asyncifyIterable(syncArray)) {
+ *   console.log(item); // 1, 2, 3
+ * }
+ * ```
+ */
+export declare function asyncifyIterable<T>(iterable: Iterable<T> | AsyncIterable<T>): AsyncIterable<T>;
+/**
+ * Lazily splits the input async iterable into chunks of specified size.
+ * The last chunk may contain fewer items if the total number of items
+ * is not evenly divisible by the chunk size.
+ * @internal
+ *
+ * @yields Arrays of items, each containing up to chunkSize items
+ *
+ * **Example usage:**
+ * ```ts
+ * const numbers = async function* () {
+ *   for (let i = 1; i <= 10; i++) yield i;
+ * };
+ *
+ * for await (const chunk of chunkedAsyncIterable(numbers(), 3)) {
+ *   console.log(chunk); // [1, 2, 3], [4, 5, 6], [7, 8, 9], [10]
+ * }
+ * ```
+ */
+export declare function chunkedAsyncIterable<T>(iterable: AsyncIterable<T> | Iterable<T>, chunkSize: number | (() => number)): AsyncIterable<T[]>;
+/**
+ * An async iterator that also supports peeking at the next value without consuming it.
+ * Extends both AsyncIterator and AsyncIterable interfaces.
+ * @internal
+ */
+export interface PeekableAsyncIterator<T> extends AsyncIterator<T>, AsyncIterable<T> {
+    /**
+     * Peeks at the next value without consuming it from the iterator.
+     * Subsequent calls to peek() will return the same value until next() is called.
+     *
+     * @returns Promise that resolves to the next value, or undefined if the iterator is exhausted
+     */
+    peek(): Promise<T | undefined>;
+}
+/**
+ * An async iterable that yields peekable async iterators.
+ * @internal
+ */
+export interface PeekableAsyncIterable<T> extends AsyncIterable<T> {
+    [Symbol.asyncIterator](): PeekableAsyncIterator<T>;
+}
+/**
+ * Wraps an async iterable to provide peek functionality, allowing you to look at
+ * the next value without consuming it from the iterator.
+ * @internal
+ *
+ * @param iterable - The async iterable to make peekable
+ *
+ * **Example usage:**
+ * ```ts
+ * const numbers = async function* () {
+ *   yield 1; yield 2; yield 3;
+ * };
+ *
+ * const peekable = peekableAsyncIterable(numbers());
+ * const iterator = peekable[Symbol.asyncIterator]();
+ *
+ * console.log(await iterator.peek()); // 1 (doesn't consume)
+ * console.log(await iterator.peek()); // 1 (still doesn't consume)
+ * console.log(await iterator.next()); // { value: 1, done: false } (now consumed)
+ * console.log(await iterator.peek()); // 2 (next value)
+ * ```
+ */
+export declare function peekableAsyncIterable<T>(iterable: AsyncIterable<T> | Iterable<T>): PeekableAsyncIterable<T>;
+/**
+ * Merges multiple async iterables into a single async iterable, yielding values concurrently.
+ *
+ * **Example usage:**
+ * ```ts
+ * const asyncIterable1 = async function* () {
+ *   yield 1; yield 3; yield 5;
+ * };
+ *
+ * const asyncIterable2 = async function* () {
+ *   yield 2; yield 4; yield 6;
+ * };
+ *
+ * for await (const value of mergeAsyncIterables(asyncIterable1(), asyncIterable2())) {
+ *   console.log(value);
+ * }
+ * ```
+ */
+export declare function mergeAsyncIterables<T>(...iterables: AsyncIterable<T>[]): AsyncIterable<T>;