@crawlee/core 4.0.0-beta.11 → 4.0.0-beta.111

package/storages/{sitemap_request_list.js → sitemap_request_loader.js}

@@ -2,37 +2,34 @@ import { Transform } from 'node:stream';
 import { parseSitemap } from '@crawlee/utils';
 import { minimatch } from 'minimatch';
 import ow from 'ow';
-import defaultLog from '@apify/log';
-import { Configuration } from '../configuration.js';
-import { constructGlobObjectsFromGlobs, constructRegExpObjectsFromRegExps } from '../enqueue_links/shared.js';
+import { constructUrlPatternObjects } from '../enqueue_links/shared.js';
 import { Request } from '../request.js';
+import { serviceLocator } from '../service_locator.js';
 import { KeyValueStore } from './key_value_store.js';
 import { purgeDefaultStorages } from './utils.js';
 /** @internal */
-const STATE_PERSISTENCE_KEY = 'SITEMAP_REQUEST_LIST_STATE';
+const STATE_PERSISTENCE_KEY = 'SITEMAP_REQUEST_LOADER_STATE';
 /**
  * A list of URLs to crawl parsed from a sitemap.
  *
  * The loading of the sitemap is performed in the background so that crawling can start before the sitemap is fully loaded.
  */
-export class SitemapRequestList {
+export class SitemapRequestLoader {
     /**
      * Set of URLs that were returned by `fetchNextRequest()` and not marked as handled yet.
      * @internal
      */
     inProgress = new Set();
-    /** Set of URLs for which `reclaimRequest()` was called. */
-    reclaimed = new Set();
     /**
      * Map of returned Request objects that have not been marked as handled yet.
      *
-     * We use this to persist custom user fields on the in-progress (or reclaimed) requests.
+     * We use this to persist custom user fields on the in-progress requests.
      */
-    requestData = new Map();
+    #requestData = new Map();
     /**
      * Object for keeping track of the sitemap parsing progress.
      */
-    sitemapParsingProgress = {
+    #sitemapParsingProgress = {
         /**
          * URL of the sitemap that is currently being parsed. `null` if no sitemap is being parsed.
          */
@@ -52,7 +49,7 @@ export class SitemapRequestList {
      *
      * Fetch the next URL to be processed using `fetchNextRequest()`.
      */
-    urlQueueStream;
+    #urlQueueStream;
     /**
      * Indicates whether the request list sitemap loading was aborted.
      *
@@ -61,27 +58,28 @@ export class SitemapRequestList {
      *
      * If the loading is aborted and all the requests are handled, `isFinished()` will return `true`.
      */
-    abortLoading = false;
+    #abortLoading = false;
     /** Number of URLs that were marked as handled */
-    handledUrlCount = 0;
-    persistStateKey;
-    store;
-    closed = false;
+    #handledUrlCount = 0;
+    #persistStateKey;
+    #store;
+    #closed = false;
     /**
      * Proxy URL to be used for sitemap loading.
      */
-    proxyUrl;
+    #proxyUrl;
     /**
      * Logger instance.
      */
-    log = defaultLog.child({ prefix: 'SitemapRequestList' });
-    urlExcludePatternObjects = [];
-    urlPatternObjects = [];
+    #log;
+    #urlExcludePatternObjects = [];
+    #urlPatternObjects = [];
     /** EventManager used to handle persistence */
-    events;
-    persistenceOptions;
+    #events;
+    #persistenceOptions;
     /** @internal */
     constructor(options) {
+        const urlPatternValidator = ow.any(ow.string, ow.regExp, ow.object.hasKeys('glob'), ow.object.hasKeys('regexp'));
         ow(options, ow.object.exactShape({
             sitemapUrls: ow.array.ofType(ow.string),
             proxyUrl: ow.optional.string,
@@ -90,35 +88,25 @@ export class SitemapRequestList {
             timeoutMillis: ow.optional.number,
             maxBufferSize: ow.optional.number,
             parseSitemapOptions: ow.optional.object,
-            globs: ow.optional.array.ofType(ow.any(ow.string, ow.object.hasKeys('glob'))),
-            exclude: ow.optional.array.ofType(ow.any(ow.string, ow.regExp, ow.object.hasKeys('glob'), ow.object.hasKeys('regexp'))),
-            regexps: ow.optional.array.ofType(ow.any(ow.regExp, ow.object.hasKeys('regexp'))),
-            config: ow.optional.object,
+            include: ow.optional.array.ofType(urlPatternValidator),
+            exclude: ow.optional.array.ofType(urlPatternValidator),
             persistenceOptions: ow.optional.object,
+            httpClient: ow.optional.object,
         }));
-        const { globs, exclude, regexps, config = Configuration.getGlobalConfig() } = options;
+        const { include, exclude } = options;
+        this.#log = serviceLocator.getLogger().child({ prefix: 'SitemapRequestLoader' });
         if (exclude?.length) {
-            for (const excl of exclude) {
-                if (typeof excl === 'string' || 'glob' in excl) {
-                    this.urlExcludePatternObjects.push(...constructGlobObjectsFromGlobs([excl]));
-                }
-                else if (excl instanceof RegExp || 'regexp' in excl) {
-                    this.urlExcludePatternObjects.push(...constructRegExpObjectsFromRegExps([excl]));
-                }
-            }
+            this.#urlExcludePatternObjects.push(...constructUrlPatternObjects(exclude));
         }
-        if (globs?.length) {
-            this.urlPatternObjects.push(...constructGlobObjectsFromGlobs(globs));
+        if (include?.length) {
+            this.#urlPatternObjects.push(...constructUrlPatternObjects(include));
         }
-        if (regexps?.length) {
-            this.urlPatternObjects.push(...constructRegExpObjectsFromRegExps(regexps));
-        }
-        this.persistStateKey = options.persistStateKey;
-        this.persistenceOptions = { enable: true, ...options.persistenceOptions };
-        this.proxyUrl = options.proxyUrl;
-        this.urlQueueStream = this.createNewStream(options.maxBufferSize ?? 200);
-        this.sitemapParsingProgress.pendingSitemapUrls = new Set(options.sitemapUrls);
-        this.events = config.getEventManager();
+        this.#persistStateKey = options.persistStateKey;
+        this.#persistenceOptions = { enable: true, ...options.persistenceOptions };
+        this.#proxyUrl = options.proxyUrl;
+        this.#urlQueueStream = this.createNewStream(options.maxBufferSize ?? 200);
+        this.#sitemapParsingProgress.pendingSitemapUrls = new Set(options.sitemapUrls);
+        this.#events = serviceLocator.getEventManager();
         this.persistState = this.persistState.bind(this);
     }
     /**
@@ -146,13 +134,13 @@ export class SitemapRequestList {
         };
     }
     /**
-     * Checks whether the URL matches the `globs` / `regexps` / `exclude` provided in the `options`.
+     * Checks whether the URL matches the `include` / `exclude` patterns provided in the `options`.
      * @param url URL to be checked.
      * @returns `true` if the URL matches the patterns, `false` otherwise.
      */
     isUrlMatchingPatterns(url) {
-        return (!this.urlExcludePatternObjects.some(this.matchesUrl(url)) &&
-            (this.urlPatternObjects.length === 0 || this.urlPatternObjects.some(this.matchesUrl(url))));
+        return (!this.#urlExcludePatternObjects.some(this.matchesUrl(url)) &&
+            (this.#urlPatternObjects.length === 0 || this.#urlPatternObjects.some(this.matchesUrl(url))));
     }
     /**
      * Adds a URL to the queue of parsed URLs.
@@ -161,13 +149,13 @@ export class SitemapRequestList {
      */
     async pushNextUrl(url) {
         return new Promise((resolve) => {
-            if (this.closed || (url && !this.isUrlMatchingPatterns(url))) {
+            if (this.#closed || (url && !this.isUrlMatchingPatterns(url))) {
                 resolve();
                 return;
             }
-            if (!this.urlQueueStream.push(url)) {
+            if (!this.#urlQueueStream.push(url)) {
                 // This doesn't work with the 'drain' event (it's not emitted for some reason).
-                this.urlQueueStream.once('readdata', () => {
+                this.#urlQueueStream.once('readdata', () => {
                     resolve();
                 });
             }
@@ -184,21 +172,21 @@ export class SitemapRequestList {
      */
     async readNextUrl() {
         return new Promise((resolve) => {
-            if (this.closed) {
+            if (this.#closed) {
                 resolve(null);
                 return;
             }
-            const result = this.urlQueueStream.read();
+            const result = this.#urlQueueStream.read();
             if (!result && !this.isSitemapFullyLoaded()) {
-                this.urlQueueStream.once('readable', () => {
-                    const nextUrl = this.urlQueueStream.read();
+                this.#urlQueueStream.once('readable', () => {
+                    const nextUrl = this.#urlQueueStream.read();
                     resolve(nextUrl);
                 });
             }
             else {
                 resolve(result);
             }
-            this.urlQueueStream.emit('readdata');
+            this.#urlQueueStream.emit('readdata');
         });
     }
     /**
@@ -207,8 +195,8 @@ export class SitemapRequestList {
      * If this is `false`, the background processing is either still in progress or was aborted.
      */
     isSitemapFullyLoaded() {
-        return (this.sitemapParsingProgress.inProgressSitemapUrl === null &&
-            this.sitemapParsingProgress.pendingSitemapUrls.size === 0);
+        return (this.#sitemapParsingProgress.inProgressSitemapUrl === null &&
+            this.#sitemapParsingProgress.pendingSitemapUrls.size === 0);
     }
     /**
      * Start processing the sitemaps and loading the URLs.
@@ -216,58 +204,61 @@ export class SitemapRequestList {
      * Resolves once all the sitemaps URLs have been fully loaded (sets `isSitemapFullyLoaded` to `true`).
      */
     async load({ parseSitemapOptions, }) {
-        while (!this.isSitemapFullyLoaded() && !this.abortLoading) {
-            const sitemapUrl = this.sitemapParsingProgress.inProgressSitemapUrl ??
-                this.sitemapParsingProgress.pendingSitemapUrls.values().next().value;
+        while (!this.isSitemapFullyLoaded() && !this.#abortLoading) {
+            const sitemapUrl = this.#sitemapParsingProgress.inProgressSitemapUrl ??
+                this.#sitemapParsingProgress.pendingSitemapUrls.values().next().value;
             try {
-                for await (const item of parseSitemap([{ type: 'url', url: sitemapUrl }], this.proxyUrl, {
+                for await (const item of parseSitemap([{ type: 'url', url: sitemapUrl }], this.#proxyUrl, {
                     ...parseSitemapOptions,
                     maxDepth: 0,
                     emitNestedSitemaps: true,
                 })) {
                     if (!item.originSitemapUrl) {
                         // This is a nested sitemap
-                        this.sitemapParsingProgress.pendingSitemapUrls.add(item.loc);
+                        this.#sitemapParsingProgress.pendingSitemapUrls.add(item.loc);
                         continue;
                     }
-                    if (!this.sitemapParsingProgress.inProgressEntries.has(item.loc)) {
+                    if (!this.#sitemapParsingProgress.inProgressEntries.has(item.loc)) {
                         await this.pushNextUrl(item.loc);
-                        this.sitemapParsingProgress.inProgressEntries.add(item.loc);
+                        this.#sitemapParsingProgress.inProgressEntries.add(item.loc);
                     }
                 }
             }
             catch (e) {
-                this.log.error('Error loading sitemap contents:', e);
+                this.#log.error('Error loading sitemap contents:', e);
             }
-            this.sitemapParsingProgress.pendingSitemapUrls.delete(sitemapUrl);
-            this.sitemapParsingProgress.inProgressEntries.clear();
-            this.sitemapParsingProgress.inProgressSitemapUrl = null;
+            this.#sitemapParsingProgress.pendingSitemapUrls.delete(sitemapUrl);
+            this.#sitemapParsingProgress.inProgressEntries.clear();
+            this.#sitemapParsingProgress.inProgressSitemapUrl = null;
         }
-        this.urlQueueStream.end();
+        this.#urlQueueStream.end();
     }
     /**
      * Open a sitemap and start processing it.
      *
-     * Resolves to a new instance of `SitemapRequestList`, which **might not be fully loaded yet** - i.e. the sitemap might still be loading in the background.
+     * Resolves to a new instance of `SitemapRequestLoader`, which **might not be fully loaded yet** - i.e. the sitemap might still be loading in the background.
      *
      * Track the loading progress using the `isSitemapFullyLoaded` property.
      */
     static async open(options) {
-        const requestList = new SitemapRequestList({
-            ...options,
+        const { httpClient, ...restOptions } = options;
+        const requestList = new SitemapRequestLoader({
+            ...restOptions,
             persistStateKey: options.persistStateKey ?? STATE_PERSISTENCE_KEY,
         });
         await requestList.restoreState();
-        void requestList.load({ parseSitemapOptions: options.parseSitemapOptions });
-        if (requestList.persistenceOptions.enable) {
-            requestList.events.on("persistState" /* EventType.PERSIST_STATE */, requestList.persistState);
+        void requestList.load({
+            parseSitemapOptions: { logger: serviceLocator.getLogger(), ...options.parseSitemapOptions, httpClient },
+        });
+        if (requestList.#persistenceOptions.enable) {
+            requestList.#events.on("persistState" /* EventType.PERSIST_STATE */, requestList.persistState);
         }
         options?.signal?.addEventListener('abort', () => {
-            requestList.abortLoading = true;
+            requestList.#abortLoading = true;
         });
         if (options.timeoutMillis) {
             setTimeout(() => {
-                requestList.abortLoading = true;
+                requestList.#abortLoading = true;
             }, options.timeoutMillis);
         }
         return requestList;
@@ -275,38 +266,58 @@ export class SitemapRequestList {
     /**
      * @inheritDoc
      */
-    length() {
-        return this.urlQueueStream.readableLength + this.handledUrlCount - this.inProgress.size - this.reclaimed.size;
+    async getTotalCount() {
+        // Total known so far = not-yet-fetched (still buffered in the stream) + in-progress (fetched but not
+        // yet handled) + already handled.
+        return this.#urlQueueStream.readableLength + this.inProgress.size + this.#handledUrlCount;
+    }
+    /**
+     * @inheritDoc
+     */
+    async getPendingCount() {
+        // Pending = everything not yet handled = not-yet-fetched + in-progress.
+        return this.#urlQueueStream.readableLength + this.inProgress.size;
+    }
+    /**
+     * Combines this list with a request manager (a {@link RequestQueue} by default) into a
+     * {@link RequestManagerTandem}, allowing requests to be added and reclaimed while still
+     * being read from this list first.
+     */
+    async toTandem(requestManager) {
+        // Import here to avoid circular imports.
+        const { RequestManagerTandem } = await import('./request_manager_tandem.js');
+        const { RequestQueue } = await import('./request_queue.js');
+        return new RequestManagerTandem(this, requestManager ?? (await RequestQueue.open()));
     }
     /**
      * @inheritDoc
      */
     async isFinished() {
-        return ((await this.isEmpty()) && this.inProgress.size === 0 && (this.isSitemapFullyLoaded() || this.abortLoading));
+        return ((await this.isEmpty()) && this.inProgress.size === 0 && (this.isSitemapFullyLoaded() || this.#abortLoading));
     }
     /**
      * @inheritDoc
      */
     async isEmpty() {
-        return this.reclaimed.size === 0 && this.urlQueueStream.readableLength === 0;
+        return this.#urlQueueStream.readableLength === 0;
     }
     /**
      * @inheritDoc
      */
-    handledCount() {
-        return this.handledUrlCount;
+    async getHandledCount() {
+        return this.#handledUrlCount;
     }
     /**
      * @inheritDoc
      */
     async persistState() {
-        if (this.persistStateKey === undefined) {
+        if (this.#persistStateKey === undefined) {
             return;
         }
-        this.store ??= await KeyValueStore.open();
+        this.#store ??= await KeyValueStore.open();
         const urlQueue = [];
-        while (this.urlQueueStream.readableLength > 0) {
-            const url = this.urlQueueStream.read();
+        while (this.#urlQueueStream.readableLength > 0) {
+            const url = this.#urlQueueStream.read();
             if (url === null) {
                 break;
             }
@@ -314,69 +325,63 @@ export class SitemapRequestList {
         }
         // Create a new stream, as we have read all the URLs from the current one.
         // Pushing the urls back to the original stream might not be possible if it has been ended.
-        const newStream = this.createNewStream(this.urlQueueStream.readableHighWaterMark);
+        const newStream = this.createNewStream(this.#urlQueueStream.readableHighWaterMark);
         for (const url of urlQueue) {
             newStream.push(url);
         }
-        if (this.urlQueueStream.writableEnded) {
+        if (this.#urlQueueStream.writableEnded) {
             newStream.end();
         }
-        this.urlQueueStream = newStream;
-        await this.store.setValue(this.persistStateKey, {
+        this.#urlQueueStream = newStream;
+        await this.#store.setValue(this.#persistStateKey, {
             sitemapParsingProgress: {
-                pendingSitemapUrls: Array.from(this.sitemapParsingProgress.pendingSitemapUrls),
-                inProgressSitemapUrl: this.sitemapParsingProgress.inProgressSitemapUrl,
-                inProgressEntries: Array.from(this.sitemapParsingProgress.inProgressEntries),
+                pendingSitemapUrls: Array.from(this.#sitemapParsingProgress.pendingSitemapUrls),
+                inProgressSitemapUrl: this.#sitemapParsingProgress.inProgressSitemapUrl,
+                inProgressEntries: Array.from(this.#sitemapParsingProgress.inProgressEntries),
             },
-            urlQueue,
-            reclaimed: [...this.inProgress, ...this.reclaimed], // In-progress and reclaimed requests will be both retried if state is restored
-            requestData: Array.from(this.requestData.entries()),
-            abortLoading: this.abortLoading,
-            closed: this.closed,
+            // Re-queue in-progress requests to the front so they are retried if the state is restored.
+            urlQueue: [...this.inProgress, ...urlQueue],
+            requestData: Array.from(this.#requestData.entries()),
+            abortLoading: this.#abortLoading,
+            closed: this.#closed,
         });
     }
     async restoreState() {
         await purgeDefaultStorages({ onlyPurgeOnce: true });
-        if (this.persistStateKey === undefined) {
+        if (this.#persistStateKey === undefined) {
             return;
         }
-        this.store ??= await KeyValueStore.open();
-        const state = await this.store.getValue(this.persistStateKey);
+        this.#store ??= await KeyValueStore.open();
+        const state = await this.#store.getValue(this.#persistStateKey);
         if (state === null) {
             return;
         }
-        this.reclaimed = new Set(state.reclaimed);
-        this.sitemapParsingProgress = {
+        this.#sitemapParsingProgress = {
             pendingSitemapUrls: new Set(state.sitemapParsingProgress.pendingSitemapUrls),
             inProgressSitemapUrl: state.sitemapParsingProgress.inProgressSitemapUrl,
             inProgressEntries: new Set(state.sitemapParsingProgress.inProgressEntries),
         };
-        this.requestData = new Map(state.requestData ?? []);
+        this.#requestData = new Map(state.requestData ?? []);
         for (const url of state.urlQueue) {
-            this.urlQueueStream.push(url);
+            this.#urlQueueStream.push(url);
         }
-        this.abortLoading = state.abortLoading;
-        this.closed = state.closed;
+        this.#abortLoading = state.abortLoading;
+        this.#closed = state.closed;
     }
     /**
      * @inheritDoc
      */
     async fetchNextRequest() {
-        // Try to return a reclaimed request first
-        let nextUrl = this.reclaimed.values().next().value;
-        if (nextUrl) {
-            this.reclaimed.delete(nextUrl);
+        const nextUrl = await this.readNextUrl();
+        if (!nextUrl) {
+            return null;
         }
-        else {
-            // Otherwise read next url from the stream
-            nextUrl = await this.readNextUrl();
-            if (!nextUrl) {
-                return null;
-            }
-            this.requestData.set(nextUrl, new Request({ url: nextUrl }));
+        // A restored in-progress request already has its Request data; don't overwrite it.
+        if (!this.#requestData.has(nextUrl)) {
+            this.#requestData.set(nextUrl, new Request({ url: nextUrl }));
         }
         this.inProgress.add(nextUrl);
-        return this.requestData.get(nextUrl);
+        return this.#requestData.get(nextUrl);
     }
     /**
      * @inheritDoc
@@ -389,42 +394,30 @@ export class SitemapRequestList {
             yield request;
         }
     }
-    /**
-     * @inheritDoc
-     */
-    async reclaimRequest(request) {
-        this.ensureInProgressAndNotReclaimed(request.url);
-        this.reclaimed.add(request.url);
-        this.inProgress.delete(request.url);
-    }
     /**
      * Aborts the internal sitemap loading, stops the processing of the sitemap contents and drops all the pending URLs.
      *
      * Calling `fetchNextRequest()` after this method will always return `null`.
      */
     async teardown() {
-        this.closed = true;
-        this.abortLoading = true;
-        this.events.off("persistState" /* EventType.PERSIST_STATE */, this.persistState);
+        this.#closed = true;
+        this.#abortLoading = true;
+        this.#events.off("persistState" /* EventType.PERSIST_STATE */, this.persistState);
         await this.persistState();
-        this.urlQueueStream.emit('readdata'); // unblocks the potentially waiting `pushNextUrl` call
+        this.#urlQueueStream.emit('readdata'); // unblocks the potentially waiting `pushNextUrl` call
     }
     /**
      * @inheritDoc
      */
-    async markRequestHandled(request) {
-        this.handledUrlCount += 1;
-        this.ensureInProgressAndNotReclaimed(request.url);
+    async markRequestAsHandled(request) {
+        this.#handledUrlCount += 1;
+        this.ensureInProgress(request.url);
         this.inProgress.delete(request.url);
-        this.requestData.delete(request.url);
+        this.#requestData.delete(request.url);
     }
-    ensureInProgressAndNotReclaimed(url) {
+    ensureInProgress(url) {
         if (!this.inProgress.has(url)) {
             throw new Error(`The request is not being processed (url: ${url})`);
         }
-        if (this.reclaimed.has(url)) {
-            throw new Error(`The request was already reclaimed (url: ${url})`);
-        }
     }
 }
-//# sourceMappingURL=sitemap_request_list.js.map

package/storages/storage_instance_manager.d.ts

@@ -0,0 +1,87 @@
+import type { Constructor, DatasetBackend, KeyValueStoreBackend, RequestQueueBackend, StorageBackend, StorageIdentifier } from '@crawlee/types';
+export type { StorageIdentifier } from '@crawlee/types';
+/**
+ * Matches an `IStorage` – a storage "frontend" (Dataset, KeyValueStore, RequestQueue).
+ */
+export interface IStorage {
+    id: string;
+    name?: string;
+}
+type Hashable = string;
+/**
+ * Unified manager for opening and caching storage instances (Dataset, KeyValueStore, RequestQueue).
+ *
+ * A single instance manages all storage types. Instances are cached by
+ * `(storageClass, id/name/alias, backendCacheKey)` so the same storage is never opened twice.
+ *
+ * The manager itself does not resolve identifiers — callers pass explicit `id`, `name`, or `alias` (at most one),
+ * and a pre-bound `backendOpener` promise. When none of `id`, `name`, `alias` are provided, the manager automatically
+ * assigns a reserved default alias.
+ */
+export declare class StorageInstanceManager {
+    #private;
+    /**
+     * Open (or retrieve from cache) a storage instance.
+     *
+     * @param cls               The storage class constructor (e.g. `Dataset`, `KeyValueStore`, `RequestQueue`).
+     * @param id                Storage ID (mutually exclusive with `name` and `alias`).
+     * @param name              Storage name (mutually exclusive with `id` and `alias`).
+     * @param alias             Run-scoped alias (mutually exclusive with `id` and `name`).
+     *                          Automatically assigned when no identifier is provided.
+     * @param backendOpener      A **lazy** factory that creates the sub-backend.
+     *                          Only called on a cache miss.
+     * @param backendCacheKey    Opaque key identifying the storage backend, so that the same logical
+     *                          storage opened through different clients is cached separately.
+     */
+    openStorage<TStorage extends IStorage>(cls: Constructor<TStorage>, { id, name, alias, backendOpener, backendCacheKey, }: (ExplicitStorageIdentifier | DefaultStorageIdentifier) & {
+        backendOpener: () => Promise<DatasetBackend | KeyValueStoreBackend | RequestQueueBackend>;
+        backendCacheKey: Hashable;
+    }): Promise<TStorage>;
+    /**
+     * Remove a storage instance from the cache (called from `storage.drop()`).
+     */
+    removeFromCache(instance: IStorage): void;
+    /**
+     * Clear the entire cache. Also calls `clearCache()` on any cached KeyValueStore
+     * instances (duck-typed to avoid importing KeyValueStore and circular dependencies).
+     * Called during service locator reset.
+     */
+    clearCache(): void;
+}
+/**
+ * A storage identifier where exactly one of `id`, `name`, or `alias` is specified.
+ * Produced by {@link resolveStorageIdentifier} from ambiguous user input.
+ */
+export type ExplicitStorageIdentifier = {
+    id: string;
+    name?: never;
+    alias?: never;
+} | {
+    id?: never;
+    name: string;
+    alias?: never;
+} | {
+    id?: never;
+    name?: never;
+    alias: string;
+};
+/**
+ * Represents the case where no identifier was provided — the caller wants the default storage.
+ */
+export interface DefaultStorageIdentifier {
+    id?: never;
+    name?: never;
+    alias?: never;
+}
+/**
+ * Decompose a user-provided `identifier` (the `Dataset.open()` / `KeyValueStore.open()` /
+ * `RequestQueue.open()` argument) into separate `id`, `name`, and `alias` fields that
+ * the `StorageInstanceManager` and `StorageBackend.create*Client` expect.
+ *
+ * - `null` / `undefined` / `{}` → default storage alias
+ * - `string` → resolved via `storageExists` (ID-first, then name)
+ * - `{ id }` → `{ id }`
+ * - `{ name }` → `{ name }`
+ * - `{ alias }` → `{ alias }`
+ */
+export declare function resolveStorageIdentifier(identifier: string | StorageIdentifier | null | undefined, storageBackend: StorageBackend, storageType: 'Dataset' | 'KeyValueStore' | 'RequestQueue'): Promise<ExplicitStorageIdentifier>;