@tstdl/base 0.92.167 → 0.93.0

package/browser/browser-context-controller.d.ts

@@ -1,6 +1,4 @@
 import type { BrowserContext, Page } from 'playwright';
-import type { AsyncDisposable } from '../disposable/disposable.js';
-import { disposeAsync } from '../disposable/disposable.js';
 import type { Resolvable } from '../injector/interfaces.js';
 import { afterResolve, resolveArgumentType } from '../injector/interfaces.js';
 import type { Logger } from '../logger/logger.js';
@@ -20,14 +18,14 @@ export type BrowserContextState = Tagged<Record<string | number, unknown>, 'Brow
 export type BrowserContextControllerArgument = NewBrowserContextOptions;
 export declare class BrowserContextController implements AsyncDisposable, Resolvable<BrowserContextControllerArgument> {
     #private;
-    /** @deprecated should be avoided */
+    /** @deprecated direct usage of underlying page object should be avoided */
     readonly context: BrowserContext;
     readonly options: BrowserContextControllerOptions;
     readonly [resolveArgumentType]: BrowserContextControllerArgument;
     constructor(context: BrowserContext, options?: BrowserContextControllerOptions);
     [afterResolve](): void;
     initialize(): void;
-    [disposeAsync](): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     pages(): PageController[];
     /**
      * Get a controller for the page.

package/browser/browser-context-controller.js

@@ -7,7 +7,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { disposeAsync } from '../disposable/disposable.js';
 import { Injectable } from '../injector/decorators.js';
 import { afterResolve, resolveArgumentType } from '../injector/interfaces.js';
 import { filterUndefinedFromRecord } from '../utils/object/object.js';
@@ -17,7 +16,7 @@ import { PageController } from './page-controller.js';
 import { attachLogger } from './utils.js';
 let BrowserContextController = class BrowserContextController {
     #pageControllers = new WeakMap();
-    /** @deprecated should be avoided */
+    /** @deprecated direct usage of underlying page object should be avoided */
     context;
     options;
     constructor(context, options = {}) {
@@ -32,7 +31,7 @@ let BrowserContextController = class BrowserContextController {
             page.once('close', () => this.#pageControllers.delete(page));
         });
     }
-    async [disposeAsync]() {
+    async [Symbol.asyncDispose]() {
         await this.close();
     }
     pages() {
@@ -91,7 +90,7 @@ let BrowserContextController = class BrowserContextController {
         }
     }
     async waitForClose() {
-        return new Promise((resolve) => this.context.once('close', () => resolve()));
+        await new Promise((resolve) => this.context.once('close', () => resolve()));
     }
     attachLogger(logger) {
         attachLogger(this.context, logger);
@@ -108,8 +107,8 @@ BrowserContextController = __decorate([
                 const { context: browserContext, controllerOptions } = await browserController.newRawContext(argument);
                 value.context = browserContext;
                 value.options = controllerOptions;
-            }
-        }
+            },
+        },
     }),
     __metadata("design:paramtypes", [Object, Object])
 ], BrowserContextController);

package/browser/browser-controller.d.ts

@@ -1,6 +1,4 @@
 import type { Browser, BrowserContext } from 'playwright';
-import type { AsyncDisposable } from '../disposable/disposable.js';
-import { disposeAsync } from '../disposable/disposable.js';
 import type { Resolvable, resolveArgumentType } from '../injector/interfaces.js';
 import type { Record } from '../types/index.js';
 import type { BrowserContextControllerOptions, BrowserContextState, NewPageOptions } from './browser-context-controller.js';
