apify-client 3.0.0-beta.2 → 3.0.0-beta.20

package/dist/timeouts.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/** Default duration of the `short` timeout tier, in seconds. */
+export const DEFAULT_TIMEOUT_SHORT_SECS = 5;
+/** Default duration of the `medium` timeout tier, in seconds. */
+export const DEFAULT_TIMEOUT_MEDIUM_SECS = 30;
+/** Default duration of the `long` timeout tier, in seconds. */
+export const DEFAULT_TIMEOUT_LONG_SECS = 360;
+/** Default cap on the timeout of a single request attempt, in seconds. */
+export const DEFAULT_TIMEOUT_MAX_SECS = 360;
+/**
+ * Schema of {@link Timeout}. Zero is rejected on purpose - `'noTimeout'` is the explicit way to run without one.
+ */
+const timeoutSchema = z.union([z.enum(['short', 'medium', 'long', 'noTimeout']), z.number().positive()]);
+/**
+ * Schema of {@link Timeout}, optional, for the methods that validate `timeoutSecs` on its own.
+ * @internal
+ */
+export const optionalTimeoutSchema = timeoutSchema.optional();
+/**
+ * Schema shape of {@link TimeoutOptions}, to spread into the option schema of every method that sends a
+ * request. One copy stops it drifting from the interface.
+ * @internal
+ */
+export const timeoutOptionsShape = {
+    timeoutSecs: optionalTimeoutSchema,
+};
+/**
+ * Schema of {@link TimeoutOptions}, for the methods that take no other option.
+ * @internal
+ */
+export const timeoutOptionsSchema = z.strictObject(timeoutOptionsShape);

package/dist/utils.d.ts

@@ -1,18 +1,12 @@
 import type { Readable } from 'node:stream';
-import type { JsonValue, TypedArray } from 'type-fest';
+import type { TypedArray } from 'type-fest';
 import { z } from 'zod';
 import type { ApifyApiError } from './apify_api_error.js';
+import { parseArgument } from '@apify/validations';
+import type { ApifyResponse } from './http_client.js';
 import type { RequestQueueClientListRequestsOptions, RequestQueueClientListRequestsResult } from './resource_clients/request_queue.js';
 import type { WebhookUpdateData } from './resource_clients/webhook.js';
-/**
- * Parses `value` with `schema`, returning the typed result (with schema defaults applied).
- * Throws {@link ArgumentValidationError} on failure.
- *
- * The optional `label` names the interface being validated and is appended to every error line
- * (e.g. ``... at `memory` in `ActorStartOptions` ``).
- * @internal
- */
-export declare function parseArgument<TValue, TSchema extends z.ZodType>(value: TValue, schema: TSchema, label?: string): TValue & z.output<TSchema>;
+export { parseArgument };
 /**
  * Accepts any non-null, non-array object as a predicate for `z.custom()`.
  * @internal
@@ -33,32 +27,34 @@ export declare const anyObjectSchema: z.ZodCustom<Record<string, unknown>, Recor
 export interface MaybeData<R> {
     data?: R;
 }
+/**
+ * Turns a JSON API response into the value a resource method returns: unwraps the `data` envelope and validates the
+ * result against `schema`, one of the schemas generated from the OpenAPI specification. The validated copy is what
+ * callers get, so it is the schema's output -- unknown fields and unknown enum values included, since the schemas let
+ * both through, date-time fields turned into `Date` objects, and URL fields normalized, since `z.url()` hands back the
+ * parsed URL's serialization.
+ *
+ * Throws {@link ResponseValidationError} when the response does not match the specification.
+ * @internal
+ */
+export declare function parseResponse<R>(response: ApifyResponse, schema: z.ZodType): R;
 /**
  * Returns object's 'data' property or throws if parameter is not an object,
  * or an object without a 'data' property.
  */
 export declare function pluckData<R>(obj: MaybeData<R>): R;
 /**
- * If given HTTP error has NOT_FOUND_STATUS_CODE status code then returns undefined.
- * Otherwise rethrows error.
+ * Swallows a 404 Not Found API error and rethrows anything else.
  */
 export declare function catchNotFoundOrThrow(err: ApifyApiError): void;
