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

package/memory-storage/resource-clients/request-queue.js

@@ -0,0 +1,422 @@
+import { randomUUID } from 'node:crypto';
+import { AsyncQueue } from '@sapphire/async-queue';
+import { s } from '@sapphire/shapeshift';
+import { purgeNullsFromObject, uniqueKeyToRequestId } from '../utils.js';
+import { BaseClient } from './common/base-client.js';
+const requestShape = s
+    .object({
+    id: s.string(),
+    url: s.string().url({ allowedProtocols: ['http:', 'https:'] }),
+    uniqueKey: s.string(),
+    method: s.string().optional(),
+    retryCount: s.number().int().optional(),
+    handledAt: s.union([s.string(), s.date().valid()]).optional(),
+})
+    .passthrough();
+const requestShapeWithoutId = requestShape.omit(['id']);
+const batchRequestShapeWithoutId = requestShapeWithoutId.array();
+const requestOptionsShape = s.object({
+    forefront: s.boolean().optional(),
+});
+export class RequestQueueBackend extends BaseClient {
+    name;
+    /**
+     * The key used for cache lookup. For named storages, this equals the name. For alias (unnamed)
+     * storages, this is the alias string. Falls back to id.
+     */
+    cacheKey;
+    createdAt = new Date();
+    accessedAt = new Date();
+    modifiedAt = new Date();
+    handledRequestCount = 0;
+    pendingRequestCount = 0;
+    /**
+     * Serializes every operation that reads-then-writes this backend's shared queue state — the
+     * `requests` map, the `forefrontRequestIds` array, the `inProgressRequestIds` set and the request
+     * counts. Those mutations span `await` points, so without this mutex a concurrent operation could
+     * interleave and corrupt them (e.g. a head scan pruning `forefrontRequestIds` while
+     * `addBatchOfRequests` pushes to it). Held by every mutating method as well as by `isEmpty`/
+     * `isFinished`, whose head scan also prunes `forefrontRequestIds`.
+     */
+    #queueStateMutex = new AsyncQueue();
+    #forefrontRequestIds = [];
+    /**
+     * IDs of requests currently fetched but not yet handled or reclaimed. A request in this set is
+     * "in progress" and will not be handed out again by {@link fetchNextRequest}.
+     *
+     * Unlike the file-system / platform clients, the in-memory queue lives entirely within a single
+     * process and is never shared with another consumer, so there is no need for an expiring,
+     * cross-process-visible lock — tracking in-progress requests in this set is enough.
+     */
+    #inProgressRequestIds = new Set();
+    #requests = new Map();
+    // kept as TS-private: storage-backend tests read this field at runtime
+    storageBackend;
+    constructor(options) {
+        super(options.id ?? randomUUID());
+        this.name = options.name;
+        this.cacheKey = options.cacheKey ?? this.name ?? this.id;
+        this.storageBackend = options.storageBackend;
+    }
+    async getMetadata() {
+        this.updateTimestamps(false);
+        return this.toRequestQueueInfo();
+    }
+    async drop() {
+        // Serialize against other mutators (and the head scans in `isEmpty`/`isFinished`) so a concurrent
+        // operation cannot observe half-cleared state — e.g. a forefront id whose request has already been
+        // removed, which `listPendingHead` would then dereference as `undefined`.
+        await this.#queueStateMutex.wait();
+        try {
+            const storeIndex = this.storageBackend.requestQueueBackendCache.findIndex((queue) => queue.id === this.id);
+            if (storeIndex !== -1) {
+                const [oldBackend] = this.storageBackend.requestQueueBackendCache.splice(storeIndex, 1);
+                oldBackend.pendingRequestCount = 0;
+                // Clear all in-memory state, consistent with `purge`. Clearing `requests` alone would
+                // leave dangling ids in `forefrontRequestIds`/`inProgressRequestIds`, which a later head
+                // scan would resolve to a missing request and dereference.
+                oldBackend.#requests.clear();
+                oldBackend.#forefrontRequestIds = [];
+                oldBackend.#inProgressRequestIds.clear();
+            }
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    async purge() {
+        // Serialize against other mutators (and the head scans in `isEmpty`/`isFinished`) so a concurrent
+        // operation cannot observe or repopulate half-cleared state across the `await` below.
+        await this.#queueStateMutex.wait();
+        try {
+            // Clear all in-memory state
+            this.#requests.clear();
+            this.#forefrontRequestIds = [];
+            this.#inProgressRequestIds.clear();
+            this.handledRequestCount = 0;
+            this.pendingRequestCount = 0;
+            this.updateTimestamps(true);
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    *requestKeyIterator() {
+        for (let i = this.#forefrontRequestIds.length - 1; i >= 0; i--) {
+            yield this.#forefrontRequestIds[i];
+        }
+        for (const key of this.#requests.keys()) {
+            yield key;
+        }
+    }
+    /**
+     * Scans the queue and returns the pending head — requests that are neither handled nor currently
+     * in progress — ordered by `orderNo`, deduplicated.
+     *
+     * When `detectInProgressRequests` is set, the result also carries an `hasInProgressRequests` flag
+     * telling whether any unhandled-but-in-progress request was skipped along the way. It lets
+     * {@link isFinished} distinguish "no work left at all" from "work remains, but it is currently being
+     * processed". Without it, a consumer with concurrency could consider the queue finished and shut the
+     * crawler down while it is still handling the last requests.
+     *
+     * Computing the flag is expensive: because an in-progress request may sit anywhere in the queue, it
+     * forces a scan of every pending entry even when only `limit` items are wanted. Callers that only
+     * need the head (e.g. {@link fetchNextRequest}, {@link isEmpty}) leave it off so the scan can stop as
+     * soon as the page is filled, keeping those calls O(head) instead of O(N).
+     */
+    async listPendingHead(limit, detectInProgressRequests = false) {
+        const items = [];
+        let hasInProgressRequests = false;
+        // Tracks processed request IDs to avoid duplicates (request in both `forefrontRequestIds` and `requests`).
+        const seenRequestIds = new Set();
+        // Tracks handled request IDs from `forefrontRequestIds` to be removed.
+        const handledForefrontIds = new Set();
+        for (const requestId of this.requestKeyIterator()) {
+            // Once the requested page is filled we can stop — unless the caller asked us to detect
+            // in-progress requests and we have not yet seen one, in which case we must keep scanning.
+            if (items.length >= limit && (!detectInProgressRequests || hasInProgressRequests)) {
+                break;
+            }
+            if (seenRequestIds.has(requestId)) {
+                continue;
+            }
+            seenRequestIds.add(requestId);
+            const request = this.#requests.get(requestId);
+            // Permanently-handled requests (`orderNo === null`) are in a terminal state and can be skipped.
+            if (request.orderNo === null) {
+                if (this.#forefrontRequestIds.includes(requestId)) {
+                    handledForefrontIds.add(requestId);
+                }
+                continue;
+            }
+            // In progress (fetched but not yet handled or reclaimed) — skip it, but remember that the
+            // queue is not truly empty.
+            if (this.#inProgressRequestIds.has(requestId)) {
+                hasInProgressRequests = true;
+                continue;
+            }
+            if (items.length < limit) {
+                items.push(request);
+            }
+        }
+        this.#forefrontRequestIds = this.#forefrontRequestIds.filter((id) => !handledForefrontIds.has(id));
+        return {
+            items: items.sort((a, b) => a.orderNo - b.orderNo),
+            hasInProgressRequests: detectInProgressRequests ? hasInProgressRequests : undefined,
+        };
+    }
+    async fetchNextRequest() {
+        this.updateTimestamps(false);
+        await this.#queueStateMutex.wait();
+        try {
+            const { items: [head], } = await this.listPendingHead(1);
+            if (!head) {
+                return undefined;
+            }
+            // Mark the request as in progress so it is not handed out again until it is handled or
+            // reclaimed. The request keeps its `orderNo` (and thus its forefront / normal ordering).
+            this.#inProgressRequestIds.add(head.id);
+            return this.jsonToRequest(head.json) ?? undefined;
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    async addBatchOfRequests(requests, options = {}) {
+        batchRequestShapeWithoutId.parse(requests);
+        requestOptionsShape.parse(options);
+        // Serialize against other mutators (and the head scans in `isEmpty`/`isFinished`) so that the
+        // shared `requests` map, `forefrontRequestIds` array and request counts are not corrupted by a
+        // concurrent operation interleaving at one of the `await` points below.
+        await this.#queueStateMutex.wait();
+        try {
+            const result = {
+                processedRequests: [],
+                unprocessedRequests: [],
+            };
+            for (const model of requests) {
+                const requestModel = this.createInternalRequest(model, options.forefront);
+                const existingRequestWithId = this.#requests.get(requestModel.id);
+                if (existingRequestWithId) {
+                    result.processedRequests.push({
+                        requestId: existingRequestWithId.id,
+                        uniqueKey: existingRequestWithId.uniqueKey,
+                        wasAlreadyHandled: existingRequestWithId.orderNo === null,
+                        wasAlreadyPresent: true,
+                    });
+                    continue;
+                }
+                this.#requests.set(requestModel.id, requestModel);
+                if (requestModel.orderNo) {
+                    this.pendingRequestCount += 1;
+                }
+                else {
+                    this.handledRequestCount += 1;
+                }
+                if (options.forefront) {
+                    this.#forefrontRequestIds.push(requestModel.id);
+                }
+                result.processedRequests.push({
+                    requestId: requestModel.id,
+                    uniqueKey: requestModel.uniqueKey,
+                    // We return wasAlreadyHandled: false even though the request may
+                    // have been added as handled, because that's how API behaves.
+                    wasAlreadyHandled: false,
+                    wasAlreadyPresent: false,
+                });
+            }
+            this.updateTimestamps(true);
+            return result;
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    async getRequest(uniqueKey) {
+        s.string().parse(uniqueKey);
+        this.updateTimestamps(false);
+        const id = uniqueKeyToRequestId(uniqueKey);
+        const json = this.#requests.get(id)?.json;
+        return this.jsonToRequest(json);
+    }
+    async markRequestAsHandled(request) {
+        requestShape.parse(request);
+        this.updateTimestamps(false);
+        // Serialize against other mutators (and the head scans in `isEmpty`/`isFinished`) so the shared
+        // `requests` map, `inProgressRequestIds` set and request counts stay consistent across the
+        // `await` points below.
+        await this.#queueStateMutex.wait();
+        try {
+            const id = uniqueKeyToRequestId(request.uniqueKey);
+            const existingRequest = this.#requests.get(id);
+            // The request must exist to be marked as handled. We intentionally do NOT require it to still
+            // be in progress: marking an already-released request handled must still succeed, otherwise
+            // the request could be handed out again and the queue would never finish.
+            if (!existingRequest) {
+                return undefined;
+            }
+            // A handled request has `orderNo === null`. Marking it again is an idempotent no-op.
+            const wasAlreadyHandled = existingRequest.orderNo === null;
+            const handledAt = request.handledAt ?? new Date().toISOString();
+            const requestModel = this.createInternalRequest({ ...request, handledAt }, false);
+            this.#requests.set(id, requestModel);
+            // The request is no longer in progress for this client.
+            this.#inProgressRequestIds.delete(id);
+            if (!wasAlreadyHandled) {
+                this.pendingRequestCount -= 1;
+                this.handledRequestCount += 1;
+            }
+            this.updateTimestamps(true);
+            return {
+                requestId: id,
+                wasAlreadyHandled,
+                wasAlreadyPresent: true,
+            };
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    async reclaimRequest(request, options = {}) {
+        requestShape.parse(request);
+        requestOptionsShape.parse(options);
+        this.updateTimestamps(false);
+        // Serialize against other mutators (and the head scans in `isEmpty`/`isFinished`) so the shared
+        // `requests` map, `forefrontRequestIds` array and `inProgressRequestIds` set stay consistent
+        // across the `await` points below.
+        await this.#queueStateMutex.wait();
+        try {
+            const id = uniqueKeyToRequestId(request.uniqueKey);
+            const existingRequest = this.#requests.get(id);
+            // The request must exist and not already be handled to be reclaimed. As with
+            // `markRequestAsHandled`, we do NOT require it to still be in progress — returning an
+            // already-released request to the queue (e.g. to honor a `forefront` reorder) must still
+            // work, rather than have the reclaim silently dropped.
+            if (!existingRequest || existingRequest.orderNo === null) {
+                return undefined;
+            }
+            // Reclaiming resets the `orderNo` to a fresh timestamp, restoring the request to the queue
+            // (at the front if `forefront`).
+            const requestModel = this.createInternalRequest(request, options.forefront);
+            this.#requests.set(id, requestModel);
+            // The request is no longer in progress for this client.
+            this.#inProgressRequestIds.delete(id);
+            if (options.forefront) {
+                this.#forefrontRequestIds.push(id);
+            }
+            this.updateTimestamps(true);
+            return {
+                requestId: id,
+                wasAlreadyHandled: false,
+                wasAlreadyPresent: true,
+            };
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    async isEmpty() {
+        this.updateTimestamps(false);
+        // "Empty" means there is nothing left to fetch right now — i.e. the next `fetchNextRequest`
+        // would return `null`. Requests that are currently in progress are intentionally NOT counted
+        // here: they are not fetchable, so the queue is empty from a consumer's point of view. Whether
+        // those in-progress requests mean crawling is not yet done is a separate question, answered by
+        // `isFinished`.
+        //
+        // `listPendingHead` prunes `forefrontRequestIds` as it scans, so we must hold the queue-state mutex to avoid
+        // racing a concurrent mutator (e.g. `addBatchOfRequests`) at its `await` points.
+        await this.#queueStateMutex.wait();
+        try {
+            const { items } = await this.listPendingHead(1);
+            return items.length === 0;
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    async isFinished() {
+        this.updateTimestamps(false);
+        // The queue is finished only when there is nothing left to fetch AND nothing currently in
+        // progress. Counting in-progress requests is what allows a crawler with concurrency to keep
+        // waiting while it still holds the last requests, instead of finishing prematurely.
+        //
+        // Detecting in-progress requests requires a full scan, hence the `detectInProgressRequests`
+        // flag — unlike `fetchNextRequest`/`isEmpty`, which only need the head and can stop early.
+        //
+        // `listPendingHead` prunes `forefrontRequestIds` as it scans, so we must hold the queue-state mutex to avoid
+        // racing a concurrent mutator (e.g. `addBatchOfRequests`) at its `await` points.
+        await this.#queueStateMutex.wait();
+        try {
+            const { items, hasInProgressRequests } = await this.listPendingHead(1, true);
+            return items.length === 0 && !hasInProgressRequests;
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    /**
+     * Returns all pending (not yet handled, not currently in progress) requests in the queue, ordered
+     * the same way {@link fetchNextRequest} would hand them out. This does not mutate the queue,
+     * nothing is marked in progress.
+     */
+    async listItems() {
+        this.updateTimestamps(false);
+        // `listPendingHead` prunes `forefrontRequestIds` as it scans, so we must hold the queue-state
+        // mutex to avoid racing a concurrent mutator at its `await` points.
+        await this.#queueStateMutex.wait();
+        try {
+            const { items } = await this.listPendingHead(Number.POSITIVE_INFINITY);
+            return items.map((request) => this.jsonToRequest(request.json));
+        }
+        finally {
+            this.#queueStateMutex.shift();
+        }
+    }
+    toRequestQueueInfo() {
+        return {
+            accessedAt: this.accessedAt,
+            createdAt: this.createdAt,
+            handledRequestCount: this.handledRequestCount,
+            id: this.id,
+            modifiedAt: this.modifiedAt,
+            name: this.name,
+            pendingRequestCount: this.pendingRequestCount,
+            totalRequestCount: this.#requests.size,
+        };
+    }
+    updateTimestamps(hasBeenModified) {
+        this.accessedAt = new Date();
+        if (hasBeenModified) {
+            this.modifiedAt = new Date();
+        }
+    }
+    jsonToRequest(requestJson) {
+        if (!requestJson)
+            return undefined;
+        const request = JSON.parse(requestJson);
+        return purgeNullsFromObject(request);
+    }
+    createInternalRequest(request, forefront) {
+        const orderNo = this.calculateOrderNo(request, forefront);
+        const id = uniqueKeyToRequestId(request.uniqueKey);
+        if (request.id && request.id !== id) {
+            throw new Error('Request ID does not match its uniqueKey.');
+        }
+        const json = JSON.stringify({ ...request, id });
+        return {
+            id,
+            json,
+            method: request.method,
+            orderNo,
+            retryCount: request.retryCount ?? 0,
+            uniqueKey: request.uniqueKey,
+            url: request.url,
+        };
+    }
+    calculateOrderNo(request, forefront) {
+        if (request.handledAt)
+            return null;
+        const timestamp = Date.now();
+        return forefront ? -timestamp : timestamp;
+    }
+}

package/memory-storage/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolves `segment` against `baseDirectory` and ensures the result stays within `baseDirectory`.
+ * Storage names and record keys are used as filesystem path components, so a value containing `..`
+ * or an absolute path could otherwise escape the intended directory.
+ */
+export declare function resolveWithinDirectory(baseDirectory: string, segment: string): string;
+/**
+ * Removes all properties with a null value
+ * from the provided object.
+ */
+export declare function purgeNullsFromObject<T>(object: T): T;
+/**
+ * Creates a standard request ID (same as Platform).
+ */
+export declare function uniqueKeyToRequestId(uniqueKey: string): string;
+export { isBuffer, isStream, toBuffer } from '../byte_utils.js';

package/memory-storage/utils.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+import { resolve, sep } from 'node:path';
+import { REQUEST_ID_LENGTH } from './consts.js';
+/**
+ * Resolves `segment` against `baseDirectory` and ensures the result stays within `baseDirectory`.
+ * Storage names and record keys are used as filesystem path components, so a value containing `..`
+ * or an absolute path could otherwise escape the intended directory.
+ */
+export function resolveWithinDirectory(baseDirectory, segment) {
+    const base = resolve(baseDirectory);
+    const resolved = resolve(base, segment);
+    if (resolved !== base && !resolved.startsWith(`${base}${sep}`)) {
+        throw new Error(`"${segment}" is not allowed because it would resolve outside of the storage directory. ` +
+            `Storage names and record keys must not contain path traversal segments ("..") or absolute paths.`);
+    }
+    return resolved;
+}
+/**
+ * Removes all properties with a null value
+ * from the provided object.
+ */
+export function purgeNullsFromObject(object) {
+    if (object && typeof object === 'object' && !Array.isArray(object)) {
+        for (const [key, value] of Object.entries(object)) {
+            if (value === null)
+                Reflect.deleteProperty(object, key);
+        }
+    }
+    return object;
+}
+/**
+ * Creates a standard request ID (same as Platform).
+ */
+export function uniqueKeyToRequestId(uniqueKey) {
+    const str = createHash('sha256')
+        .update(uniqueKey)
+        .digest('base64')
+        .replace(/(\+|\/|=)/g, '');
+    return str.length > REQUEST_ID_LENGTH ? str.slice(0, REQUEST_ID_LENGTH) : str;
+}
+export { isBuffer, isStream, toBuffer } from '../byte_utils.js';

package/owned_or_injected.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Captures the "inject-or-default" ownership pattern for a crawler's stateful collaborators (session pool, browser
+ * pool, the crawler-opened request queue, ...). A collaborator is either **injected** by the user (borrowed — the
+ * crawler never drives its lifecycle) or **built by the crawler** as a default (owned — the crawler sequences its
+ * lifecycle). Owned-only lifecycle hooks are gated through a single {@link OwnedOrInjected.ifOwned|`ifOwned()`}.
+ *
+ * This is the deliberate complement to the {@link ServiceLocator}: ambient infrastructure (config/events/storage/
+ * logger) stays in the locator, while crawler-scoped stateful collaborators the crawler sequences go through this.
+ *
+ * @internal
+ */
+export declare class OwnedOrInjected<Injected, Owned extends Injected = Injected> {
+    #private;
+    private constructor();
+    /**
+     * Resolves a collaborator from an optionally-injected instance. `Injected` is the public/borrowed type exposed via
+     * {@link OwnedOrInjected.value|`value`}; `Owned` is the concrete type the crawler builds (a subtype with extra
+     * lifecycle methods), which {@link OwnedOrInjected.set|`set()`} and {@link OwnedOrInjected.ifOwned|`ifOwned()`}
+     * deal in — so owned-only lifecycle hooks are statically typed with no casts.
+     *
+     * - `injected` provided → borrowed (present, not owned).
+     * - `injected` omitted → owned; `buildDefault` fills the slot eagerly if given, otherwise it stays empty until a
+     *   later {@link OwnedOrInjected.set|`set()`} (the lazy case, e.g. a request queue opened on first use).
+     */
+    static resolve<Injected, Owned extends Injected = Injected>(injected?: Injected, buildDefault?: () => Owned): OwnedOrInjected<Injected, Owned>;
+    /**
+     * Whether the crawler owns the instance and is therefore responsible for its lifecycle. `true` only for
+     * crawler-built defaults, `false` for user-injected instances.
+     */
+    get isOwned(): boolean;
+    /**
+     * Whether a value is currently available. `false` for an owned slot whose default hasn't been built yet
+     * (e.g. a lazily-opened request queue before its first use).
+     */
+    get isPresent(): boolean;
+    /**
+     * The resolved instance, typed as the public `Injected` type. Throws if the value is not present yet — callers that
+     * expect a lazily-filled owned slot should read {@link OwnedOrInjected.maybeValue|`maybeValue`} instead.
+     */
+    get value(): Injected;
+    /**
+     * The resolved instance, or `undefined` when a lazily-filled owned slot hasn't been built yet. The non-throwing
+     * counterpart to {@link OwnedOrInjected.value|`value`} — pairs naturally with `?? fallback` so callers can read
+     * a possibly-empty slot without the `isPresent ? value : …` dance.
+     */
+    get maybeValue(): Injected | undefined;
+    /**
+     * Fills the (owned) slot with the crawler-built default, returning it for convenience. Only valid on an owned,
+     * not-yet-filled slot: borrowed instances are never replaced and an owned slot is filled exactly once (re-setting
+     * would silently orphan the previous instance's lifecycle).
+     */
+    set(value: Owned): Owned;
+    /**
+     * Runs an owned-only lifecycle hook, invoked (with the value typed as the concrete `Owned`) only when the crawler
+     * owns a present instance — a no-op for a borrowed instance or an owned-but-not-yet-built slot.
+     */
+    ifOwned<R>(fn: (value: Owned) => R | Promise<R>): Promise<R | undefined>;
+}

package/owned_or_injected.js

@@ -0,0 +1,98 @@
+/**
+ * Captures the "inject-or-default" ownership pattern for a crawler's stateful collaborators (session pool, browser
+ * pool, the crawler-opened request queue, ...). A collaborator is either **injected** by the user (borrowed — the
+ * crawler never drives its lifecycle) or **built by the crawler** as a default (owned — the crawler sequences its
+ * lifecycle). Owned-only lifecycle hooks are gated through a single {@link OwnedOrInjected.ifOwned|`ifOwned()`}.
+ *
+ * This is the deliberate complement to the {@link ServiceLocator}: ambient infrastructure (config/events/storage/
+ * logger) stays in the locator, while crawler-scoped stateful collaborators the crawler sequences go through this.
+ *
+ * @internal
+ */
+export class OwnedOrInjected {
+    #value;
+    #owned;
+    #present;
+    constructor(value, owned, present) {
+        this.#value = value;
+        this.#owned = owned;
+        this.#present = present;
+    }
+    /**
+     * Resolves a collaborator from an optionally-injected instance. `Injected` is the public/borrowed type exposed via
+     * {@link OwnedOrInjected.value|`value`}; `Owned` is the concrete type the crawler builds (a subtype with extra
+     * lifecycle methods), which {@link OwnedOrInjected.set|`set()`} and {@link OwnedOrInjected.ifOwned|`ifOwned()`}
+     * deal in — so owned-only lifecycle hooks are statically typed with no casts.
+     *
+     * - `injected` provided → borrowed (present, not owned).
+     * - `injected` omitted → owned; `buildDefault` fills the slot eagerly if given, otherwise it stays empty until a
+     *   later {@link OwnedOrInjected.set|`set()`} (the lazy case, e.g. a request queue opened on first use).
+     */
+    static resolve(injected, buildDefault) {
+        if (injected !== undefined) {
+            return new OwnedOrInjected(injected, false, true);
+        }
+        if (buildDefault !== undefined) {
+            return new OwnedOrInjected(buildDefault(), true, true);
+        }
+        return new OwnedOrInjected(undefined, true, false);
+    }
+    /**
+     * Whether the crawler owns the instance and is therefore responsible for its lifecycle. `true` only for
+     * crawler-built defaults, `false` for user-injected instances.
+     */
+    get isOwned() {
+        return this.#owned;
+    }
+    /**
+     * Whether a value is currently available. `false` for an owned slot whose default hasn't been built yet
+     * (e.g. a lazily-opened request queue before its first use).
+     */
+    get isPresent() {
+        return this.#present;
+    }
+    /**
+     * The resolved instance, typed as the public `Injected` type. Throws if the value is not present yet — callers that
+     * expect a lazily-filled owned slot should read {@link OwnedOrInjected.maybeValue|`maybeValue`} instead.
+     */
+    get value() {
+        if (!this.#present) {
+            throw new Error('OwnedOrInjected value is not initialized yet');
+        }
+        return this.#value;
+    }
+    /**
+     * The resolved instance, or `undefined` when a lazily-filled owned slot hasn't been built yet. The non-throwing
+     * counterpart to {@link OwnedOrInjected.value|`value`} — pairs naturally with `?? fallback` so callers can read
+     * a possibly-empty slot without the `isPresent ? value : …` dance.
+     */
+    get maybeValue() {
+        return this.#present ? this.#value : undefined;
+    }
+    /**
+     * Fills the (owned) slot with the crawler-built default, returning it for convenience. Only valid on an owned,
+     * not-yet-filled slot: borrowed instances are never replaced and an owned slot is filled exactly once (re-setting
+     * would silently orphan the previous instance's lifecycle).
+     */
+    set(value) {
+        if (!this.#owned) {
+            throw new Error('Cannot set() a borrowed OwnedOrInjected value');
+        }
+        if (this.#present) {
+            throw new Error('OwnedOrInjected value is already initialized');
+        }
+        this.#value = value;
+        this.#present = true;
+        return value;
+    }
+    /**
+     * Runs an owned-only lifecycle hook, invoked (with the value typed as the concrete `Owned`) only when the crawler
+     * owns a present instance — a no-op for a borrowed instance or an owned-but-not-yet-built slot.
+     */
+    async ifOwned(fn) {
+        if (!this.#owned || !this.#present) {
+            return undefined;
+        }
+        return fn(this.#value);
+    }
+}