@@ -29,12 +27,12 @@ export type NewBrowserContextOptions = {
 };
 export type BrowserControllerArgument = NewBrowserOptions;
 export declare class BrowserController implements AsyncDisposable, Resolvable<BrowserControllerArgument> {
-    /** @deprecated should be avoided */
+    /** @deprecated direct usage of underlying browser object should be avoided */
     readonly browser: Browser;
     readonly options: BrowserControllerOptions | undefined;
     readonly [resolveArgumentType]: BrowserControllerArgument;
     constructor(browser: Browser, options?: BrowserControllerOptions);
-    [disposeAsync](): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * @deprecated for internal use
      */

package/browser/browser-controller.js

@@ -7,7 +7,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { disposeAsync } from '../disposable/disposable.js';
 import { Injectable } from '../injector/decorators.js';
 import { inject } from '../injector/inject.js';
 import { filterUndefinedFromRecord } from '../utils/object/object.js';
@@ -16,14 +15,14 @@ import { BrowserContextController } from './browser-context-controller.js';
 import { BrowserService } from './browser.service.js';
 import { mergeNewBrowserContextOptions } from './utils.js';
 let BrowserController = class BrowserController {
-    /** @deprecated should be avoided */
+    /** @deprecated direct usage of underlying browser object should be avoided */
     browser;
     options;
     constructor(browser, options) {
         this.browser = browser;
         this.options = options;
     }
-    async [disposeAsync]() {
+    async [Symbol.asyncDispose]() {
         await this.close();
     }
     /**
@@ -64,7 +63,7 @@ let BrowserController = class BrowserController {
         }
     }
     async waitForClose() {
-        return await new Promise((resolve) => {
+        await new Promise((resolve) => {
             if (!this.browser.isConnected()) {
                 resolve();
             }

package/browser/browser.service.d.ts

@@ -1,6 +1,4 @@
 import type { Browser, LaunchOptions } from 'playwright';
-import type { AsyncDisposable } from '../disposable/disposable.js';
-import { disposeAsync } from '../disposable/disposable.js';
 import type { Resolvable, resolveArgumentType } from '../injector/interfaces.js';
 import { BrowserContextController } from './browser-context-controller.js';
 import type { BrowserControllerOptions, NewBrowserContextOptions } from './browser-controller.js';
@@ -26,7 +24,7 @@ export declare class BrowserService implements AsyncDisposable, Resolvable<Brows
     private readonly persistentBrowserContexts;
     readonly options: BrowserServiceOptions | undefined;
     readonly [resolveArgumentType]: BrowserServiceArgument;
-    [disposeAsync](): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * @deprecated internal use only
      */

package/browser/browser.service.js

@@ -4,7 +4,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { disposeAsync } from '../disposable/disposable.js';
 import { Singleton } from '../injector/decorators.js';
 import { injectArgument } from '../injector/inject.js';
 import { filterUndefinedFromRecord } from '../utils/object/object.js';
@@ -20,7 +19,7 @@ let BrowserService = class BrowserService {
     browsers = new Set();
     persistentBrowserContexts = new Set();
     options = injectArgument(this, { optional: true });
-    async [disposeAsync]() {
+    async [Symbol.asyncDispose]() {
         await this.dispose();
     }
     /**

package/browser/page-controller.d.ts

@@ -1,6 +1,4 @@
 import type { Page } from 'playwright';
-import type { AsyncDisposable } from '../disposable/disposable.js';
-import { disposeAsync } from '../disposable/disposable.js';
 import type { Logger } from '../logger/logger.js';
 import type { BrowserContextController } from './browser-context-controller.js';
 import type { DocumentControllerOptions } from './document-controller.js';
@@ -15,11 +13,11 @@ export type ScrollToCoordinates = {
     y?: number;
 };
 export declare class PageController extends DocumentController<Page> implements AsyncDisposable {
-    /** @deprecated should be avoided */
+    /** @deprecated direct usage of underlying page object should be avoided */
     readonly page: Page;
     readonly options: PageControllerOptions;
     constructor(page: Page, context: BrowserContextController, options?: PageControllerOptions);
-    [disposeAsync](): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     close(): Promise<void>;
     /** finds pages opened by this page (having opener set to this page) */
     opened(): Promise<PageController[]>;

package/browser/page-controller.js

@@ -1,4 +1,3 @@
-import { disposeAsync } from '../disposable/disposable.js';
 import { filterUndefinedFromRecord } from '../utils/object/object.js';
 import { readableStreamFromPromise } from '../utils/stream/from-promise.js';
 import { toReadableStream } from '../utils/stream/to-readable-stream.js';
@@ -9,7 +8,7 @@ import { DocumentController } from './document-controller.js';
 import { ElementController } from './element-controller.js';
 import { attachLogger, delay } from './utils.js';
 export class PageController extends DocumentController {
-    /** @deprecated should be avoided */
+    /** @deprecated direct usage of underlying page object should be avoided */
     page;
     options;
     constructor(page, context, options = {}) {
@@ -17,7 +16,7 @@ export class PageController extends DocumentController {
         this.page = page;
         this.options = options;
     }
-    async [disposeAsync]() {
+    async [Symbol.asyncDispose]() {
         await this.close();
     }
     async close() {
@@ -45,7 +44,7 @@ export class PageController extends DocumentController {
         await this.page.setExtraHTTPHeaders(filtered);
     }
     async waitForClose() {
-        return new Promise((resolve) => {
+        await new Promise((resolve) => {
             if (this.page.isClosed()) {
                 resolve();
                 return;
@@ -69,7 +68,7 @@ export class PageController extends DocumentController {
     }
     async renderPdf(options = {}) {
         const createPdfOptions = convertPdfOptions(options);
-        return withTimeout(options.timeout ?? 30 * millisecondsPerSecond, this.page.pdf(createPdfOptions), { errorMessage: 'Rendering pdf timed out.' });
+        return await withTimeout(options.timeout ?? 30 * millisecondsPerSecond, this.page.pdf(createPdfOptions), { errorMessage: 'Rendering pdf timed out.' });
     }
     async scroll(deltaX, deltaY) {
         await this.page.mouse.wheel(deltaX, deltaY);
@@ -87,7 +86,7 @@ export class PageController extends DocumentController {
         const offsetY = viewportSize.height / 10;
         const isElement = coordinatesOrController instanceof ElementController;
         while (true) {
-            const { scrollWidth, scrollHeight, scrollLeft, scrollTop, clientWidth, clientHeight } = await this.page.evaluate(async () => {
+            const { scrollWidth, scrollHeight, scrollLeft, scrollTop, clientWidth, clientHeight } = await this.page.evaluate(() => {
                 const { scrollWidth, scrollHeight, scrollLeft, scrollTop, clientWidth, clientHeight } = document.documentElement;
                 return { scrollWidth, scrollHeight, scrollLeft, scrollTop, clientWidth, clientHeight };
             });
@@ -139,7 +138,7 @@ function convertPdfOptions(options) {
                 top: options.margin,
                 bottom: options.margin,
                 right: options.margin,
-                left: options.margin
+                left: options.margin,
             };
     return {
         format: options.format ?? 'a4',
@@ -151,6 +150,6 @@ function convertPdfOptions(options) {
         margin,
         displayHeaderFooter: options.displayHeaderFooter ?? (isDefined(options.headerTemplate) || isDefined(options.footerTemplate)),
         headerTemplate: options.headerTemplate,
-        footerTemplate: options.footerTemplate
+        footerTemplate: options.footerTemplate,
     };
 }

package/browser/utils.js

@@ -13,7 +13,7 @@ export function getLaunchOptions(options) {
         ignoreDefaultArgs: (options.headless == 'new') ? ['--headless'] : undefined,
         headless: headless != false,
         args,
-        proxy: options.proxy
+        proxy: options.proxy,
     };
 }
 export function mergeNewBrowserContextOptions(a, b, c) {
@@ -22,13 +22,13 @@ export function mergeNewBrowserContextOptions(a, b, c) {
         ...a,
         ...b,
         ...c,
-        extraHttpHeaders: (objectKeys(mergedExtraHttpHeaders).length > 0) ? mergedExtraHttpHeaders : undefined
+        extraHttpHeaders: (objectKeys(mergedExtraHttpHeaders).length > 0) ? mergedExtraHttpHeaders : undefined,
     };
 }
 function getPageLogger(page, baseLogger) {
     let pageLogger = pageLoggerMap.get(page);
     if (isUndefined(pageLogger)) {
-        pageLogger = baseLogger.subModule(crypto.randomUUID().slice(-12));
+        pageLogger = baseLogger.with({ pageSession: crypto.randomUUID().slice(-12) });
         pageLoggerMap.set(page, pageLogger);
     }
     return pageLogger;

package/cancellation/token.d.ts

@@ -1,138 +1,201 @@
 import { BehaviorSubject, type Observable, type Observer, type Subscribable, type Unsubscribable } from 'rxjs';
+/**
+ * Configuration for connecting a source to a CancellationToken.
+ */
 export type ConnectConfig = {
     /**
-     * Propagate parent set to child.
+     * Propagate 'set' (true) states to the child token.
      * @default true
      */
     set?: boolean;
     /**
-     * Propagate unset to child.
+     * Propagate 'unset' (false) states to the child token.
      * @default true
      */
     unset?: boolean;
     /**
-     * Propagate complete to child.
+     * Propagate the 'complete' event to the child token.
      * @default true
      */
     complete?: boolean;
     /**
-     * Propagate errors to child.
+     * Propagate errors to the child token.
      * @default true
      */
     error?: boolean;
     /**
-     * Update state immediately and don't wait for next state change.
+     * Immediately apply the source's current state upon connection.
+     * If false, waits for the next state change.
      * @default true
      */
     immediate?: boolean;
     /**
-     * Only update the state once (if immediate is also true it basically just sets the same value).
+     * Only propagate the first applicable state change, then disconnect.
      * @default false
      */
     once?: boolean;
 };
+/**
+ * A read-only view of a CancellationToken's state.
+ *
+ * It allows consumers to subscribe to state changes, await cancellation,
+ * or convert to other signal types (like AbortSignal) without being able
+ * to change the token's state.
+ *
+ * It is both `PromiseLike<void>` (resolves when set) and `Subscribable<void>`
+ * (emits when set).
+ */
 export declare class CancellationSignal implements PromiseLike<void>, Subscribable<void> {
-    #private;
+    protected readonly _stateSubject: BehaviorSubject<boolean>;
     /**
-     * Observable which emits the current state and every state change.
+     * Observable which emits the current state (true for set, false for unset)
+     * and any subsequent state changes.
      */
     readonly state$: Observable<boolean>;
     /**
-     * Observable which emits when this token is set.
+     * Observable which emits `void` only when the token becomes set.
      */
     readonly set$: Observable<void>;
     /**
-     * Observable which emits when this token is unset.
+     * Observable which emits `void` only when the token becomes unset.
      */
     readonly unset$: Observable<void>;
     /**
-     * Returns a promise which is resolved when this token changes its state.
+     * A promise that resolves with the next state of the token.
      */
     get $state(): Promise<boolean>;
     /**
-     * Returns a promise which is resolved when this token is set.
+     * A promise that resolves when the token is next set.
+     * If the token is already set, it resolves immediately.
      */
     get $set(): Promise<void>;
     /**
-     * Returns a promise which is resolved when this token is unset.
+     * A promise that resolves when the token is next unset.
+     * If the token is already unset, it resolves immediately.
      */
     get $unset(): Promise<void>;
+    /**
+     * The current state of the token.
+     * @returns `true` if set, `false` if unset.
+     */
     get state(): boolean;
     /**
-     * Whether this token is set.
+     * Whether the token is currently in a 'set' state.
      */
     get isSet(): boolean;
     /**
-     * Whether this token is unset.
+     * Whether the token is currently in an 'unset' state.
      */
     get isUnset(): boolean;
+    /**
+     * @internal
+     */
     constructor(stateSubject: BehaviorSubject<boolean>);
     /**
-     * Returns an AbortSignal.
+     * Returns a standard `AbortSignal` that is aborted when this token is set.
+     * Useful for interoperability with APIs like `fetch`.
      */
     asAbortSignal(): AbortSignal;
     /**
-     * Create a new token and connect it to this instance.
+     * Creates a new `CancellationToken` that is connected to this one.
+     * State changes from this token will propagate to the new child token.
      * @see {@link connect}
      */
     createChild(config?: ConnectConfig): CancellationToken;
     /**
-     * Propagate events from this instance to `target`. Events from the `target` are *not* propagated to this instance.
-     * @param target receiver to connect
+     * Propagates state changes from this token to a target `CancellationToken`.
+     * @param target The token to receive state updates.
+     * @param config Configuration for the connection.
      */
     connect(target: CancellationToken, config?: ConnectConfig): void;
+    /**
+     * Allows this object to be awaited. The promise resolves when the token is set.
+     * Implements the `PromiseLike<void>` interface.
+     */
     then<TResult>(onfulfilled?: ((value: void) => TResult | PromiseLike<TResult>) | null): Promise<TResult>;
+    /**
+     * Subscribes to notifications for when the token becomes set.
+     * This is an alias for `this.set$.subscribe(observer)`.
+     * Implements the `Subscribable<void>` interface.
+     */
     subscribe(observer: Partial<Observer<void>>): Unsubscribable;
 }
+/**
+ * A CancellationToken represents a unit of work that can be cancelled.
+ * It can be explicitly set/unset, completed, or errored.
+ *
+ * You can create child tokens, connect them to other async primitives
+ * (Promises, AbortSignals), and pass around its read-only `signal`
+ * to consumers that should only react to cancellation, not trigger it.
+ */
 export declare class CancellationToken extends CancellationSignal {
     #private;
-    /** Signal for this token */
+    /**
+     * A read-only view of this token.
+     * Useful for passing to functions that should only be able to check for
+     * cancellation but not trigger it.
+     */
     get signal(): CancellationSignal;
     /**
-     * @param initialState which state to initialze this token to
-     * - `false`: unset
-     * - `true`: set
-     * @default false
+     * @param initialState The initial state of the token. `false` (unset) by default.
      */
     constructor(initialState?: boolean);
     /**
-     * Creates a token and sets it whenever the source signals
-     * @param source source to listen to
-     * @param complete complete token after signal
+     * Creates a token that is set when the source signals.
+     * @param source The event source to listen to.
+     * @example
+     * // From a fetch promise
+     * const token = CancellationToken.from(fetch('/api/data'));
+     *
+     * // From a browser AbortSignal
+     * const controller = new AbortController();
+     * const token = CancellationToken.from(controller.signal);
      */
-    static from(source: AbortSignal | PromiseLike<any> | Observable<void>, options?: {
-        complete?: boolean;
-    }): CancellationToken;
+    static from(source: AbortSignal | PromiseLike<any> | Observable<void>, config?: ConnectConfig): CancellationToken;
     /**
-     * Creates a token and connects the source to its next, error and complete.
-     * @param observable observable to subscribe. Takes emitted value as state if type is boolean otherwise sets state to true.
+     * Creates a token and connects it to an `Observable<boolean>` source.
+     * The token's state will mirror the boolean values emitted by the observable.
+     * @param source The observable source.
+     * @param config Configuration for the connection.
      */
     static from(source: Observable<boolean>, config?: ConnectConfig): CancellationToken;
-    static connect(state$: Observable<boolean>, target: CancellationToken, config?: ConnectConfig): void;
     /**
-     * Become a child of the provided parent. Events from the parent are propagated to this token. Events from this token are *not* propagated to the parent.
+     * Connects an observable state source to a target token.
+     * @param source$ The observable providing boolean state.
+     * @param target The CancellationToken to update.
+     * @param config The connection configuration.
+     */
+    static connect(source$: Observable<boolean>, target: CancellationToken, config?: ConnectConfig): void;
+    /**
+     * Makes this token a child of a parent token.
+     * State changes from the parent will propagate to this token.
+     * @param parent The token to inherit state from.
+     * @param config Configuration for the connection.
      */
     inherit(parent: CancellationToken | CancellationSignal, config?: ConnectConfig): this;
     /**
-     * Set this token.
+     * Sets the token's state to `true`.
+     * This signals cancellation or completion of the associated operation.
      */
     set(): void;
     /**
-     * Unset this token.
+     * Sets the token's state to `false`.
+     * This can be used to reset the token.
      */
     unset(): void;
     /**
-     * Set the state.
+     * Explicitly sets the state of the token.
+     * @param state `true` for set, `false` for unset.
      */
     setState(state: boolean): void;
     /**
-     * Errors the token.
+     * Puts the token into an errored state.
+     * All current and future subscribers will receive this error.
      */
     error(error: Error): void;
     /**
-     * Clean up subscriptions.
-     *
-     * Keep in mind that *active* awaits (promise) on this token will throw.
+     * Completes the token's lifecycle.
+     * No further state changes can occur. Active awaits may throw an error.
      */
     complete(): void;
 }