-type ReturnJsonValue = string | number | boolean | null | Date | ReturnJsonObject | ReturnJsonArray;
-type ReturnJsonObject = {
-    [Key in string]?: ReturnJsonValue;
-};
-type ReturnJsonArray = ReturnJsonValue[];
 /**
- * Traverses JSON structure and converts fields that end with "At" to a Date object (fields such as "modifiedAt" or
- * "createdAt").
+ * Like `catchNotFoundOrThrow()`, but swallows the 404 only when the client names its resource by ID.
  *
- * If you want parse other fields as well, you can provide a custom matcher function shouldParseField(). This
- * admittedly awkward approach allows this function to be reused for various purposes without introducing potential
- * breaking changes.
- *
- * If the field cannot be converted to Date, it is left as is.
+ * A chained client without an ID, such as `run.dataset()` or `run.log()`, requests a path where a 404 can mean either
+ * the parent or the default sub-resource is missing. The response cannot tell the two apart, so the error propagates.
+ * @internal
  */
-export declare function parseDateFields(input: JsonValue, shouldParseField?: ((key: string) => boolean) | null, depth?: number): ReturnJsonValue;
+export declare function catchNotFoundForResourceOrThrow(err: ApifyApiError, resourceId: string | undefined): void;
 /**
  * Helper function that converts array of webhooks to base64 string
  */
@@ -67,15 +63,37 @@ export interface CompressedValue {
     data: Buffer;
     encoding: 'br' | 'gzip';
 }
+/**
+ * Decides whether a request body with the given content type is worth compressing.
+ *
+ * Images, audio, video and archives already carry their own compression. Running them through brotli or gzip
+ * burns CPU, holds a second full copy of the body in memory, and usually produces output slightly larger than
+ * the input. Formats that are raw despite such a media type, for example `image/bmp` or `audio/wav`, are still
+ * compressed. A body with no content type is assumed to be compressible.
+ * @internal
+ */
+export declare function isCompressibleContentType(contentType?: string): boolean;
 /**
  * Compress the passed value using brotli, falling back to gzip. Returns undefined if the data is
  * too small / wrong type, or if neither algorithm is available.
  */
 export declare function maybeCompressValue(value: unknown): Promise<CompressedValue | undefined>;
 /**
- * Helper function slice the items from array to fit the max byte length.
+ * Returns the UTF-8 byte length of a string.
  */
-export declare function sliceArrayByByteLength<T>(array: T[], maxByteLength: number, startIndex: number): T[];
+export declare function utf8ByteLength(value: string): number;
+/**
+ * Splits JSON-serialized items into consecutive batches of at most `maxCount` items, each of which fits into a JSON
+ * array body - the items joined by commas between brackets - of at most `maxByteLength` bytes. The `byteLength` of an
+ * item is the UTF-8 byte length of its serialization. An item too large for a body of its own still gets one, so a
+ * caller that cannot send such an item has to reject it beforehand.
+ */
+export declare function splitIntoJsonArrayBatches<T extends {
+    byteLength: number;
+}>(items: readonly T[], { maxCount, maxByteLength }: {
+    maxCount: number;
+    maxByteLength: number;
+}): T[][];
 export declare function isNode(): boolean;
 export declare function isBuffer(value: unknown): value is Buffer | ArrayBuffer | TypedArray;
 export declare function isStream(value: unknown): value is Readable;
@@ -83,14 +101,10 @@ export declare function getVersionData(): {
     version: string;
 };
 /**
- * Helper class to create async iterators from paginated list endpoints with exclusive start key.
+ * Helper class to create async iterators from paginated list endpoints.
  */
 export declare class RequestQueuePaginationIterator {
-    private readonly maxPageLimit;
-    private readonly getPage;
-    private readonly limit?;
-    private readonly exclusiveStartId?;
-    private readonly cursor?;
+    #private;
     constructor(options: RequestQueuePaginationIteratorOptions);
     [Symbol.asyncIterator](): AsyncIterator<RequestQueueClientListRequestsResult>;
 }
@@ -105,7 +119,6 @@ export interface RequestQueuePaginationIteratorOptions {
     maxPageLimit: number;
     getPage: (opts: RequestQueueClientListRequestsOptions) => Promise<RequestQueueClientListRequestsResult>;
     limit?: number;
-    exclusiveStartId?: string;
     cursor?: string;
 }
 /**
@@ -164,6 +177,16 @@ export interface PaginatedList<Data> extends PaginatedResponse<Data> {
     /** Should the results be in descending order. */
     desc: boolean;
 }
