apify-client 3.0.0-beta.46 → 3.0.0-beta.47

package/dist/resource_clients/actor.d.ts

@@ -85,6 +85,8 @@ export declare class ActorClient extends ResourceClient {
      * @param options.webhooks - Webhooks to trigger when the Actor run reaches a specific state (e.g., `SUCCEEDED`, `FAILED`).
      * @param options.maxItems - Maximum number of dataset items that will be charged (only for pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (only for pay-per-event Actors).
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds.
      * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`, extended to cover `waitForFinish`
      * when the API is asked to hold the response.
      * @returns The Actor run object with status, usage, and storage IDs
@@ -119,6 +121,9 @@ export declare class ActorClient extends ResourceClient {
      * @param options.build - Tag or number of the build to run (e.g., `'beta'` or `'1.2.345'`).
      * @param options.memory - Memory in megabytes allocated for the run.
      * @param options.runTimeoutSecs - Maximum run duration in seconds.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds. The time spent
+     * retrying doesn't count toward `waitSecs`.
      * @param options.timeoutSecs - Timeout for each API request, the start and every poll alike. Default is `'noTimeout'`.
      * @returns The finished Actor run object with final status (`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`)
      * @see https://docs.apify.com/api/v2/act-runs-post
@@ -367,6 +372,20 @@ export interface ActorStartOptions extends TimeoutOptions {
      * @since Added in 2.17.0
      */
     forcePermissionLevel?: ACTOR_PERMISSION_LEVEL;
+    /**
+     * Retry the start while the account lacks the resources for the run, that is while the API rejects it with an
+     * `ApifyApiError` of type `actor-memory-limit-exceeded` or `concurrent-runs-limit-exceeded`. Both clear as
+     * other runs or builds finish. The start is retried every 10 seconds, and any other error is thrown right away.
+     *
+     * `true` retries until the run starts. A number stops retrying after that many seconds and throws the last
+     * error. Omitted or `false`, the first rejection is thrown.
+     *
+     * A run that requests more memory than the whole memory limit of the account is rejected with
+     * `actor-memory-limit-exceeded` as well and never starts, so `true` retries it forever.
+     *
+     * A `Readable` input can't be sent twice, so its start is never retried and the first rejection is thrown.
+     */
+    waitForResources?: boolean | number;
 }
 /**
  * Options for calling an Actor and waiting for it to finish.

package/dist/resource_clients/actor.js

@@ -4,7 +4,8 @@ import { Log } from '@apify/log';
 import { ResourceClient } from '../base/resource_client.js';
 import * as schemas from '../schemas.js';
 import { timeoutOptionsSchema, timeoutOptionsShape } from '../timeouts.js';
-import { anyObjectSchema, parseArgument, parseResponse, stringifyWebhooksToBase64 } from '../utils.js';
+import { anyObjectSchema, isStream, parseArgument, parseResponse, stringifyWebhooksToBase64 } from '../utils.js';
+import { startWaitingForResources } from '../wait_for_resources.js';
 import { ActorVersionClient } from './actor_version.js';
 import { ActorVersionCollectionClient } from './actor_version_collection.js';
 import { BuildClient } from './build.js';
@@ -23,6 +24,7 @@ const startOptionsSchema = z.strictObject({
     maxTotalChargeUsd: z.number().min(0).optional(),
     restartOnError: z.boolean().optional(),
     forcePermissionLevel: z.enum(ACTOR_PERMISSION_LEVEL).optional(),
+    waitForResources: z.union([z.boolean(), z.number().min(0)]).optional(),
     ...timeoutOptionsShape,
 });
 const callOptionsSchema = z.strictObject({
@@ -37,6 +39,7 @@ const callOptionsSchema = z.strictObject({
     log: z.union([z.null(), z.instanceof(Log), z.literal('default')]).optional(),
     restartOnError: z.boolean().optional(),
     forcePermissionLevel: z.enum(ACTOR_PERMISSION_LEVEL).optional(),
+    waitForResources: z.union([z.boolean(), z.number().min(0)]).optional(),
     ...timeoutOptionsShape,
 });
 const validateInputOptionsSchema = z.strictObject({
@@ -141,6 +144,8 @@ export class ActorClient extends ResourceClient {
      * @param options.webhooks - Webhooks to trigger when the Actor run reaches a specific state (e.g., `SUCCEEDED`, `FAILED`).
      * @param options.maxItems - Maximum number of dataset items that will be charged (only for pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (only for pay-per-event Actors).
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds.
      * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`, extended to cover `waitForFinish`
      * when the API is asked to hold the response.
      * @returns The Actor run object with status, usage, and storage IDs
@@ -161,7 +166,7 @@ export class ActorClient extends ResourceClient {
      */
     async start(input, options = {}) {
         const parsed = parseArgument(options, startOptionsSchema, 'ActorStartOptions');
-        const { waitForFinish, runTimeoutSecs, memory, build, maxItems, maxTotalChargeUsd, restartOnError, forcePermissionLevel, timeoutSecs, signal, } = parsed;
+        const { waitForFinish, runTimeoutSecs, memory, build, maxItems, maxTotalChargeUsd, restartOnError, forcePermissionLevel, waitForResources, timeoutSecs, signal, } = parsed;
         // The API's `timeout` parameter bounds the run, not the request.
         const params = {
             waitForFinish,
@@ -189,7 +194,8 @@ export class ActorClient extends ResourceClient {
                 'content-type': parsed.contentType,
             };
         }
-        const response = await this.httpClient.call(request);
+        // A `Readable` input is consumed by the first attempt, so a retry would start the run with an empty input.
+        const response = await startWaitingForResources(async () => this.httpClient.call(request), isStream(input) ? false : waitForResources, this.httpClient.logger, signal);
         return parseResponse(response, schemas.Run());
     }
     /**
@@ -207,6 +213,9 @@ export class ActorClient extends ResourceClient {
      * @param options.build - Tag or number of the build to run (e.g., `'beta'` or `'1.2.345'`).
      * @param options.memory - Memory in megabytes allocated for the run.
      * @param options.runTimeoutSecs - Maximum run duration in seconds.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds. The time spent
+     * retrying doesn't count toward `waitSecs`.
      * @param options.timeoutSecs - Timeout for each API request, the start and every poll alike. Default is `'noTimeout'`.
      * @returns The finished Actor run object with final status (`SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`)
      * @see https://docs.apify.com/api/v2/act-runs-post

package/dist/resource_clients/task.d.ts

@@ -103,6 +103,8 @@ export declare class TaskClient extends ResourceClient {
      * @param options.maxItems - Maximum number of dataset items (for pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (for pay-per-event Actors).
      * @param options.restartOnError - Whether to restart the run on error.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds.
      * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`, extended to cover `waitForFinish`
      * when the API is asked to hold the response.
      * @returns The Actor Run object.
@@ -123,6 +125,9 @@ export declare class TaskClient extends ResourceClient {
      * @param options.maxItems - Maximum number of dataset items (for pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (for pay-per-event Actors).
      * @param options.restartOnError - Whether to restart the run on error.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds. The time spent
+     * retrying doesn't count toward `waitSecs`.
      * @param options.timeoutSecs - Timeout for each API request, the start and every poll alike. Default is `'noTimeout'`.
      * @returns The Actor run object.
      * @see https://docs.apify.com/api/v2/actor-task-runs-post

package/dist/resource_clients/task.js

@@ -3,7 +3,8 @@ import { ACT_JOB_STATUSES, META_ORIGINS } from '@apify/consts';
 import { ResourceClient } from '../base/resource_client.js';
 import * as schemas from '../schemas.js';
 import { timeoutOptionsSchema, timeoutOptionsShape } from '../timeouts.js';
-import { anyObjectSchema, cast, parseArgument, parseResponse, stringifyWebhooksToBase64 } from '../utils.js';
+import { anyObjectSchema, cast, isStream, parseArgument, parseResponse, stringifyWebhooksToBase64 } from '../utils.js';
+import { startWaitingForResources } from '../wait_for_resources.js';
 import { RunClient } from './run.js';
 import { RunCollectionClient } from './run_collection.js';
 import { WebhookCollectionClient } from './webhook_collection.js';
@@ -17,6 +18,7 @@ const startOptionsSchema = z.strictObject({
     maxItems: z.number().min(0).optional(),
     maxTotalChargeUsd: z.number().min(0).optional(),
     restartOnError: z.boolean().optional(),
+    waitForResources: z.union([z.boolean(), z.number().min(0)]).optional(),
     ...timeoutOptionsShape,
 });
 const callOptionsSchema = z.strictObject({
@@ -28,6 +30,7 @@ const callOptionsSchema = z.strictObject({
     maxItems: z.number().min(0).optional(),
     maxTotalChargeUsd: z.number().min(0).optional(),
     restartOnError: z.boolean().optional(),
+    waitForResources: z.union([z.boolean(), z.number().min(0)]).optional(),
     ...timeoutOptionsShape,
 });
 const lastRunOptionsSchema = z.strictObject({
@@ -148,6 +151,8 @@ export class TaskClient extends ResourceClient {
      * @param options.maxItems - Maximum number of dataset items (for pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (for pay-per-event Actors).
      * @param options.restartOnError - Whether to restart the run on error.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds.
      * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`, extended to cover `waitForFinish`
      * when the API is asked to hold the response.
      * @returns The Actor Run object.
@@ -156,7 +161,7 @@ export class TaskClient extends ResourceClient {
     async start(input, options = {}) {
         parseArgument(input, inputSchema);
         const parsed = parseArgument(options, startOptionsSchema, 'TaskStartOptions');
-        const { waitForFinish, runTimeoutSecs, memory, build, maxItems, maxTotalChargeUsd, restartOnError, timeoutSecs, signal, } = parsed;
+        const { waitForFinish, runTimeoutSecs, memory, build, maxItems, maxTotalChargeUsd, restartOnError, waitForResources, timeoutSecs, signal, } = parsed;
         // The API's `timeout` parameter bounds the run, not the request.
         const params = {
             waitForFinish,
@@ -181,7 +186,8 @@ export class TaskClient extends ResourceClient {
             timeoutSecs: this.timeoutForWaitForFinish(timeoutSecs, 'medium', waitForFinish),
             signal,
         };
-        const response = await this.httpClient.call(request);
+        // A `Readable` input is consumed by the first attempt, so a retry would start the run with an empty input.
+        const response = await startWaitingForResources(async () => this.httpClient.call(request), isStream(input) ? false : waitForResources, this.httpClient.logger, signal);
         return parseResponse(response, schemas.Run());
     }
     /**
@@ -198,6 +204,9 @@ export class TaskClient extends ResourceClient {
      * @param options.maxItems - Maximum number of dataset items (for pay-per-result Actors).
      * @param options.maxTotalChargeUsd - Maximum cost in USD (for pay-per-event Actors).
      * @param options.restartOnError - Whether to restart the run on error.
+     * @param options.waitForResources - Retry the start while the account lacks the memory or a concurrent-run slot for
+     * the run. `true` retries until the run starts, a number stops retrying after that many seconds. The time spent
+     * retrying doesn't count toward `waitSecs`.
      * @param options.timeoutSecs - Timeout for each API request, the start and every poll alike. Default is `'noTimeout'`.
      * @returns The Actor run object.
      * @see https://docs.apify.com/api/v2/actor-task-runs-post

package/dist/wait_for_resources.d.ts

@@ -0,0 +1,8 @@
+import type { Log } from '@apify/log';
+/**
+ * Makes the `start` request, retrying it every {@link WAIT_FOR_RESOURCES_COOLDOWN_MILLIS} while it fails with one of
+ * {@link RESOURCE_LIMIT_ERROR_TYPES}. `true` retries until the request succeeds, a number of seconds bounds the
+ * retrying, after which the last error is thrown. Any other error is thrown right away.
+ * @internal
+ */
+export declare function startWaitingForResources<T>(start: () => Promise<T>, waitForResources: boolean | number | undefined, logger: Log, signal?: AbortSignal): Promise<T>;

package/dist/wait_for_resources.js

@@ -0,0 +1,39 @@
+import { ApifyApiError } from './apify_api_error.js';
+import { sleep } from './utils.js';
+/**
+ * Error types the API rejects a run start with while the account has no free memory or concurrent-run slot for it.
+ * Both clear as other runs or builds finish.
+ */
+const RESOURCE_LIMIT_ERROR_TYPES = new Set([
+    'actor-memory-limit-exceeded',
+    'concurrent-runs-limit-exceeded',
+]);
+/** Cooldown between two attempts to start a run that was rejected for lack of resources. */
+const WAIT_FOR_RESOURCES_COOLDOWN_MILLIS = 10_000;
+/**
+ * Makes the `start` request, retrying it every {@link WAIT_FOR_RESOURCES_COOLDOWN_MILLIS} while it fails with one of
+ * {@link RESOURCE_LIMIT_ERROR_TYPES}. `true` retries until the request succeeds, a number of seconds bounds the
+ * retrying, after which the last error is thrown. Any other error is thrown right away.
+ * @internal
+ */
+export async function startWaitingForResources(start, waitForResources, logger, signal) {
+    if (!waitForResources)
+        return start();
+    const deadline = waitForResources === true ? Infinity : Date.now() + waitForResources * 1000;
+    for (;;) {
+        try {
+            return await start();
+        }
+        catch (err) {
+            if (!(err instanceof ApifyApiError) || !RESOURCE_LIMIT_ERROR_TYPES.has(err.type ?? ''))
+                throw err;
+            const remainingMillis = deadline - Date.now();
+            if (remainingMillis <= 0)
+                throw err;
+            const delayMillis = Math.min(WAIT_FOR_RESOURCES_COOLDOWN_MILLIS, remainingMillis);
+            logger.info(`Not enough resources to start the run, retrying in ${Number((delayMillis / 1000).toPrecision(3))}s: ${err.message}`);
+            await sleep(delayMillis, signal);
+            signal?.throwIfAborted();
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify-client",
-  "version": "3.0.0-beta.46",
+  "version": "3.0.0-beta.47",
   "description": "Apify API client for JavaScript",
   "engines": {
     "node": ">=22.13.0"