apify 4.0.0-beta.29 → 4.0.0-beta.31

package/dist/actor.d.ts

@@ -11,7 +11,7 @@ import type { ConfigurationOptions } from './configuration.js';
 import { Configuration } from './configuration.js';
 import type { ProxyConfigurationOptions } from './proxy_configuration.js';
 import { ProxyConfiguration } from './proxy_configuration.js';
-import type { OpenStorageOptions, StorageIdentifier, StorageIdentifierWithoutAlias } from './storage.js';
+import type { OpenStorageOptions, StorageIdentifier } from './storage.js';
 export interface InitOptions {
     storage?: StorageBackend;
     /**
@@ -358,12 +358,6 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      */
     private gracefulShutdownHandlers;
     private chargingManager;
-    /**
-     * Tracks which aliased storages have been purged during this session,
-     * so we only purge them once (on first open) when running locally.
-     * @internal
-     */
-    purgedStorageAliases: Set<string>;
     /** How Apify platform request queues are consumed; set from {@link InitOptions.requestQueueAccess}. */
     private requestQueueAccess;
     constructor(options?: ActorOptions);
@@ -623,8 +617,8 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param [datasetIdOrName]
      *   ID, name, or alias of the dataset to be opened. If `null` or `undefined`,
      *   the function returns the default dataset associated with the Actor run.
-     *   You can also pass `{ alias: 'name' }` to open a dataset defined in the Actor's schema storages,
-     *   `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
@@ -735,13 +729,14 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * For more details and code examples, see the {@link KeyValueStore} class.
      *
      * @param [storeIdOrName]
-     *   ID or name of the key-value store to be opened. If `null` or `undefined`,
+     *   ID, name, or alias of the key-value store to be opened. If `null` or `undefined`,
      *   the function returns the default key-value store associated with the Actor run.
-     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
-    openKeyValueStore(storeIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
+    openKeyValueStore(storeIdOrName?: StorageIdentifier | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
     /**
      * Opens a request queue and returns a promise resolving to an instance
      * of the {@link RequestQueue} class.
@@ -754,13 +749,14 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * For more details and code examples, see the {@link RequestQueue} class.
      *
      * @param [queueIdOrName]
-     *   ID or name of the request queue to be opened. If `null` or `undefined`,
+     *   ID, name, or alias of the request queue to be opened. If `null` or `undefined`,
      *   the function returns the default request queue associated with the Actor run.
-     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
-    openRequestQueue(queueIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<RequestQueue>;
+    openRequestQueue(queueIdOrName?: StorageIdentifier | null, options?: OpenStorageOptions): Promise<RequestQueue>;
     /**
      * Creates a proxy configuration and returns a promise resolving to an instance
      * of the {@link ProxyConfiguration} class that is already initialized.
@@ -1168,8 +1164,8 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      * @param [datasetIdOrName]
      *   ID, name, or alias of the dataset to be opened. If `null` or `undefined`,
      *   the function returns the default dataset associated with the Actor run.
-     *   You can also pass `{ alias: 'name' }` to open a dataset defined in the Actor's schema storages,
-     *   `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      */
     static openDataset<Data extends Dictionary = Dictionary>(datasetIdOrName?: StorageIdentifier | null, options?: OpenStorageOptions): Promise<Dataset<Data>>;
@@ -1280,7 +1276,7 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      */
-    static openKeyValueStore(storeIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
+    static openKeyValueStore(storeIdOrName?: StorageIdentifier | null, options?: OpenStorageOptions): Promise<KeyValueStore>;
     /**
      * Opens a request queue and returns a promise resolving to an instance
      * of the {@link RequestQueue} class.
@@ -1298,7 +1294,7 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
      *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      */
-    static openRequestQueue(queueIdOrName?: StorageIdentifierWithoutAlias | null, options?: OpenStorageOptions): Promise<RequestQueue>;
+    static openRequestQueue(queueIdOrName?: StorageIdentifier | null, options?: OpenStorageOptions): Promise<RequestQueue>;
     /**
      * Creates a proxy configuration and returns a promise resolving to an instance
      * of the {@link ProxyConfiguration} class that is already initialized.
@@ -1390,7 +1386,6 @@ export declare class Actor<Data extends Dictionary = Dictionary> {
     private usesPushDataInterception;
     private pushDataViaInterceptedClient;
     private pushDataWithExplicitCharging;
-    private _openStorage;
     private createApifyStorageBackend;
     private _ensureActorInit;
     /**

package/dist/actor.js

@@ -7,14 +7,14 @@ import { ACTOR_ENV_VARS, ACTOR_EVENT_NAMES, APIFY_ENV_VARS, INTEGER_ENV_VARS, }
 import { decryptInputSecrets } from '@apify/input_secrets';
 import log from '@apify/log';
 import { addTimeoutToPromise } from '@apify/timeout';
+import { parseArgument } from '@apify/validations';
 import { ApifyStorageBackend, pushDataChargingContext, USES_PUSH_DATA_INTERCEPTION, } from './apify_storage_backend.js';
 import { ChargingManager, pushDataAndCharge } from './charging.js';
 import { Configuration } from './configuration.js';
 import { getDefaultsFromInputSchema, noActorInputSchemaDefinedMarker, readInputSchema } from './input-schemas.js';
 import { PlatformEventManager } from './platform_event_manager.js';
 import { ProxyConfiguration } from './proxy_configuration.js';
-import { openStorage } from './storage.js';
-import { checkCrawleeVersion, getSystemInfo, isNonEmptyObject, printOutdatedSdkWarning, snakeCaseToCamelCase, validate, } from './utils.js';
+import { checkCrawleeVersion, getSystemInfo, isNonEmptyObject, printOutdatedSdkWarning, snakeCaseToCamelCase, } from './utils.js';
 /**
  * Exit codes for the Actor process.
  * The error codes must be in the range 1-128, to avoid collision with signal exits
@@ -75,12 +75,6 @@ export class Actor {
      */
     #statusMessageForwarder;
     chargingManager;
-    /**
-     * Tracks which aliased storages have been purged during this session,
-     * so we only purge them once (on first open) when running locally.
-     * @internal
-     */
-    purgedStorageAliases = new Set();
     /** How Apify platform request queues are consumed; set from {@link InitOptions.requestQueueAccess}. */
     requestQueueAccess = 'single';
     constructor(options = {}) {
@@ -546,7 +540,7 @@ export class Actor {
      * @ignore
      */
     async addWebhook(options) {
-        validate(z
+        parseArgument(options, z
             .object({
             eventTypes: z.array(z.string()),
             requestUrl: z.string(),
@@ -559,7 +553,7 @@ export class Actor {
             shouldInterpolateStrings: z.boolean().optional(),
             isApifyIntegration: z.boolean().optional(),
         })
-            .strict(), options);
+            .strict());
         if (!this.isAtHome()) {
             log.warning('Actor.addWebhook() is only supported when running on the Apify platform. The webhook will not be invoked.');
             return undefined;
@@ -585,8 +579,8 @@ export class Actor {
      */
     async setStatusMessage(statusMessage, options) {
         const { isStatusMessageTerminal, level } = options || {};
-        validate(z.string(), statusMessage);
-        validate(z.boolean().optional(), isStatusMessageTerminal);
+        parseArgument(statusMessage, z.string());
+        parseArgument(isStatusMessageTerminal, z.boolean().optional());
         this._ensureActorInit('setStatusMessage');
         const loggedStatusMessage = `[Status message]: ${statusMessage}`;
         switch (level) {
@@ -673,15 +667,17 @@ export class Actor {
      * @param [datasetIdOrName]
      *   ID, name, or alias of the dataset to be opened. If `null` or `undefined`,
      *   the function returns the default dataset associated with the Actor run.
-     *   You can also pass `{ alias: 'name' }` to open a dataset defined in the Actor's schema storages,
-     *   `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
     async openDataset(datasetIdOrName, options = {}) {
-        validate(z.object({ forceCloud: z.boolean().optional() }).strict(), options);
+        parseArgument(options, z.object({ forceCloud: z.boolean().optional() }).strict());
         this._ensureActorInit('openDataset');
-        return this._openStorage(Dataset, datasetIdOrName, options);
+        return Dataset.open(datasetIdOrName ?? null, {
+            storageBackend: options.forceCloud ? this.createApifyStorageBackend() : undefined,
+        });
     }
     /**
      * Gets a value from the default {@link KeyValueStore} associated with the current Actor run.
@@ -819,16 +815,19 @@ export class Actor {
      * For more details and code examples, see the {@link KeyValueStore} class.
      *
      * @param [storeIdOrName]
-     *   ID or name of the key-value store to be opened. If `null` or `undefined`,
+     *   ID, name, or alias of the key-value store to be opened. If `null` or `undefined`,
      *   the function returns the default key-value store associated with the Actor run.
-     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
     async openKeyValueStore(storeIdOrName, options = {}) {
-        validate(z.object({ forceCloud: z.boolean().optional() }).strict(), options);
+        parseArgument(options, z.object({ forceCloud: z.boolean().optional() }).strict());
         this._ensureActorInit('openKeyValueStore');
-        return this._openStorage(KeyValueStore, storeIdOrName, options);
+        return KeyValueStore.open(storeIdOrName ?? null, {
+            storageBackend: options.forceCloud ? this.createApifyStorageBackend() : undefined,
+        });
     }
     /**
      * Opens a request queue and returns a promise resolving to an instance
@@ -842,17 +841,19 @@ export class Actor {
      * For more details and code examples, see the {@link RequestQueue} class.
      *
      * @param [queueIdOrName]
-     *   ID or name of the request queue to be opened. If `null` or `undefined`,
+     *   ID, name, or alias of the request queue to be opened. If `null` or `undefined`,
      *   the function returns the default request queue associated with the Actor run.
-     *   You can also pass `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      * @ignore
      */
     async openRequestQueue(queueIdOrName, options = {}) {
-        validate(z.object({ forceCloud: z.boolean().optional() }).strict(), options);
+        parseArgument(options, z.object({ forceCloud: z.boolean().optional() }).strict());
         this._ensureActorInit('openRequestQueue');
-        const queue = await this._openStorage(RequestQueue, queueIdOrName, options);
-        return queue;
+        return RequestQueue.open(queueIdOrName ?? null, {
+            storageBackend: options.forceCloud ? this.createApifyStorageBackend() : undefined,
+        });
     }
     /**
      * Creates a proxy configuration and returns a promise resolving to an instance
@@ -1342,8 +1343,8 @@ export class Actor {
      * @param [datasetIdOrName]
      *   ID, name, or alias of the dataset to be opened. If `null` or `undefined`,
      *   the function returns the default dataset associated with the Actor run.
-     *   You can also pass `{ alias: 'name' }` to open a dataset defined in the Actor's schema storages,
-     *   `{ id: 'abc' }` to open by explicit ID, or `{ name: 'abc' }` to open by explicit name.
+     *   You can also pass `{ alias: 'abc' }` to open a run-scoped storage, `{ id: 'abc' }` to open by
+     *   explicit ID, or `{ name: 'abc' }` to open by explicit name.
      * @param [options]
      */
     static async openDataset(datasetIdOrName, options = {}) {
@@ -1630,13 +1631,6 @@ export class Actor {
             pushFn: async (limitedItems) => dataset.pushData(limitedItems),
         });
     }
-    async _openStorage(storageClass, identifier, options = {}) {
-        return openStorage(storageClass, identifier, {
-            config: this.configuration,
-            backend: options.forceCloud ? this.createApifyStorageBackend() : undefined,
-            purgedStorageAliases: this.purgedStorageAliases,
-        });
-    }
     createApifyStorageBackend() {
         return new ApifyStorageBackend(this.apifyClient, {
             configuration: this.configuration,

package/dist/apify_storage_backend.d.ts

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { DatasetBackend, KeyValueStoreBackend, RequestQueueBackend, StorageBackend, StorageIdentifier } from '@crawlee/types';
 import type { ApifyClient } from 'apify-client';
-import type { RequestQueueAccessMode } from './apify_request_queue_backend.js';
+import { type RequestQueueAccessMode } from './apify_request_queue_backend.js';
 import { type ChargeResult, type ChargingManager } from './charging.js';
 import type { Configuration } from './configuration.js';
 type StorageType = 'Dataset' | 'KeyValueStore' | 'RequestQueue';
@@ -66,8 +66,12 @@ export declare class ApifyStorageBackend implements StorageBackend {
     private readonly config?;
     private readonly requestQueueAccess;
     private readonly getChargingManager?;
-    /** Unnamed storages created for aliases in this process, so an alias maps to one storage. */
+    /** Unnamed storages resolved for aliases in this process, keyed like {@link AliasMapping}. */
     private readonly aliasIdCache;
+    /** The alias mapping read from the run's default key-value store; `undefined` until first read. */
+    private persistedAliasIds?;
+    /** Serializes alias resolution — see `resolveAliasId`. */
+    private readonly aliasLock;
     /** Fallback request queue client key when the run id is unavailable — one per backend. */
     private fallbackClientKey?;
     constructor(client: ApifyClient, options?: ApifyStorageBackendOptions);
@@ -78,6 +82,8 @@ export declare class ApifyStorageBackend implements StorageBackend {
      * and `shared` mode at once is not supported, and whichever backend opens it first wins.
      */
     getStorageBackendCacheKey(): string;
+    /** Short digest of the API base URL and token — identifies the credentials a storage was opened with. */
+    private credentialsHash;
     storageExists(id: string, type: StorageType): Promise<boolean>;
     createDatasetBackend(options?: StorageIdentifier): Promise<DatasetBackend>;
     createKeyValueStoreBackend(options?: StorageIdentifier): Promise<KeyValueStoreBackend>;
@@ -97,11 +103,27 @@ export declare class ApifyStorageBackend implements StorageBackend {
      * Resolves a crawlee {@link StorageIdentifier} to a platform storage id.
      *
      * Aliases resolve to unnamed storages: the reserved `__default__` alias maps to the run's
-     * default storage, and other aliases to the storages declared in the Actor's schema (via the
-     * `ACTOR_STORAGES_JSON` environment variable, maintained by the platform). Outside the
-     * platform, an unnamed storage is created per alias instead (remembered for this process only).
+     * default storage, and an alias declared in the Actor's schema to the storage the platform
+     * created for it (via the `ACTOR_STORAGES_JSON` environment variable). Any other alias gets an
+     * unnamed storage of its own — crawlee mints aliases at runtime, one per extra crawler instance
+     * and one per throttled domain, so an undeclared alias is not an error.
      */
     private resolveId;
+    /**
+     * Returns the unnamed storage backing `alias`, creating it on first use.
+     *
+     * On the platform the mapping is persisted, so a migrated run reopens the same storages rather
+     * than empty ones — aliased request queues hold live requests. Serialized, so one alias means
+     * one storage and the mapping's read-modify-write cannot drop entries.
+     */
+    private resolveAliasId;
+    /**
+     * Re-reads the record first, so a second backend in this process does not drop its entries.
+     * Logged rather than thrown: a lost entry only costs a re-created storage after a migration.
+     */
+    private persistAliasId;
+    /** The run's default key-value store, where the mapping lives — `undefined` off the platform. */
+    private aliasMappingStore;
     /** Looks an alias up in the Actor's schema storages (the `ACTOR_STORAGES_JSON` env var). */
     private aliasFromActorStorages;
     private resourceClient;

package/dist/apify_storage_backend.js

@@ -2,14 +2,22 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash } from 'node:crypto';
 import { DatasetClient as ApifyDatasetClient } from 'apify-client';
+import log from '@apify/log';
 import { cryptoRandomObjectId } from '@apify/utilities';
 import { ApifyDatasetBackend } from './apify_dataset_backend.js';
 import { ApifyKeyValueStoreBackend } from './apify_key_value_store_backend.js';
+import { AsyncLock } from './apify_request_queue_backend.js';
 import { ApifyRequestQueueSharedBackend } from './apify_request_queue_shared_backend.js';
 import { ApifyRequestQueueSingleBackend } from './apify_request_queue_single_backend.js';
 import { DEFAULT_DATASET_ITEM_EVENT, mergeChargeResults, pushDataAndCharge, } from './charging.js';
 /** The reserved alias crawlee uses for the default (unnamed) storage. */
 const DEFAULT_STORAGE_ALIAS = '__default__';
+/** The key of the default key-value store record holding this run's alias -> storage id mapping. */
+const ALIAS_MAPPING_RECORD_KEY = '__STORAGE_ALIASES_MAPPING';
+async function readAliasMapping(store) {
+    const record = await store.getRecord(ALIAS_MAPPING_RECORD_KEY);
+    return record?.value ?? {};
+}
 /** The maximum clientKey length accepted by the request queue API. */
 const MAX_CLIENT_KEY_LENGTH = 32;
 const DEFAULT_ID_CONFIG_KEY = {
@@ -95,8 +103,12 @@ export class ApifyStorageBackend {
     config;
     requestQueueAccess;
     getChargingManager;
-    /** Unnamed storages created for aliases in this process, so an alias maps to one storage. */
+    /** Unnamed storages resolved for aliases in this process, keyed like {@link AliasMapping}. */
     aliasIdCache = new Map();
+    /** The alias mapping read from the run's default key-value store; `undefined` until first read. */
+    persistedAliasIds;
+    /** Serializes alias resolution — see `resolveAliasId`. */
+    aliasLock = new AsyncLock();
     /** Fallback request queue client key when the run id is unavailable — one per backend. */
     fallbackClientKey;
     constructor(client, options = {}) {
@@ -112,11 +124,14 @@ export class ApifyStorageBackend {
      * and `shared` mode at once is not supported, and whichever backend opens it first wins.
      */
     getStorageBackendCacheKey() {
-        const hash = createHash('sha256')
+        return `ApifyStorageBackend:${this.credentialsHash()}`;
+    }
+    /** Short digest of the API base URL and token — identifies the credentials a storage was opened with. */
+    credentialsHash() {
+        return createHash('sha256')
             .update(`${this.client.publicBaseUrl}${this.client.token ?? ''}`)
             .digest('hex')
             .slice(0, 8);
-        return `ApifyStorageBackend:${hash}`;
     }
     async storageExists(id, type) {
         // Lets `Dataset.open(idOrName)` and friends resolve a string to an id first (when one
@@ -183,9 +198,10 @@ export class ApifyStorageBackend {
      * Resolves a crawlee {@link StorageIdentifier} to a platform storage id.
      *
      * Aliases resolve to unnamed storages: the reserved `__default__` alias maps to the run's
-     * default storage, and other aliases to the storages declared in the Actor's schema (via the
-     * `ACTOR_STORAGES_JSON` environment variable, maintained by the platform). Outside the
-     * platform, an unnamed storage is created per alias instead (remembered for this process only).
+     * default storage, and an alias declared in the Actor's schema to the storage the platform
+     * created for it (via the `ACTOR_STORAGES_JSON` environment variable). Any other alias gets an
+     * unnamed storage of its own — crawlee mints aliases at runtime, one per extra crawler instance
+     * and one per throttled domain, so an undeclared alias is not an error.
      */
     async resolveId(options, type) {
         if (options?.id)
@@ -203,20 +219,57 @@ export class ApifyStorageBackend {
             const declaredId = this.aliasFromActorStorages(alias, type);
             if (declaredId)
                 return declaredId;
-            if (this.config?.isAtHome) {
-                throw new Error(`Storage alias "${alias}" cannot be resolved because it is not declared in the Actor's schema storages. ` +
-                    `Declare it in the Actor schema, or open the storage by name instead.`);
+        }
+        return this.resolveAliasId(alias, type);
+    }
+    /**
+     * Returns the unnamed storage backing `alias`, creating it on first use.
+     *
+     * On the platform the mapping is persisted, so a migrated run reopens the same storages rather
+     * than empty ones — aliased request queues hold live requests. Serialized, so one alias means
+     * one storage and the mapping's read-modify-write cannot drop entries.
+     */
+    async resolveAliasId(alias, type) {
+        // The credentials are part of the key, so the same alias opened through two
+        // differently-authenticated backends maps to two storages.
+        const key = [type, alias, this.credentialsHash()].join(',');
+        return this.aliasLock.runExclusive(async () => {
+            const knownId = this.aliasIdCache.get(key);
+            if (knownId)
+                return knownId;
+            const store = this.aliasMappingStore();
+            this.persistedAliasIds ??= store ? await readAliasMapping(store) : {};
+            // A persisted id can point at a storage the user has since deleted.
+            const persistedId = this.persistedAliasIds[key];
+            if (persistedId && (await this.resourceClient(persistedId, type).get())) {
+                this.aliasIdCache.set(key, persistedId);
+                return persistedId;
             }
+            const { id } = await this.collectionClient(type).getOrCreate();
+            this.aliasIdCache.set(key, id);
+            if (store)
+                await this.persistAliasId(store, key, id);
+            return id;
+        });
+    }
+    /**
+     * Re-reads the record first, so a second backend in this process does not drop its entries.
+     * Logged rather than thrown: a lost entry only costs a re-created storage after a migration.
+     */
+    async persistAliasId(store, key, id) {
+        try {
+            const mapping = await readAliasMapping(store);
+            mapping[key] = id;
+            await store.setRecord({ key: ALIAS_MAPPING_RECORD_KEY, value: mapping });
+            this.persistedAliasIds = mapping;
+        }
+        catch (error) {
+            log.warning(`Failed to persist the storage alias mapping: ${error.message}`);
         }
-        // No platform-provided id for this alias (e.g. cloud storage used locally via an API
-        // token) — create an unnamed storage for it, one per alias per process.
-        const cacheKey = `${type}:${alias}`;
-        const cachedId = this.aliasIdCache.get(cacheKey);
-        if (cachedId)
-            return cachedId;
-        const created = await this.collectionClient(type).getOrCreate();
-        this.aliasIdCache.set(cacheKey, created.id);
-        return created.id;
+    }
+    /** The run's default key-value store, where the mapping lives — `undefined` off the platform. */
+    aliasMappingStore() {
+        return this.config?.isAtHome ? this.client.keyValueStore(this.config.defaultKeyValueStoreId) : undefined;
     }
     /** Looks an alias up in the Actor's schema storages (the `ACTOR_STORAGES_JSON` env var). */
     aliasFromActorStorages(alias, type) {

package/dist/configuration.d.ts

@@ -5,7 +5,7 @@ export declare const apifyConfigFields: {
     maxUsedCpuRatio: ConfigField<z.ZodDefault<z.ZodPreprocess<z.ZodNumber>>>;
     internalTimeoutMillis: ConfigField<z.ZodOptional<z.ZodPreprocess<z.ZodNumber>>>;
     systemInfoIntervalMillis: ConfigField<z.ZodDefault<z.ZodPreprocess<z.ZodNumber>>>;
-    logLevel: ConfigField<z.ZodOptional<z.ZodPreprocess<z.ZodEnum<typeof import("@apify/log").LogLevel>>>>;
+    logLevel: ConfigField<z.ZodOptional<z.ZodPreprocess<z.ZodEnum<typeof import("@crawlee/core").LogLevel>>>>;
     persistStorage: ConfigField<z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>>;
     storageDir: ConfigField<z.ZodDefault<z.ZodString>>;
     containerized: ConfigField<z.ZodOptional<z.ZodPreprocess<z.ZodBoolean>>>;

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { ApifyStorageBackend, type ApifyStorageBackendOptions } from './apify_st
 export type { RequestQueueAccessMode } from './apify_request_queue_backend.js';
 export { ArgumentValidationError } from './utils.js';
 export { createTransformRequestFunction, type GlobInput, type PseudoUrlInput, type UrlPatternFilters, type UrlPatternRequestOptions, } from './enqueue_links_filters.js';
-export type { OpenStorageOptions, StorageAlias, StorageId, StorageName, StorageIdentifier, StorageIdentifierWithoutAlias, } from './storage.js';
+export type { OpenStorageOptions, StorageAlias, StorageId, StorageName, StorageIdentifier } from './storage.js';
 export { ChargeOptions, ChargeResult, ActorPricingInfo, ChargingManager } from './charging.js';
 export * from './configuration.js';
 export * from './proxy_configuration.js';

package/dist/proxy_configuration.js

@@ -6,9 +6,9 @@ import { z } from 'zod';
 import { APIFY_ENV_VARS, APIFY_PROXY_VALUE_REGEX } from '@apify/consts';
 import defaultLog from '@apify/log';
 import { cryptoRandomObjectId } from '@apify/utilities';
+import { parseArgument } from '@apify/validations';
 import { Actor } from './actor.js';
 import { Configuration } from './configuration.js';
-import { validate } from './utils.js';
 const CHECK_ACCESS_REQUEST_TIMEOUT_MILLIS = 4_000;
 const CHECK_ACCESS_MAX_ATTEMPTS = 2;
 const COUNTRY_CODE_REGEX = /^[A-Z]{2}$/;
@@ -72,7 +72,7 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
             ['validateRequired']: false,
         });
         this.configuration = configuration;
-        validate(z
+        parseArgument(rest, z
             .object({
             groups: z.array(z.string().regex(APIFY_PROXY_VALUE_REGEX)).optional(),
             apifyProxyGroups: z.array(z.string().regex(APIFY_PROXY_VALUE_REGEX)).optional(),
@@ -82,7 +82,7 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
             apifyProxySubdivision: z.string().regex(SUBDIVISION_CODE_REGEX).optional(),
             password: z.string().optional(),
         })
-            .strict(), rest);
+            .strict());
         const { groups = [], apifyProxyGroups = [], countryCode, apifyProxyCountry, subdivisionCode, apifyProxySubdivision, password = configuration.proxyPassword, } = options;
         const groupsToUse = groups.length ? groups : apifyProxyGroups;
         const countryCodeToUse = countryCode || apifyProxyCountry;

package/dist/storage.d.ts

@@ -1,6 +1,3 @@
-import type { IStorage, StorageOpenOptions } from '@crawlee/core';
-import type { Constructor, StorageBackend } from '@crawlee/types';
-import type { Configuration } from './configuration.js';
 export interface OpenStorageOptions {
     /**
      * If set to `true` then the cloud storage is used even if the `CRAWLEE_STORAGE_DIR`
@@ -10,8 +7,11 @@ export interface OpenStorageOptions {
     forceCloud?: boolean;
 }
 /**
- * Identifies a storage by its alias from the Actor's schema storages
- * (resolved via the `ACTOR_STORAGES_JSON` environment variable).
+ * Identifies a run-scoped storage by its alias.
+ *
+ * An alias declared in the Actor's schema storages (the `ACTOR_STORAGES_JSON` environment variable)
+ * resolves to the storage the platform created for it; any other alias gets an unnamed storage of
+ * its own, for this run only.
  */
 export interface StorageAlias {
     alias: string;
@@ -31,28 +31,8 @@ export interface StorageName {
 /**
  * Identifies a storage to open. Can be:
  * - A plain `string` for backward compatibility (treated as ID or name)
- * - `{ alias: string }` to resolve from the Actor's schema storages (`ACTOR_STORAGES_JSON`)
+ * - `{ alias: string }` to open a run-scoped storage — see {@link StorageAlias}
  * - `{ id: string }` to open by explicit platform ID
  * - `{ name: string }` to open by explicit name
  */
 export type StorageIdentifier = string | StorageAlias | StorageId | StorageName;
-/**
- * Identifies a storage to open, without alias support.
- * Used for key-value stores and request queues, which do not support aliases.
- * Can be:
- * - A plain `string` for backward compatibility (treated as ID or name)
- * - `{ id: string }` to open by explicit platform ID
- * - `{ name: string }` to open by explicit name
- */
-export type StorageIdentifierWithoutAlias = string | StorageId | StorageName;
-export interface OpenStorageContext {
-    config: Configuration;
-    backend?: StorageBackend;
-    purgedStorageAliases: Set<string>;
-}
-/**
- * Opens a storage by its identifier, handling Apify alias resolution and local purging.
- */
-export declare function openStorage<T extends IStorage>(storageClass: Constructor<T> & {
-    open(id?: string | null, options?: StorageOpenOptions): Promise<T>;
-}, identifier: StorageIdentifier | null | undefined, context: OpenStorageContext): Promise<T>;

package/dist/storage.js

@@ -1,79 +1 @@
-import { ApifyStorageBackend } from './apify_storage_backend.js';
-const STORAGE_TYPE_KEYS = {
-    Dataset: 'datasets',
-    KeyValueStore: 'keyValueStores',
-    RequestQueue: 'requestQueues',
-};
-const parsedStoragesJson = new Map();
-/**
- * Resolves a {@link StorageIdentifier} to a plain string ID or name
- * that can be passed to crawlee v4's `<Storage>.open()`.
- */
-function resolveStorageIdentifier(storageType, identifier, config) {
-    if (identifier === null || identifier === undefined) {
-        return undefined;
-    }
-    if (typeof identifier === 'string') {
-        return identifier;
-    }
-    if ('id' in identifier) {
-        return identifier.id;
-    }
-    if ('name' in identifier) {
-        return identifier.name;
-    }
-    // { alias: string }
-    const storagesJson = config.actorStoragesJson;
-    if (config.isAtHome && storagesJson) {
-        let storages;
-        try {
-            if (!parsedStoragesJson.has(storagesJson)) {
-                parsedStoragesJson.set(storagesJson, JSON.parse(storagesJson));
-            }
-            storages = parsedStoragesJson.get(storagesJson);
-        }
-        catch {
-            throw new Error(`Failed to parse ACTOR_STORAGES_JSON environment variable: ${storagesJson}`);
-        }
-        const typeKey = STORAGE_TYPE_KEYS[storageType];
-        const resolvedId = storages[typeKey]?.[identifier.alias];
-        if (resolvedId) {
-            return resolvedId;
-        }
-        throw new Error(`Storage alias "${identifier.alias}" not found in ACTOR_STORAGES_JSON for storage type "${storageType}". ` +
-            `Available aliases: ${Object.keys(storages[typeKey] ?? {}).join(', ') || '(none)'}`);
-    }
-    // When using local storage, just use the alias as a name.
-    // When using platform storage, we can't just make up a name — the alias must be
-    // in ACTOR_STORAGES_JSON.
-    if (config.isAtHome) {
-        throw new Error(`Storage alias "${identifier.alias}" cannot be resolved because ACTOR_STORAGES_JSON is not set. ` +
-            `Aliases are only available for storages declared in the Actor's schema.`);
-    }
-    return identifier.alias;
-}
-/**
- * Opens a storage by its identifier, handling Apify alias resolution and local purging.
- */
-export async function openStorage(storageClass, identifier, context) {
-    const isAlias = identifier !== null && identifier !== undefined && typeof identifier === 'object' && 'alias' in identifier;
-    if (isAlias && !context.config.isAtHome && context.backend instanceof ApifyStorageBackend) {
-        throw new Error('The `alias` option is not allowed for Apify-based storages running outside of Apify');
-    }
-    const resolvedIdOrName = resolveStorageIdentifier(storageClass.name, identifier, context.config);
-    // When running locally, purge aliased storages on first open
-    // (similar to how crawlee purges default storages on start).
-    if (isAlias &&
-        !context.config.isAtHome &&
-        context.config.purgeOnStart &&
-        !context.purgedStorageAliases.has(identifier.alias)) {
-        context.purgedStorageAliases.add(identifier.alias);
-        const existingStorage = await storageClass.open(resolvedIdOrName ?? null, {
-            storageBackend: context.backend,
-        });
-        await existingStorage.drop();
-    }
-    return storageClass.open(resolvedIdOrName ?? null, {
-        storageBackend: context.backend,
-    });
-}
+export {};

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { z } from 'zod';
+export { ArgumentValidationError } from '@apify/validations';
 /**
  * Returns `true` for a plain, non-empty object (not `null`, not an array).
  * Mirrors the `ow.object.nonEmpty` predicate the SDK used previously.
@@ -10,26 +10,6 @@ export declare function isNonEmptyObject(value: unknown): value is Record<string
  * @internal
  */
 export declare function snakeCaseToCamelCase(snakeCaseStr: string): string;
-/**
- * Error thrown when an argument fails validation (e.g. by `Actor.addWebhook()`
- * or the `ProxyConfiguration` constructor).
- *
- * Its `message` is a human-readable sentence naming the offending field and the
- * value it received (see {@link formatZodError}) — not a raw JSON dump. The
- * structured zod {@link https://zod.dev | zod} issues are available on `issues`
- * (and the original `ZodError` on `cause`) for programmatic inspection.
- */
-export declare class ArgumentValidationError extends Error {
-    /** Structured issues from the underlying schema check. */
-    readonly issues: z.ZodError['issues'];
-    constructor(error: z.ZodError, value: unknown);
-}
-/**
- * Validates `value` against a zod `schema`, returning the parsed value, or
- * throwing an {@link ArgumentValidationError} if it doesn't match.
- * @internal
- */
-export declare function validate<Schema extends z.ZodType>(schema: Schema, value: unknown): z.infer<Schema>;
 /**
  * Gets info about system, node version and apify package version.
  * @internal

package/dist/utils.js

@@ -11,6 +11,7 @@ import { APIFY_ENV_VARS } from '@apify/consts';
 import log from '@apify/log';
 // @ts-ignore if we enable resolveJsonModule, we end up with `src` folder in `dist`
 import apifyPkgJson from '../package.json' with { type: 'json' };
+export { ArgumentValidationError } from '@apify/validations';
 const require = createRequire(import.meta.url);
 /**
  * Returns `true` for a plain, non-empty object (not `null`, not an array).
@@ -31,86 +32,6 @@ export function snakeCaseToCamelCase(snakeCaseStr) {
         .map((part, index) => (index > 0 ? part.charAt(0).toUpperCase() + part.slice(1) : part))
         .join('');
 }
-/** Formats a zod issue path like `groups[0]` or `countryCode`. */
-function formatIssuePath(path) {
-    let out = '';
-    for (const key of path) {
-        if (typeof key === 'number')
-            out += `[${key}]`;
-        else
-            out += out ? `.${String(key)}` : String(key);
-    }
-    return out;
-}
-/** Reads the value at `path` from the validated input, to include in the error. */
-function valueAtPath(root, path) {
-    let current = root;
-    for (const key of path) {
-        if (current === null || typeof current !== 'object')
-            return undefined;
-        current = current[key];
-    }
-    return current;
-}
-/** Renders a primitive received value for an error; skips objects/Dates (noisy). */
-function describeReceived(value) {
-    switch (typeof value) {
-        case 'string':
-            return value;
-        case 'number':
-        case 'boolean':
-        case 'bigint':
-            return String(value);
-        default:
-            return undefined;
-    }
-}
-/**
- * Formats a `ZodError` as a plain, human-readable message that names the
- * offending field *and* the value it received (e.g. ``must match pattern
- * /^[A-Z]{2}$/ at `countryCode`, got `CZE` ``) — closer to the old `ow` errors
- * than zod's default, which omits the received value.
- */
-function formatZodError(error, root) {
-    return error.issues
-        .map((issue) => {
-        const location = issue.path.length ? ` at \`${formatIssuePath(issue.path)}\`` : '';
-        const received = describeReceived(valueAtPath(root, issue.path));
-        const got = received === undefined ? '' : `, got \`${received}\``;
-        return `${issue.message}${location}${got}`;
-    })
-        .join('\n');
-}
-/**
- * Error thrown when an argument fails validation (e.g. by `Actor.addWebhook()`
- * or the `ProxyConfiguration` constructor).
- *
- * Its `message` is a human-readable sentence naming the offending field and the
- * value it received (see {@link formatZodError}) — not a raw JSON dump. The
- * structured zod {@link https://zod.dev | zod} issues are available on `issues`
- * (and the original `ZodError` on `cause`) for programmatic inspection.
- */
-export class ArgumentValidationError extends Error {
-    /** Structured issues from the underlying schema check. */
-    issues;
-    constructor(error, value) {
-        super(formatZodError(error, value), { cause: error });
-        this.name = 'ArgumentValidationError';
-        this.issues = error.issues;
-    }
-}
-/**
- * Validates `value` against a zod `schema`, returning the parsed value, or
- * throwing an {@link ArgumentValidationError} if it doesn't match.
- * @internal
- */
-export function validate(schema, value) {
-    const result = schema.safeParse(value);
-    if (!result.success) {
-        throw new ArgumentValidationError(result.error, value);
-    }
-    return result.data;
-}
 /**
  * Gets info about system, node version and apify package version.
  * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify",
-  "version": "4.0.0-beta.29",
+  "version": "4.0.0-beta.31",
   "description": "The scalable web crawling and scraping library for JavaScript/Node.js. Enables development of data extraction and web automation jobs (not only) with headless Chrome and Puppeteer.",
   "engines": {
     "node": ">=22.0.0"
@@ -53,13 +53,14 @@
     ]
   },
   "dependencies": {
-    "@apify/consts": "^2.57.2",
-    "@apify/datastructures": "^2.0.6",
-    "@apify/input_secrets": "^1.2.56",
-    "@apify/log": "^2.5.50",
-    "@apify/pseudo_url": "^2.0.91",
-    "@apify/timeout": "^0.4.10",
-    "@apify/utilities": "^2.35.7",
+    "@apify/consts": "^3.0.1",
+    "@apify/datastructures": "^3.0.1",
+    "@apify/input_secrets": "^2.0.1",
+    "@apify/log": "^3.0.1",
+    "@apify/pseudo_url": "^3.0.1",
+    "@apify/timeout": "^1.0.1",
+    "@apify/utilities": "^3.0.1",
+    "@apify/validations": "^1.0.1",
     "@crawlee/core": "^4.0.0-rc.0",
     "@crawlee/types": "^4.0.0-rc.0",
     "@crawlee/utils": "^4.0.0-rc.0",