+/**
+ * Key under which a page of dataset items carries the number of rows the API scanned to produce it, as a
+ * non-enumerable property that stays out of the page's public shape. The API applies `offset` and `limit` to the
+ * dataset's rows first and shapes the result afterwards: filters (`clean`, `skipEmpty`, `skipHidden`) drop items and
+ * `unwind` splits or drops them, so `items.length` can land on either side of the rows scanned. The
+ * `x-apify-pagination-count` header reports the scanned number, and the offset iterator advances and terminates by it
+ * alone. A page without the property falls back to `items.length`.
+ * @internal
+ */
+export declare const SCANNED_COUNT: unique symbol;
 /**
  * Type representing both a Promise of a paginated list and an async iterable.
  *
@@ -192,12 +215,6 @@ export type DistributiveOptional<T, K extends keyof T> = T extends any ? Omit<T,
  * Adds query parameters to a given URL based on the provided options object.
  */
 export declare function applyQueryParamsToUrl(url: URL, options?: Record<string, string | number | boolean | string[] | undefined>): URL;
-/**
- * Builds a `[check, message]` pair to spread into `.refine()`, asserting that at most one of `keys`
- * is present. Pass the options interface as `T`, so that a misspelled key is a type error.
- * @internal
- */
-export declare const mutuallyExclusive: <T extends object>(...keys: (keyof T & string)[]) => [(value: T) => boolean, string];
 /**
  * Percent-encodes a caller-supplied URL path segment so it cannot restructure the request path.
  *
@@ -210,4 +227,3 @@ export declare function toPathSegment(value: string): string;
  * `requests/batch` keep their separators; an array has each of its segments encoded individually.
  */
 export declare function toPath(path: string | string[]): string;
-export {};

package/dist/utils.js

@@ -1,30 +1,56 @@
 import { z } from 'zod';
-import { ArgumentValidationError } from './argument_validation_error.js';
+import { NotFoundError } from './apify_api_error.js';
+import { parseArgument } from '@apify/validations';
+import { ResponseValidationError } from './response_validation_error.js';
 // @ts-ignore if we enable `resolveJsonModule`, we end up with a `src` folder in `dist`
 import packageJson from '../package.json' with { type: 'json' };
-const NOT_FOUND_STATUS_CODE = 404;
-const RECORD_NOT_FOUND_TYPE = 'record-not-found';
-const RECORD_OR_TOKEN_NOT_FOUND_TYPE = 'record-or-token-not-found';
 const MIN_COMPRESS_BYTES = 1024;
