apify 4.0.0-beta.30 → 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

@@ -14,7 +14,6 @@ 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, } from './utils.js';
 /**
  * Exit codes for the Actor process.
@@ -76,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 = {}) {
@@ -674,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 = {}) {
         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.
@@ -820,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 = {}) {
         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
@@ -843,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 = {}) {
         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
@@ -1343,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 = {}) {
@@ -1631,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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify",
-  "version": "4.0.0-beta.30",
+  "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"