refactor!: remove all deprecated options (#1039)

Removes every option the client had deprecated for v3.

- `ActorVersionCollectionClient.list()` and
`ActorEnvVarCollectionClient.list()` take no arguments. Neither endpoint
ever read `offset`, `limit` or `desc`, and both return every item in one
response.
- `ActorCollectionCreateOptions.restartOnError`. Use
`defaultRunOptions.restartOnError`.
- `exclusiveStartId` on `listRequests()` and `paginateRequests()`. Use
`cursor`.

BREAKING CHANGE: `ActorVersionCollectionClient.list()` and
`ActorEnvVarCollectionClient.list()` take no arguments, and
`ActorVersionCollectionListOptions` and
`ActorEnvVarCollectionListOptions` are removed with the `offset`,
`limit`, `desc` and `chunkSize` they declared.
`ActorCollectionCreateOptions.restartOnError` is removed; use
`defaultRunOptions.restartOnError`. `exclusiveStartId` is removed from
`listRequests()` and `paginateRequests()`; use `cursor`.

Closes #799

*✍️ Drafted by Claude Code*

Author: vdusek

docs/04_upgrading/upgrading_v3.md

@@ -86,7 +86,7 @@ This affects numeric options such as `waitSecs`, `timeout` and `memory`, and dat
 
 Some options were declared in the TypeScript types but always rejected by the client's own validation before a request was ever sent: `chunkSize` on `DatasetClient.downloadItems()` and `createItemsPublicUrl()`, and `signature` on `createItemsPublicUrl()` and `createKeysPublicUrl()`. These are no longer part of the option types, so passing them is now a compile-time error instead of a runtime throw.
 
-The reverse also happened: `chunkSize` now works on every paginating `list()` method. In v2 only `DatasetClient.listItems()` accepted it - everywhere else it type-checked and then threw.
+The reverse also happened: `chunkSize` now works on every `list()` method that takes pagination options. In v2 only `DatasetClient.listItems()` accepted it - everywhere else it type-checked and then threw.
 
 ## API errors are thrown as subclasses of `ApifyApiError`
 
@@ -175,3 +175,15 @@ Two return types change as a result of describing what the endpoints really retu
 
 - <ApiLink to="class/ScheduleClient#getLog">`ScheduleClient.getLog()`</ApiLink> was typed as a `string`, even though the endpoint returns the log as a list of entries. It's now typed as <ApiLink to="interface/ScheduleInvoked">`ScheduleInvoked[]`</ApiLink>, each entry carrying `message`, `level` and `createdAt`.
 - <ApiLink to="interface/TaskPublicConfig">`TaskPublicConfig`</ApiLink> now follows the specification: `publishedAt` is optional and read-only, and `categorization`, which the specification doesn't describe, is gone from the type.
+
+## `versions().list()` and `envVars().list()` take no options
+
+<ApiLink to="class/ActorVersionCollectionClient#list">`ActorVersionCollectionClient.list()`</ApiLink> and <ApiLink to="class/ActorEnvVarCollectionClient#list">`ActorEnvVarCollectionClient.list()`</ApiLink> now take no arguments. Neither endpoint reads `offset`, `limit` or `desc`, and both return every item in one response, so `chunkSize` had nothing to size either. The `ActorVersionCollectionListOptions` and `ActorEnvVarCollectionListOptions` types that declared those four options, deprecated since v2.21.0, are gone from the package. A call that passed an options object no longer compiles. Drop the argument and the call returns the same items as before.
+
+## The last deprecated options are gone
+
+Two options that carried a `@deprecated` marker throughout v2 have been removed.
+
+`restartOnError` is gone from <ApiLink to="interface/ActorCollectionCreateOptions">`ActorCollectionCreateOptions`</ApiLink>, so <ApiLink to="class/ActorCollectionClient#create">`ActorCollectionClient.create()`</ApiLink> no longer accepts it at the top level. Pass it inside `defaultRunOptions` instead, as the deprecation notice advised.
+
+`exclusiveStartId` is gone from <ApiLink to="class/RequestQueueClient#listRequests">`listRequests()`</ApiLink> and <ApiLink to="class/RequestQueueClient#paginateRequests">`paginateRequests()`</ApiLink>. Both paginate by `cursor` alone now, and passing `exclusiveStartId` throws an `ArgumentValidationError` about an unrecognized key. In v2 the two were mutually exclusive, so the error about combining them is gone as well. Responses are unaffected, since the API still echoes `exclusiveStartId` back in the request listing.

docs/public-api/apify-client.api.md

@@ -124,8 +124,6 @@ export interface ActorCollectionCreateOptions {
     isPublic?: boolean;
     // (undocumented)
     name?: string;
-    // @deprecated (undocumented)
-    restartOnError?: boolean;
     seoDescription?: string;
     seoTitle?: string;
     // (undocumented)
@@ -194,13 +192,7 @@ export class ActorEnvVarClient extends ResourceClient {
 export class ActorEnvVarCollectionClient extends ResourceCollectionClient {
     constructor(options: ApiClientSubResourceOptions);
     create(actorEnvVar: ActorEnvironmentVariable): Promise<ActorEnvironmentVariable>;
-    list(_options?: ActorEnvVarCollectionListOptions): Promise<ActorEnvVarListResult> & AsyncIterable<ActorEnvironmentVariable>;
-}
-
-// @public @deprecated (undocumented)
-export interface ActorEnvVarCollectionListOptions extends PaginationOptions {
-    // (undocumented)
-    desc?: boolean;
+    list(): Promise<ActorEnvVarListResult> & AsyncIterable<ActorEnvironmentVariable>;
 }
 
 // @public
@@ -429,13 +421,7 @@ interface ActorVersionClientNarrowings {
 export class ActorVersionCollectionClient extends ResourceCollectionClient {
     constructor(options: ApiClientSubResourceOptions);
     create(actorVersion: ActorVersion): Promise<FinalActorVersion>;
-    list(_options?: ActorVersionCollectionListOptions): Promise<ActorVersionListResult> & AsyncIterable<FinalActorVersion>;
-}
-
-// @public @deprecated (undocumented)
-export interface ActorVersionCollectionListOptions extends PaginationOptions {
-    // (undocumented)
-    desc?: boolean;
+    list(): Promise<ActorVersionListResult> & AsyncIterable<FinalActorVersion>;
 }
 
 // @public
@@ -3379,8 +3365,6 @@ export interface RequestQueueClientListItem extends GeneratedHeadRequest {
 // @public
 export interface RequestQueueClientListRequestsOptions {
     cursor?: string;
-    // @deprecated
-    exclusiveStartId?: string;
     filter?: readonly RequestQueueListRequestsFilter[];
     // (undocumented)
     limit?: number;
@@ -3404,8 +3388,6 @@ export interface RequestQueueClientLockedListItem extends GeneratedLockedHeadReq
 // @public
 export interface RequestQueueClientPaginateRequestsOptions {
     cursor?: string;
-    // @deprecated (undocumented)
-    exclusiveStartId?: string;
     filter?: readonly RequestQueueListRequestsFilter[];
     // (undocumented)
     limit?: number;

src/resource_clients/actor_collection.ts

@@ -136,8 +136,6 @@ export interface ActorCollectionCreateOptions {
     isDeprecated?: boolean;
     isPublic?: boolean;
     name?: string;
-    /** @deprecated Use defaultRunOptions.restartOnError instead */
-    restartOnError?: boolean;
     /**
      * @since Added in 2.8.6
      */

src/resource_clients/actor_env_var_collection.ts

@@ -1,6 +1,6 @@
 import type { ApiClientSubResourceOptions } from '../base/api_client.js';
 import { ResourceCollectionClient } from '../base/resource_collection_client.js';
-import type { PaginatedList, PaginationOptions } from '../utils.js';
+import type { PaginatedList } from '../utils.js';
 import * as schemas from '../schemas.js';
 import { anyObjectSchema, parseArgument } from '../utils.js';
 import type { ActorEnvironmentVariable } from './actor_version.js';
@@ -48,25 +48,22 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient {
     /**
      * Lists all environment variables of this Actor version.
      *
-     * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched
-     * items in a single API call is limited.
+     * The endpoint returns every environment variable in one response, so awaiting the return value (as you would
+     * with a Promise) gets the whole list.
      * ```javascript
-     * const paginatedList = await client.list();
-     *```
+     * const { items } = await client.list();
+     * ```
      *
-     * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are
-     * retrieved.
+     * Asynchronous iteration is also supported, and yields the environment variables one by one.
      *
      * ```javascript
      * for await (const singleItem of client.list()) {...}
      * ```
      *
-     * @returns A paginated iterator of environment variables.
+     * @returns The environment variables, awaitable as a whole list or iterable one by one.
      * @see https://docs.apify.com/api/v2/act-version-env-vars-get
      */
-    list(
-        _options: ActorEnvVarCollectionListOptions = {},
-    ): Promise<ActorEnvVarListResult> & AsyncIterable<ActorEnvironmentVariable> {
+    list(): Promise<ActorEnvVarListResult> & AsyncIterable<ActorEnvironmentVariable> {
         return this._listPaginated(schemas.ListOfEnvVars());
     }
 
@@ -83,15 +80,6 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient {
     }
 }
 
-/**
- * @deprecated No options are used in the current API implementation.
- * https://github.com/apify/apify-client-js/issues/799
- * @since Added in 2.1.0
- */
-export interface ActorEnvVarCollectionListOptions extends PaginationOptions {
-    desc?: boolean;
-}
-
 /**
  * @since Added in 2.1.0
  */

src/resource_clients/actor_version_collection.ts

@@ -1,6 +1,6 @@
 import type { ApiClientSubResourceOptions } from '../base/api_client.js';
 import { ResourceCollectionClient } from '../base/resource_collection_client.js';
-import type { PaginatedList, PaginationOptions } from '../utils.js';
+import type { PaginatedList } from '../utils.js';
 import * as schemas from '../schemas.js';
 import { anyObjectSchema, parseArgument } from '../utils.js';
 import type { ActorVersion, FinalActorVersion } from './actor_version.js';
@@ -45,25 +45,22 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient {
     /**
      * Lists all Actor versions.
      *
-     * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched
-     * items in a single API call is limited.
+     * The endpoint returns every version in one response, so awaiting the return value (as you would with a Promise)
+     * gets the whole list.
      * ```javascript
-     * const paginatedList = await client.list();
-     *```
+     * const { items } = await client.list();
+     * ```
      *
-     * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are
-     * retrieved.
+     * Asynchronous iteration is also supported, and yields the versions one by one.
      *
      * ```javascript
      * for await (const singleItem of client.list()) {...}
      * ```
      *
-     * @returns A paginated iterator of Actor versions.
+     * @returns The Actor versions, awaitable as a whole list or iterable one by one.
      * @see https://docs.apify.com/api/v2/act-versions-get
      */
-    list(
-        _options: ActorVersionCollectionListOptions = {},
-    ): Promise<ActorVersionListResult> & AsyncIterable<FinalActorVersion> {
+    list(): Promise<ActorVersionListResult> & AsyncIterable<FinalActorVersion> {
         return this._listPaginated(schemas.ListOfVersions());
     }
 
@@ -81,12 +78,4 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient {
     }
 }
 
-/**
- * @deprecated No options are used in the current API implementation.
- * https://github.com/apify/apify-client-js/issues/799
- */
-export interface ActorVersionCollectionListOptions extends PaginationOptions {
-    desc?: boolean;
-}
-
 export type ActorVersionListResult = Pick<PaginatedList<FinalActorVersion>, 'total' | 'items'>;

src/resource_clients/request_queue.ts

@@ -30,7 +30,6 @@ import {
     cast,
     catchNotFoundOrThrow,
     isNonArrayObject,
-    mutuallyExclusive,
     parseArgument,
     parseDateFields,
     parseResponse,
@@ -78,23 +77,17 @@ const prolongRequestLockOptionsSchema = z.strictObject({
     forefront: z.boolean().optional(),
 });
 const requestFilterSchema = z.array(z.enum(['locked', 'pending'])).min(1);
-const listRequestsOptionsSchema = z
-    .strictObject({
-        limit: z.number().min(0).optional(),
-        exclusiveStartId: z.string().optional(),
-        cursor: z.string().optional(),
-        filter: requestFilterSchema.optional(),
-    })
-    .refine(...mutuallyExclusive<RequestQueueClientListRequestsOptions>('exclusiveStartId', 'cursor'));
-const paginateRequestsOptionsSchema = z
-    .strictObject({
-        limit: z.number().min(0).optional(),
-        maxPageLimit: z.number().default(DEFAULT_REQUEST_QUEUE_REQUEST_PAGE_LIMIT),
-        exclusiveStartId: z.string().optional(),
-        cursor: z.string().optional(),
-        filter: requestFilterSchema.optional(),
-    })
-    .refine(...mutuallyExclusive<RequestQueueClientPaginateRequestsOptions>('exclusiveStartId', 'cursor'));
+const listRequestsOptionsSchema = z.strictObject({
+    limit: z.number().min(0).optional(),
+    cursor: z.string().optional(),
+    filter: requestFilterSchema.optional(),
+});
+const paginateRequestsOptionsSchema = z.strictObject({
+    limit: z.number().min(0).optional(),
+    maxPageLimit: z.number().default(DEFAULT_REQUEST_QUEUE_REQUEST_PAGE_LIMIT),
+    cursor: z.string().optional(),
+    filter: requestFilterSchema.optional(),
+});
 
 export type {
     AllowedHttpMethods,
@@ -749,8 +742,6 @@ export class RequestQueueClient extends ResourceClient {
                 const newOptions = {
                     ...parsed,
                     limit: remainingItems,
-                    // remove original exclusiveStartId, if there was any, and use cursor-based pagination
-                    exclusiveStartId: undefined,
                     cursor: currentPage.nextCursor,
                 };
                 currentPage = await getPaginatedList(newOptions);
@@ -810,15 +801,14 @@ export class RequestQueueClient extends ResourceClient {
     paginateRequests(
         options: RequestQueueClientPaginateRequestsOptions = {},
     ): RequestQueueRequestsAsyncIterable<RequestQueueClientListRequestsResult> {
-        const { limit, exclusiveStartId, cursor, filter, maxPageLimit } = parseArgument(
+        const { limit, cursor, filter, maxPageLimit } = parseArgument(
             options,
             paginateRequestsOptionsSchema,
             'RequestQueueClientPaginateRequestsOptions',
         );
         return new RequestQueuePaginationIterator({
             getPage: async (pageOptions) => this.listRequests({ ...pageOptions, filter }),
             limit,
-            exclusiveStartId,
             cursor,
             maxPageLimit,
         });
@@ -869,11 +859,6 @@ export type RequestQueueListRequestsFilter = 'locked' | 'pending';
  */
 export interface RequestQueueClientListRequestsOptions {
     limit?: number;
-    /**
-     * Using id of request that does not exist in request queue leads to unpredictable results.
-     * @deprecated Use `cursor` for pagination instead.
-     */
-    exclusiveStartId?: string;
     /**
      * @since Added in 2.23.2
      */
@@ -891,8 +876,6 @@ export interface RequestQueueClientListRequestsOptions {
 export interface RequestQueueClientPaginateRequestsOptions {
     limit?: number;
     maxPageLimit?: number;
-    /** @deprecated Use `cursor` for pagination instead. */
-    exclusiveStartId?: string;
     /**
      * @since Added in 2.23.2
      */

src/utils.ts

@@ -287,7 +287,7 @@ export 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 class RequestQueuePaginationIterator {
     private readonly maxPageLimit: number;
@@ -298,22 +298,17 @@ export class RequestQueuePaginationIterator {
 
     private readonly limit?: number;
 
-    private readonly exclusiveStartId?: string;
     private readonly cursor?: string;
 
     constructor(options: RequestQueuePaginationIteratorOptions) {
         this.maxPageLimit = options.maxPageLimit;
         this.limit = options.limit;
-        this.exclusiveStartId = options.exclusiveStartId;
         this.cursor = options.cursor;
         this.getPage = options.getPage;
     }
 
     async *[Symbol.asyncIterator](): AsyncIterator<RequestQueueClientListRequestsResult> {
         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 iterateItemCount = 0;
         while (true) {
             const pageLimit = this.limit
@@ -323,7 +318,6 @@ export class RequestQueuePaginationIterator {
             const page: RequestQueueClientListRequestsResult = await this.getPage({
                 limit: pageLimit,
                 cursor: nextCursor,
-                exclusiveStartId: nextExclusiveStartId,
             });
             // There are no more pages to iterate
             if (page.items.length === 0) return;
@@ -333,7 +327,6 @@ export class RequestQueuePaginationIterator {
             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
         }
     }
 }
@@ -350,7 +343,6 @@ export interface RequestQueuePaginationIteratorOptions {
     maxPageLimit: number;
     getPage: (opts: RequestQueueClientListRequestsOptions) => Promise<RequestQueueClientListRequestsResult>;
     limit?: number;
-    exclusiveStartId?: string;
     cursor?: string;
 }
 
@@ -471,16 +463,6 @@ export function applyQueryParamsToUrl(
     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 = <T extends object>(...keys: (keyof T & string)[]): [(value: T) => boolean, string] => [
-    (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()