-// Zod installs its English locale as a module-level side effect but ships `"sideEffects": false`, so
-// any tree-shaking bundler drops it and every message degrades to a bare "Invalid input". Passing it
-// in per parse keeps them intact without reaching into the zod config the whole process shares.
-const { localeError } = z.locales.en();
-/**
- * Parses `value` with `schema`, returning the typed result (with schema defaults applied).
- * Throws {@link ArgumentValidationError} on failure.
- *
- * The optional `label` names the interface being validated and is appended to every error line
- * (e.g. ``... at `memory` in `ActorStartOptions` ``).
- * @internal
- */
-export function parseArgument(value, schema, label) {
-    const result = schema.safeParse(value, { error: localeError });
-    if (!result.success) {
-        throw new ArgumentValidationError(result.error, value, label);
-    }
-    return result.data;
-}
+/** Media type prefixes whose payloads carry their own compression, so compressing the request body is wasted work. */
+const ALREADY_COMPRESSED_MEDIA_TYPE_PREFIXES = ['audio/', 'image/', 'video/'];
+/** Exact media types whose payloads carry their own compression. */
+const ALREADY_COMPRESSED_MEDIA_TYPES = new Set([
+    'application/epub+zip',
+    'application/gzip',
+    'application/java-archive',
+    'application/vnd.android.package-archive',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.rar',
+    'application/x-7z-compressed',
+    'application/x-bzip',
+    'application/x-bzip2',
+    'application/x-gzip',
+    'application/x-rar-compressed',
+    'application/x-xz',
+    'application/x-zip-compressed',
+    'application/zip',
+    'application/zstd',
+    'font/woff',
+    'font/woff2',
+]);
+/** Uncompressed media types that sit under an already-compressed prefix, so compressing them still pays off. */
+const COMPRESSIBLE_MEDIA_TYPES = new Set([
+    'audio/aiff',
+    'audio/basic',
+    'audio/l16',
+    'audio/l24',
+    'audio/midi',
+    'audio/vnd.wave',
+    'audio/wav',
+    'audio/wave',
+    'audio/x-aiff',
+    'audio/x-wav',
+    'image/bmp',
+    'image/tiff',
+    'image/vnd.adobe.photoshop',
+    'image/vnd.microsoft.icon',
+    'image/x-icon',
+    'image/x-ms-bmp',
+]);
+/** Structured syntax suffixes marking a media type as text even under an already-compressed prefix (`image/svg+xml`). */
+const COMPRESSIBLE_MEDIA_TYPE_SUFFIXES = ['+json', '+xml'];
+export { parseArgument };
 /**
  * Accepts any non-null, non-array object as a predicate for `z.custom()`.
  * @internal
@@ -41,6 +67,29 @@ export function isNonArrayObject(value) {
 export const anyObjectSchema = z.custom(isNonArrayObject, {
     error: 'Invalid input: expected an object',
 });
+// Zod installs its English locale as a module-level side effect but ships `"sideEffects": false`, so
+// any tree-shaking bundler drops it and every message degrades to a bare "Invalid input". Passing it
+// in per parse keeps them intact without reaching into the zod config the whole process shares.
+const { localeError } = z.locales.en();
+/**
+ * Turns a JSON API response into the value a resource method returns: unwraps the `data` envelope and validates the
+ * result against `schema`, one of the schemas generated from the OpenAPI specification. The validated copy is what
+ * callers get, so it is the schema's output -- unknown fields and unknown enum values included, since the schemas let
+ * both through, date-time fields turned into `Date` objects, and URL fields normalized, since `z.url()` hands back the
+ * parsed URL's serialization.
+ *
+ * Throws {@link ResponseValidationError} when the response does not match the specification.
+ * @internal
+ */
+export function parseResponse(response, schema) {
+    const data = pluckData(response.data);
+    const result = schema.safeParse(data, { error: localeError });
+    if (!result.success) {
+        const { method = 'GET', url = '' } = response.config;
+        throw new ResponseValidationError(result.error, data, { method, url });
+    }
+    return result.data;
+}
 /**
  * Returns object's 'data' property or throws if parameter is not an object,
  * or an object without a 'data' property.
@@ -53,62 +102,23 @@ export function pluckData(obj) {
     throw new Error(`Expected response object with a "data" property, but received: ${obj}`);
 }
 /**
- * If given HTTP error has NOT_FOUND_STATUS_CODE status code then returns undefined.
- * Otherwise rethrows error.
+ * Swallows a 404 Not Found API error and rethrows anything else.
  */
 export function catchNotFoundOrThrow(err) {
-    const isNotFoundStatus = err.statusCode === NOT_FOUND_STATUS_CODE;
-    const isNotFoundMessage = err.type === RECORD_NOT_FOUND_TYPE || err.type === RECORD_OR_TOKEN_NOT_FOUND_TYPE || err.httpMethod === 'head';
-    const isNotFoundError = isNotFoundStatus && isNotFoundMessage;
-    if (!isNotFoundError)
+    if (!(err instanceof NotFoundError))
         throw err;
 }
 /**
- * Traverses JSON structure and converts fields that end with "At" to a Date object (fields such as "modifiedAt" or
- * "createdAt").
- *
- * If you want parse other fields as well, you can provide a custom matcher function shouldParseField(). This
- * admittedly awkward approach allows this function to be reused for various purposes without introducing potential
- * breaking changes.
+ * Like `catchNotFoundOrThrow()`, but swallows the 404 only when the client names its resource by ID.
  *
- * If the field cannot be converted to Date, it is left as is.
+ * A chained client without an ID, such as `run.dataset()` or `run.log()`, requests a path where a 404 can mean either
+ * the parent or the default sub-resource is missing. The response cannot tell the two apart, so the error propagates.
+ * @internal
  */
