Skip to content

Crawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.

refactor: Introduce OwnedOrInjected dependency tracking helper (#3891)

Jan Bucharec5ff9ba17c0
diff --git a/docs/public-api/crawlee-basic.api.md b/docs/public-api/crawlee-basic.api.md
index 1c4e81882..e079855b7 100644
--- a/docs/public-api/crawlee-basic.api.md
+++ b/docs/public-api/crawlee-basic.api.md
@@ -167,7 +167,7 @@ export class BasicCrawler<Context extends CrawlingContext = CrawlingContext, Con
running: boolean;
// (undocumented)
protected runRequestHandler(crawlingContext: ExtendedContext): Promise<void>;
- readonly sessionPool: ISessionPool;
+ get sessionPool(): ISessionPool;
setStatusMessage(message: string, options?: SetStatusMessageOptions): void;
readonly stats: Statistics;
stop(reason?: string): void;
diff --git a/docs/upgrading/upgrading_v4.md b/docs/upgrading/upgrading_v4.md
index f662680fd..40a8c46bc 100644
--- a/docs/upgrading/upgrading_v4.md
+++ b/docs/upgrading/upgrading_v4.md
@@ -266,6 +266,8 @@ const crawler = new BasicCrawler({
The returned objects must be `Session` instances — the rest of the crawler relies on `session.markGood()`, `session.cookieJar`, `session.proxyInfo`, and the rest of the concrete `Session` API.
+The `crawler.sessionPool` property is now **read-only** (a getter). It was previously a writable field, so any code that reassigned it after construction (`crawler.sessionPool = myPool`) no longer works — pass your pool via the `sessionPool` constructor option instead.
+
## `retireOnBlockedStatusCodes` is removed from `Session`
`Session.retireOnBlockedStatusCodes` is removed. Blocked status code handling is now internal to the crawler. Configure blocked status codes via the `blockedStatusCodes` crawler option (moved from `sessionPoolOptions`).
@@ -317,6 +319,8 @@ await crawler.run();
await sharedPool.destroy();
```
+The `crawler.browserPool` property is now **read-only** (a getter). It was previously a writable field, so any code that reassigned it after construction (`crawler.browserPool = myPool`) no longer works — pass your pool via the `browserPool` constructor option instead.
+
## `BrowserCrawlingContext.browserController` has been removed
The `browserController` property is no longer part of the crawling context (`BrowserCrawlingContext`). Browser controller management is now fully internal to the pool — the crawler interacts with the pool only through the `IBrowserPool` interface (`newPage`, `closePage`, `extractPageState`, and `injectPageState`).
diff --git a/packages/basic-crawler/src/internals/basic-crawler.ts b/packages/basic-crawler/src/internals/basic-crawler.ts
index 5c4283ac9..1b6f665db 100644
--- a/packages/basic-crawler/src/internals/basic-crawler.ts
+++ b/packages/basic-crawler/src/internals/basic-crawler.ts
@@ -48,6 +48,7 @@ import {
MissingSessionError,
NavigationSkippedError,
NonRetryableError,
+ OwnedOrInjected,
purgeDefaultStorages,
RequestHandlerError,
RequestManagerTandem,
@@ -596,26 +597,23 @@ export class BasicCrawler<
*/
protected requestManager?: IRequestManager;
+ /** Backs the {@apilink BasicCrawler.sessionPool|`sessionPool`} getter. */
+ private sessionPoolDep: OwnedOrInjected<ISessionPool, SessionPool>;
+
/**
* A reference to the underlying session pool that manages the crawler's {@apilink Session|sessions}. Typed as
* {@apilink ISessionPool} so custom implementations can be plugged in via the `sessionPool` constructor option.
*/
- readonly sessionPool: ISessionPool;
-
- /**
- * Set when the crawler constructed its own {@apilink SessionPool} (no `sessionPool` option was provided).
- * Holds the same instance as `sessionPool`, but typed as the concrete class so the crawler can call
- * lifecycle methods (`resetStore`, `teardown`) that aren't part of {@apilink ISessionPool}. A user-supplied
- * pool is never owned and never torn down by the crawler.
- */
- private ownedSessionPool?: SessionPool;
+ get sessionPool(): ISessionPool {
+ return this.sessionPoolDep.value;
+ }
/**
- * Set when the crawler constructed its own request manager (no `requestManager`, `requestQueue`, or `requestList`
- * option was provided). The owned manager is purged (not dropped) between repeated `run()` calls.
- * A user-supplied manager is never purged by the crawler.
+ * Tracks **only** the queue the crawler opens for itself — not the {@apilink RequestManagerTandem} that may wrap it
+ * around a user-supplied `requestList` — so the owned-only purge between repeated `run()` calls never reaches
+ * through to a borrowed loader. Filled lazily in {@apilink BasicCrawler.openOwnedRequestQueue|`openOwnedRequestQueue()`}.
*/
- private ownedRequestManager?: IRequestManager;
+ private ownedRequestQueue = OwnedOrInjected.resolve<RequestQueue>();
/**
* Whether the request-processing-time hint has already been forwarded to the request manager. The hint
@@ -921,19 +919,18 @@ export class BasicCrawler<
);
}
- if (sessionPool) {
- this.sessionPool = sessionPool;
- } else {
- this.ownedSessionPool = new SessionPool({
- createSessionFunction: async (opts) =>
- new Session({
- ...opts?.sessionOptions,
- proxyInfo:
- opts?.sessionOptions?.proxyInfo ?? (await this.proxyConfiguration?.newProxyInfo()),
- }),
- });
- this.sessionPool = this.ownedSessionPool;
- }
+ this.sessionPoolDep = OwnedOrInjected.resolve(
+ sessionPool,
+ () =>
+ new SessionPool({
+ createSessionFunction: async (opts) =>
+ new Session({
+ ...opts?.sessionOptions,
+ proxyInfo:
+ opts?.sessionOptions?.proxyInfo ?? (await this.proxyConfiguration?.newProxyInfo()),
+ }),
+ }),
+ );
this.blockedStatusCodes = new Set(blockedStatusCodesInput ?? BLOCKED_STATUS_CODES);
@@ -1373,12 +1370,12 @@ export class BasicCrawler<
// we need to purge the RQ to allow processing the same requests again — this is important so users can
// pass in failed requests back to the `crawler.run()`, otherwise they would be considered as handled and
// ignored — as a failed request is still handled.
- // By default (purgeRequestQueue unset or true), only the manager we created ourselves (ownedRequestManager) is purged.
+ // By default (`purgeRequestQueue` unset), only the queue we opened ourselves is purged.
// When `purgeRequestQueue` is explicitly `true`, we also purge a user-supplied manager.
// When `purgeRequestQueue` is explicitly `false`, nothing is purged.
const shouldPurge = purgeRequestQueue !== false;
const managerToPurge =
- this.ownedRequestManager ?? (purgeRequestQueue === true ? this.requestManager : undefined);
+ this.ownedRequestQueue.maybeValue ?? (purgeRequestQueue === true ? this.requestManager : undefined);
if (managerToPurge?.purge && shouldPurge) {
await managerToPurge.purge();
@@ -1386,7 +1383,7 @@ export class BasicCrawler<
this.stats.reset();
await this.stats.resetStore();
- await this.ownedSessionPool?.resetStore();
+ await this.sessionPoolDep.ifOwned((pool) => pool.resetStore());
}
this.unexpectedStop = false;
@@ -1528,17 +1525,16 @@ export class BasicCrawler<
/**
* Opens the default {@apilink RequestQueue}, applies the crawler's timeouts to it and records it as the
- * crawler-owned manager (so it gets purged between repeated `run()` calls).
+ * crawler-owned queue (so it gets purged between repeated `run()` calls).
* @private
*/
- private async openOwnedRequestQueue(): Promise<IRequestManager> {
+ private async openOwnedRequestQueue(): Promise<RequestQueue> {
// The first crawler instance uses the default queue (null identifier);
// subsequent instances get their own queue via a unique alias so they don't collide.
const identifier = this.identity.instanceIndex === 0 ? null : { alias: `__default_${this.identity.id}__` };
const requestQueue = await RequestQueue.open(identifier, { config: serviceLocator.getConfiguration() });
- this.ownedRequestManager = requestQueue;
- return requestQueue;
+ return this.ownedRequestQueue.set(requestQueue);
}
/**
@@ -2343,17 +2339,12 @@ export class BasicCrawler<
serviceLocator.getEventManager().emit(EventType.PERSIST_STATE, { isMigrating: false });
}
- if (this.ownsSessionPool) {
- await this.sessionPool.teardown({ persistState: this._ownsEventManager });
- }
-
+ await this.sessionPoolDep.ifOwned(async (pool) => pool.teardown({ persistState: this._ownsEventManager }));
if (this._ownsEventManager) {
await serviceLocator.getEventManager().close();
}
- await this.ownedSessionPool?.teardown();
-
await this.autoscaledPool?.abort();
}
diff --git a/packages/browser-crawler/src/internals/browser-crawler.ts b/packages/browser-crawler/src/internals/browser-crawler.ts
index da8e3e17d..9ccd68c07 100644
--- a/packages/browser-crawler/src/internals/browser-crawler.ts
+++ b/packages/browser-crawler/src/internals/browser-crawler.ts
@@ -21,6 +21,7 @@ import {
enqueueLinks,
handleRequestTimeout,
NavigationSkippedError,
+ OwnedOrInjected,
RequestState,
resolveBaseUrlForEnqueueLinksFiltering,
SessionError,
@@ -53,6 +54,13 @@ interface BaseResponse {
status(): number;
}
+/**
+ * The type of a browser pool the crawler builds (and therefore owns) for itself. It's an {@apilink IBrowserPool} that
+ * additionally exposes `destroy()` — the crawler only ever tears down pools it created, which is why {@apilink IBrowserPool}
+ * itself intentionally omits `destroy`.
+ */
+type OwnedBrowserPool<Page> = IBrowserPool<Page> & { destroy: () => Promise<void> };
+
type ContextDifference<T, U> = Omit<U, keyof T> & Partial<U>;
export interface BrowserCrawlingContext<
@@ -334,18 +342,16 @@ export abstract class BrowserCrawler<
ExtendedContext extends Context = Context & ContextExtension,
GoToOptions extends Dictionary = Dictionary,
> extends BasicCrawler<Context, ContextExtension, ExtendedContext> {
+ /** Backs the {@apilink BrowserCrawler.browserPool|`browserPool`} getter. */
+ private browserPoolDep: OwnedOrInjected<IBrowserPool<Page>, OwnedBrowserPool<Page>>;
+
/**
* A reference to the underlying browser pool that manages the crawler's browsers. Typed as
* {@apilink IBrowserPool} so custom implementations can be plugged in via the `browserPool` constructor option.
*/
- browserPool: IBrowserPool<Page>;
-
- /**
- * Set when the crawler constructed its own pool (a {@apilink BrowserPool}, or a {@apilink RemoteBrowserPool}
- * built from the `remoteBrowser` option). Holds the same instance as `browserPool` but is the only reference
- * the crawler tears down — a user-supplied `browserPool` is never owned and never destroyed by the crawler.
- */
- private ownedBrowserPool?: { destroy: () => Promise<void> };
+ get browserPool(): IBrowserPool<Page> {
+ return this.browserPoolDep.value;
+ }
launchContext: BrowserLaunchContext<LaunchOptions, unknown>;
@@ -445,39 +451,37 @@ export abstract class BrowserCrawler<
this.saveResponseCookies = saveResponseCookies;
- // `browserPool` wins over `remoteBrowser` — a passed-in pool is used as-is, the sugar is ignored.
- if (browserPool) {
- this.browserPool = browserPool;
- return;
- }
-
- const resolvedBrowserPoolOptions = browserPoolOptions ?? ({} as Partial<BrowserPoolOptions>);
+ // `browserPool` wins over `remoteBrowser` — a passed-in pool is used as-is (borrowed), the sugar is ignored.
+ // The default is only built when no pool was injected, so all the option/launchContext fiddling below stays
+ // inside the factory.
+ this.browserPoolDep = OwnedOrInjected.resolve(browserPool, () => {
+ const resolvedBrowserPoolOptions = browserPoolOptions ?? ({} as Partial<BrowserPoolOptions>);
- if (launchContext?.userAgent) {
- if (resolvedBrowserPoolOptions.useFingerprints)
- this.log.info('Custom user agent provided, disabling automatic browser fingerprint injection!');
- resolvedBrowserPoolOptions.useFingerprints = false;
- }
+ if (launchContext?.userAgent) {
+ if (resolvedBrowserPoolOptions.useFingerprints)
+ this.log.info('Custom user agent provided, disabling automatic browser fingerprint injection!');
+ resolvedBrowserPoolOptions.useFingerprints = false;
+ }
- if (remoteBrowser) {
- // The crawler already built the right plugin for its browser — hand it to a RemoteBrowserPool so the
- // remote connection is always for the matching browser (no plugin to construct, no way to mismatch).
- const { browserPlugins, ...remoteBrowserPoolOptions } = resolvedBrowserPoolOptions;
- const remotePool = new RemoteBrowserPool({
- browserPlugins: browserPlugins as BrowserPlugin[],
- ...remoteBrowser,
- browserPoolOptions: remoteBrowserPoolOptions as any,
- });
- this.ownedBrowserPool = remotePool;
- this.browserPool = remotePool as IBrowserPool<Page>;
- return;
- }
+ if (remoteBrowser) {
+ // The crawler already built the right plugin for its browser — hand it to a RemoteBrowserPool so the
+ // remote connection is always for the matching browser (no plugin to construct, no way to mismatch).
+ const { browserPlugins, ...remoteBrowserPoolOptions } = resolvedBrowserPoolOptions;
+ return new RemoteBrowserPool({
+ browserPlugins: browserPlugins as BrowserPlugin[],
+ ...remoteBrowser,
+ browserPoolOptions: remoteBrowserPoolOptions as any,
+ }) as OwnedBrowserPool<Page>;
+ }
- const ownedBrowserPool = new BrowserPool<InternalBrowserPoolOptions>({
- ...(resolvedBrowserPoolOptions as any),
+ // Double cast: `BrowserPool` implements `IBrowserPool<PageReturn>`, where `PageReturn` is derived from the
+ // plugin/controller generics and doesn't overlap with the crawler's free `Page` type param, so TS won't
+ // narrow it directly. The concrete pool does satisfy the `Page`/`destroy` contract at runtime — this is the
+ // long-standing `Page` variance gap, not a `destroy`-related hole.
+ return new BrowserPool<InternalBrowserPoolOptions>({
+ ...(resolvedBrowserPoolOptions as any),
+ }) as unknown as OwnedBrowserPool<Page>;
});
- this.ownedBrowserPool = ownedBrowserPool;
- this.browserPool = ownedBrowserPool as IBrowserPool<Page>;
}
protected override buildContextPipeline(): ContextPipeline<
@@ -758,7 +762,7 @@ export abstract class BrowserCrawler<
* @ignore
*/
override async teardown(): Promise<void> {
- await this.ownedBrowserPool?.destroy();
+ await this.browserPoolDep.ifOwned((pool) => pool.destroy());
await super.teardown();
}
}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index ee84b93af..bff597a44 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -6,6 +6,7 @@ export * from './crawlers/index.js';
export * from './enqueue_links/index.js';
export * from './events/index.js';
export * from './log.js';
+export * from './owned_or_injected.js';
export * from './proxy_configuration.js';
export * from './request.js';
export * from './router.js';
diff --git a/packages/core/src/owned_or_injected.ts b/packages/core/src/owned_or_injected.ts
new file mode 100644
index 000000000..15ce7a33d
--- /dev/null
+++ b/packages/core/src/owned_or_injected.ts
@@ -0,0 +1,116 @@
+/**
+ * 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 {@apilink OwnedOrInjected.ifOwned|`ifOwned()`}.
+ *
+ * This is the deliberate complement to the {@apilink 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<Injected, Owned extends Injected = Injected> {
+ private _value: Injected | undefined;
+ private readonly _owned: boolean;
+ private _present: boolean;
+
+ private constructor(value: Injected | undefined, owned: boolean, present: boolean) {
+ 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
+ * {@apilink OwnedOrInjected.value|`value`}; `Owned` is the concrete type the crawler builds (a subtype with extra
+ * lifecycle methods), which {@apilink OwnedOrInjected.set|`set()`} and {@apilink 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 {@apilink 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> {
+ if (injected !== undefined) {
+ return new OwnedOrInjected<Injected, Owned>(injected, false, true);
+ }
+
+ if (buildDefault !== undefined) {
+ return new OwnedOrInjected<Injected, Owned>(buildDefault(), true, true);
+ }
+
+ return new OwnedOrInjected<Injected, Owned>(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(): boolean {
+ 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(): boolean {
+ 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 {@apilink OwnedOrInjected.maybeValue|`maybeValue`} instead.
+ */
+ get value(): Injected {
+ if (!this._present) {
+ throw new Error('OwnedOrInjected value is not initialized yet');
+ }
+
+ return this._value as Injected;
+ }
+
+ /**
+ * The resolved instance, or `undefined` when a lazily-filled owned slot hasn't been built yet. The non-throwing
+ * counterpart to {@apilink OwnedOrInjected.value|`value`} — pairs naturally with `?? fallback` so callers can read
+ * a possibly-empty slot without the `isPresent ? value : …` dance.
+ */
+ get maybeValue(): Injected | undefined {
+ return this._present ? (this._value as 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 {
+ 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<R>(fn: (value: Owned) => R | Promise<R>): Promise<R | undefined> {
+ if (!this._owned || !this._present) {
+ return undefined;
+ }
+
+ return fn(this._value as Owned);
+ }
+}
diff --git a/test/core/owned_or_injected.test.ts b/test/core/owned_or_injected.test.ts
new file mode 100644
index 000000000..e81a1b964
--- /dev/null
+++ b/test/core/owned_or_injected.test.ts
@@ -0,0 +1,180 @@
+import { OwnedOrInjected } from '../../packages/core/src/owned_or_injected.js';
+
+describe('OwnedOrInjected', () => {
+ describe('resolve() with an injected instance', () => {
+ it('is present and not owned', () => {
+ const injected = { name: 'injected' };
+ const dep = OwnedOrInjected.resolve(injected);
+
+ expect(dep.isPresent).toBe(true);
+ expect(dep.isOwned).toBe(false);
+ expect(dep.value).toBe(injected);
+ });
+
+ it('does not run owned-only lifecycle hooks', async () => {
+ const dep = OwnedOrInjected.resolve({ name: 'injected' });
+ const hook = vitest.fn();
+
+ const result = await dep.ifOwned(hook);
+
+ expect(hook).not.toHaveBeenCalled();
+ expect(result).toBeUndefined();
+ });
+
+ it('cannot be set() over a borrowed instance', () => {
+ const dep = OwnedOrInjected.resolve({ name: 'injected' });
+
+ expect(() => dep.set({ name: 'replacement' })).toThrow('borrowed');
+ });
+
+ it('ignores the buildDefault factory when an instance is injected', () => {
+ const injected = { name: 'injected' };
+ const factory = vitest.fn(() => ({ name: 'default' }));
+
+ const dep = OwnedOrInjected.resolve(injected, factory);
+
+ expect(factory).not.toHaveBeenCalled();
+ expect(dep.isOwned).toBe(false);
+ expect(dep.value).toBe(injected);
+ });
+ });
+
+ describe('resolve() with a buildDefault factory', () => {
+ it('builds the default eagerly, owned and present', () => {
+ const built = { name: 'default' };
+ const factory = vitest.fn(() => built);
+
+ const dep = OwnedOrInjected.resolve<{ name: string }>(undefined, factory);
+
+ expect(factory).toHaveBeenCalledTimes(1);
+ expect(dep.isOwned).toBe(true);
+ expect(dep.isPresent).toBe(true);
+ expect(dep.value).toBe(built);
+ });
+
+ it('runs owned-only lifecycle hooks on the built default', async () => {
+ const dep = OwnedOrInjected.resolve<{ closed: boolean }>(undefined, () => ({ closed: false }));
+
+ await dep.ifOwned((value) => {
+ value.closed = true;
+ });
+
+ expect(dep.value.closed).toBe(true);
+ });
+ });
+
+ describe('resolve() without an injected instance or factory', () => {
+ it('is owned but not present until set()', () => {
+ const dep = OwnedOrInjected.resolve<{ name: string }>();
+
+ expect(dep.isOwned).toBe(true);
+ expect(dep.isPresent).toBe(false);
+ });
+
+ it('throws when reading value before it is set', () => {
+ const dep = OwnedOrInjected.resolve<{ name: string }>();
+
+ expect(() => dep.value).toThrow('not initialized');
+ });
+
+ it('does not run owned-only lifecycle hooks while unset', async () => {
+ const dep = OwnedOrInjected.resolve<{ name: string }>();
+ const hook = vitest.fn();
+
+ await dep.ifOwned(hook);
+
+ expect(hook).not.toHaveBeenCalled();
+ });
+
+ it('becomes present after set() and returns the value', () => {
+ const dep = OwnedOrInjected.resolve<{ name: string }>();
+ const built = { name: 'default' };
+
+ const returned = dep.set(built);
+
+ expect(returned).toBe(built);
+ expect(dep.isPresent).toBe(true);
+ expect(dep.value).toBe(built);
+ expect(dep.isOwned).toBe(true);
+ });
+
+ it('exposes maybeValue as undefined while unset and the value once set', () => {
+ const dep = OwnedOrInjected.resolve<{ name: string }>();
+ expect(dep.maybeValue).toBeUndefined();
+
+ const built = { name: 'default' };
+ dep.set(built);
+
+ expect(dep.maybeValue).toBe(built);
+ });
+
+ it('cannot be set() twice', () => {
+ const dep = OwnedOrInjected.resolve<{ name: string }>();
+ dep.set({ name: 'default' });
+
+ expect(() => dep.set({ name: 'again' })).toThrow('already initialized');
+ });
+
+ it('runs owned-only lifecycle hooks once present', async () => {
+ const dep = OwnedOrInjected.resolve<{ name: string }>();
+ const built = { name: 'default' };
+ dep.set(built);
+
+ const hook = vitest.fn(async (value: { name: string }) => `torn down ${value.name}`);
+ const result = await dep.ifOwned(hook);
+
+ expect(hook).toHaveBeenCalledWith(built);
+ expect(result).toBe('torn down default');
+ });
+ });
+
+ describe('distinct Injected / Owned types', () => {
+ interface Borrowed {
+ use(): void;
+ }
+ class Built implements Borrowed {
+ use(): void {}
+ teardown(): string {
+ return 'torn down';
+ }
+ }
+
+ it('exposes value as the Injected type and ifOwned as the Owned type', async () => {
+ const dep = OwnedOrInjected.resolve<Borrowed, Built>(undefined, () => new Built());
+
+ // value is the borrowed/public type
+ const asBorrowed: Borrowed = dep.value;
+ expect(asBorrowed).toBeInstanceOf(Built);
+
+ // ifOwned hands over the concrete owned type — teardown() is only on Built, no cast needed
+ const result = await dep.ifOwned((pool) => pool.teardown());
+ expect(result).toBe('torn down');
+ });
+
+ it('does not run the owned lifecycle for an injected Borrowed instance', async () => {
+ const injected: Borrowed = { use() {} };
+ const dep = OwnedOrInjected.resolve<Borrowed, Built>(injected, () => new Built());
+
+ const hook = vitest.fn((pool: Built) => pool.teardown());
+ const result = await dep.ifOwned(hook);
+
+ expect(hook).not.toHaveBeenCalled();
+ expect(result).toBeUndefined();
+ });
+ });
+
+ describe('ifOwned()', () => {
+ it('awaits async lifecycle hooks', async () => {
+ const dep = OwnedOrInjected.resolve<{ closed: boolean }>();
+ const instance = { closed: false };
+ dep.set(instance);
+
+ await dep.ifOwned(async (value) => {
+ await new Promise((resolve) => setTimeout(resolve, 1));
+ value.closed = true;
+ });
+
+ expect(instance.closed).toBe(true);
+ });
+ });
+});