-export function parseDateFields(input, shouldParseField = null, depth = 0) {
-    // Don't go too deep to avoid stack overflows (especially if there is a circular reference). The depth of 4
-    // corresponds to obj.items.[x].someArrayField.[y].field, which is what a list response looks like: it
-    // nests one level deeper than the single resource it wraps, because both the item array and the nested
-    // array spend a level.
-    //
-    // In a list response it also reaches one level into caller-owned blobs the API stores verbatim, so a
-    // listed request's `userData.foo.somethingAt` comes back as a `Date` rather than the string it was
-    // written as.
-    // TODO: Consider removing this limitation. It might came across as an annoying surprise as it's not communicated.
-    if (depth > 4) {
-        return input;
-    }
-    if (Array.isArray(input))
-        return input.map((child) => parseDateFields(child, shouldParseField, depth + 1));
-    if (!input || typeof input !== 'object')
-        return input;
-    return Object.entries(input).reduce((output, [k, v]) => {
-        const isValObject = !!v && typeof v === 'object';
-        if (k.endsWith('At') || (shouldParseField && shouldParseField(k))) {
-            if (v) {
-                const d = new Date(v);
-                output[k] = Number.isNaN(d.getTime()) ? v : d;
-            }
-            else {
-                output[k] = v;
-            }
-        }
-        else if (isValObject || Array.isArray(v)) {
-            output[k] = parseDateFields(v, shouldParseField, depth + 1);
-        }
-        else {
-            output[k] = v;
-        }
-        return output;
-    }, {});
+export function catchNotFoundForResourceOrThrow(err, resourceId) {
+    if (!resourceId)
+        throw err;
+    catchNotFoundOrThrow(err);
 }
 /**
  * Helper function that converts array of webhooks to base64 string
@@ -150,6 +160,28 @@ async function gzipValue(value) {
     }
     return gzipPromisified(value);
 }
+/**
+ * Decides whether a request body with the given content type is worth compressing.
+ *
+ * Images, audio, video and archives already carry their own compression. Running them through brotli or gzip
+ * burns CPU, holds a second full copy of the body in memory, and usually produces output slightly larger than
+ * the input. Formats that are raw despite such a media type, for example `image/bmp` or `audio/wav`, are still
+ * compressed. A body with no content type is assumed to be compressible.
+ * @internal
+ */
+export function isCompressibleContentType(contentType) {
+    if (!contentType)
+        return true;
+    // `Content-Type` is case-insensitive and may carry parameters, for example `text/plain; charset=utf-8`.
+    const mediaType = contentType.split(';', 1)[0].trim().toLowerCase();
+    if (COMPRESSIBLE_MEDIA_TYPES.has(mediaType))
+        return true;
+    if (COMPRESSIBLE_MEDIA_TYPE_SUFFIXES.some((suffix) => mediaType.endsWith(suffix)))
+        return true;
+    if (ALREADY_COMPRESSED_MEDIA_TYPES.has(mediaType))
+        return false;
+    return !ALREADY_COMPRESSED_MEDIA_TYPE_PREFIXES.some((prefix) => mediaType.startsWith(prefix));
+}
 /**
  * Compress the passed value using brotli, falling back to gzip. Returns undefined if the data is
  * too small / wrong type, or if neither algorithm is available.
@@ -181,28 +213,35 @@ export async function maybeCompressValue(value) {
     }
 }
 /**
- * Helper function slice the items from array to fit the max byte length.
+ * Returns the UTF-8 byte length of a string.
+ */
+export function utf8ByteLength(value) {
+    return isNode() ? Buffer.byteLength(value) : new Blob([value]).size;
+}
+/**
+ * Splits JSON-serialized items into consecutive batches of at most `maxCount` items, each of which fits into a JSON
+ * array body - the items joined by commas between brackets - of at most `maxByteLength` bytes. The `byteLength` of an
+ * item is the UTF-8 byte length of its serialization. An item too large for a body of its own still gets one, so a
+ * caller that cannot send such an item has to reject it beforehand.
  */
-export function sliceArrayByByteLength(array, maxByteLength, startIndex) {
-    const stringByteLength = (str) => (isNode() ? Buffer.byteLength(str) : new Blob([str]).size);
-    const arrayByteLength = stringByteLength(JSON.stringify(array));
-    if (arrayByteLength < maxByteLength)
-        return array;
-    const slicedArray = [];
-    let byteLength = 2; // 2 bytes for the empty array []
-    for (let i = 0; i < array.length; i++) {
-        const item = array[i];
-        const itemByteSize = stringByteLength(JSON.stringify(item));
-        if (itemByteSize > maxByteLength) {
-            throw new Error(`RequestQueueClient.batchAddRequests: The size of the request with index: ${startIndex + i} ` +
-                `exceeds the maximum allowed size (${maxByteLength} bytes).`);
+export function splitIntoJsonArrayBatches(items, { maxCount, maxByteLength }) {
+    const batches = [];
+    let batch = [];
+    // One byte for the opening bracket; each item then adds its own bytes plus one for the comma or the closing
+    // bracket that follows it.
+    let byteLength = 1;
+    for (const item of items) {
+        if (batch.length > 0 && (batch.length >= maxCount || byteLength + item.byteLength + 1 > maxByteLength)) {
+            batches.push(batch);
+            batch = [];
+            byteLength = 1;
         }
-        if (byteLength + itemByteSize >= maxByteLength)
-            break;
-        byteLength += itemByteSize;
-        slicedArray.push(item);
+        batch.push(item);
+        byteLength += item.byteLength + 1;
     }
-    return slicedArray;
+    if (batch.length > 0)
+        batches.push(batch);
+    return batches;
 }
 export function isNode() {
     if (typeof BROWSER_BUILD !== 'undefined')
@@ -232,34 +271,29 @@ export function getVersionData() {
     return packageJson;
 }
 /**
- * Helper class to create async iterators from paginated list endpoints with exclusive start key.
+ * Helper class to create async iterators from paginated list endpoints.
  */
 export class RequestQueuePaginationIterator {
-    maxPageLimit;
-    getPage;
-    limit;
-    exclusiveStartId;
-    cursor;
+    #maxPageLimit;
+    #getPage;
+    #limit;
+    #cursor;
     constructor(options) {
-        this.maxPageLimit = options.maxPageLimit;
-        this.limit = options.limit;
-        this.exclusiveStartId = options.exclusiveStartId;
-        this.cursor = options.cursor;
-        this.getPage = options.getPage;
+        this.#maxPageLimit = options.maxPageLimit;
+        this.#limit = options.limit;
+        this.#cursor = options.cursor;
+        this.#getPage = options.getPage;
     }
     async *[Symbol.asyncIterator]() {
-        let nextCursor = this.cursor;
-        // allow using exclusiveStartId for the first page, but then we'll delete it to avoid using it for any later page
-        let nextExclusiveStartId = this.exclusiveStartId;
+        let nextCursor = this.#cursor;
         let iterateItemCount = 0;
         while (true) {
-            const pageLimit = this.limit
-                ? Math.min(this.maxPageLimit, this.limit - iterateItemCount)
-                : this.maxPageLimit;
-            const page = await this.getPage({
+            const pageLimit = this.#limit
+                ? Math.min(this.#maxPageLimit, this.#limit - iterateItemCount)
+                : this.#maxPageLimit;
+            const page = await this.#getPage({
                 limit: pageLimit,
                 cursor: nextCursor,
-                exclusiveStartId: nextExclusiveStartId,
             });
             // There are no more pages to iterate
             if (page.items.length === 0)
@@ -267,10 +301,9 @@ export class RequestQueuePaginationIterator {
             yield page;
             iterateItemCount += page.items.length;
             // Limit reached stopping to iterate
-            if ((this.limit && iterateItemCount >= this.limit) || !page.nextCursor)
+            if ((this.#limit && iterateItemCount >= this.#limit) || !page.nextCursor)
                 return;
             nextCursor = page.nextCursor;
-            nextExclusiveStartId = undefined; // see comment above - delete it for any page after the first one, and paginate with cursor
         }
     }
 }
@@ -284,6 +317,16 @@ export const paginationOptionsShape = {
     offset: z.number().min(0).optional(),
     chunkSize: z.number().positive().optional(),
 };
+/**
+ * Key under which a page of dataset items carries the number of rows the API scanned to produce it, as a
+ * non-enumerable property that stays out of the page's public shape. The API applies `offset` and `limit` to the
+ * dataset's rows first and shapes the result afterwards: filters (`clean`, `skipEmpty`, `skipHidden`) drop items and
+ * `unwind` splits or drops them, so `items.length` can land on either side of the rows scanned. The
+ * `x-apify-pagination-count` header reports the scanned number, and the offset iterator advances and terminates by it
+ * alone. A page without the property falls back to `items.length`.
+ * @internal
+ */
+export const SCANNED_COUNT = Symbol('scannedCount');
 export function cast(input) {
     return input;
 }
@@ -310,15 +353,6 @@ export function applyQueryParamsToUrl(url, options) {
     }
     return url;
 }
-/**
- * Builds a `[check, message]` pair to spread into `.refine()`, asserting that at most one of `keys`
- * is present. Pass the options interface as `T`, so that a misspelled key is a type error.
- * @internal
- */
-export const mutuallyExclusive = (...keys) => [
-    (value) => keys.filter((key) => typeof value[key] !== 'undefined').length <= 1,
-    `At most one of the following fields is allowed: ${keys.join(', ')}`,
-];
 const pathSegmentSchema = z
     .string()
     .nonempty()