@mnaoumov/typescript-lib 0.0.0 → 1.0.0

package/dist/lib/cjs/async-events.d.cts

@@ -0,0 +1,456 @@
+/// <reference path="./library.d.cts" />
+/**
+ * @file
+ *
+ * Async event emitter.
+ */
+import type { AbstractConstructor, Promisable } from 'type-fest' with { 'resolution-mode': 'import' };
+import type { AsyncDisposableEx } from './disposable.cjs';
+import type { GenericPromisableVoidFunction } from './function.cjs';
+import type { StringKeys } from './type.cjs';
+import { AsyncDisposableBase } from './disposable.cjs';
+declare const ASYNC_EVENT_MAP: unique symbol;
+/**
+ * Async event reference.
+ */
+export interface AsyncEventRef {
+    /**
+     * An event source.
+     */
+    asyncEventSource: GenericAsyncEventSource;
+    /**
+     * A callback to call when the event is triggered.
+     */
+    callback: GenericCallback;
+    /**
+     * A name of the event.
+     */
+    name: string;
+    /**
+     * A context passed as `this` to the `callback`.
+     */
+    thisArgument: unknown;
+}
+/**
+ * Async event emitter implementation.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * When omitted, the emitter accepts any string event name with any arguments.
+ * When provided, methods enforce correct event names and argument types
+ * with full autocomplete. Works with both `type` aliases and `interface` declarations.
+ *
+ * @example
+ * ```ts
+ * // Untyped (default) — any event name, any args:
+ * const events = new AsyncEvents();
+ * events.on('my-event', (arg1: string) => { ... });
+ *
+ * // Typed — only declared events with correct args:
+ * interface MyEventMap {
+ *   save: [data: string];
+ *   load: [id: number, force: boolean];
+ * }
+ * const events = new AsyncEvents<MyEventMap>();
+ * events.on('save', (data) => { ... });   // data: string — autocomplete on event name
+ * events.on('load', (id, force) => { ... }); // id: number, force: boolean
+ * ```
+ */
+export interface AsyncEventSource<EventMap extends EventMapConstraint<EventMap> = EventMapBase> extends GenericAsyncEventSource {
+    /**
+     * Phantom marker that makes {@link EventMap} inferable from an {@link AsyncEventSource} (e.g. via
+     * `Source extends AsyncEventSource<infer EventMap>`). Never present at runtime.
+     */
+    readonly [ASYNC_EVENT_MAP]?: EventMap;
+    /**
+     * Remove an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The arguments of the event.
+     * @param name - The name of the event.
+     * @param callback - The callback to remove.
+     *
+     * @example
+     * ```ts
+     * events.off('my-event', myListener);
+     * ```
+     */
+    off: <EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>) => void;
+    /**
+     * Add an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The arguments of the event.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.on('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    on: <EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown) => AsyncEventRef;
+    /**
+     * Add an event listener that will be triggered only once.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.once('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    once: <EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown) => AsyncEventRef;
+}
+/**
+ * Interface exposing event-triggering methods for subclasses of mixin-created classes.
+ *
+ * These methods are `protected` at runtime but surfaced in the declaration type
+ * because TypeScript cannot represent `protected` in anonymous-class return types.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ */
+export interface AsyncEventTrigger<EventMap extends EventMapConstraint<EventMap> = EventMapBase> {
+    /**
+     * Trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    trigger: <EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>) => void;
+    /**
+     * Trigger an event asynchronously.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    triggerAsync: <EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>) => Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    tryTrigger: <Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments) => void;
+    /**
+     * Try to trigger an event asynchronously.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    tryTriggerAsync: <Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments) => Promise<void>;
+}
+/**
+ * Resolves callback argument types for an event.
+ *
+ * - When `EventMap` has an index signature (untyped default): returns `unknown[]`,
+ *   allowing `Args` to be inferred freely from the callback.
+ * - When `EventMap` has explicit keys only (typed map): returns `EventMap[EventName]`,
+ *   enforcing the declared argument types and enabling autocomplete.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * @typeParam EventName - The name of the event.
+ */
+export type CallbackArguments<EventMap, EventName extends string> = string extends keyof EventMap ? unknown[] : (EventName extends keyof EventMap ? EventMap[EventName] : unknown[]);
+/**
+ * Base event map type for untyped emitters.
+ */
+export type EventMapBase = Record<string, unknown[]>;
+/**
+ * Interface for event source, used by {@link AsyncEventRef}
+ * so that refs can be stored regardless of the emitter's `EventMap`.
+ */
+export interface GenericAsyncEventSource {
+    /**
+     * Remove an event listener by reference.
+     *
+     * @param eventRef - The reference to remove.
+     */
+    offref: (eventRef: AsyncEventRef) => void;
+}
+/**
+ * Parameters for {@link subscribeAsyncDisposableEvent}.
+ *
+ * @typeParam Source - The {@link AsyncEventSource} type.
+ * @typeParam EventName - The event name, constrained to the source's known events.
+ */
+export interface SubscribeAsyncDisposableEventParams<Source extends GenericAsyncEventSource, EventName extends AsyncEventNameOf<Source>> {
+    /**
+     * The async event source to subscribe on.
+     */
+    readonly asyncEventSource: Source;
+    /**
+     * The event callback. Its argument types are inferred from {@link SubscribeAsyncDisposableEventParams.name}.
+     */
+    readonly callback: AsyncEventCallbackOf<Source, EventName>;
+    /**
+     * The event name to subscribe to.
+     */
+    readonly name: EventName;
+    /**
+     * The context passed as `this` to the callback.
+     */
+    readonly thisArgument?: unknown;
+}
+type AsyncEventCallbackOf<Source extends GenericAsyncEventSource, EventName extends AsyncEventNameOf<Source>> = EventMapOf<Source>[EventName] extends infer Arguments extends unknown[] ? (...$arguments: Arguments) => Promisable<void> : never;
+type AsyncEventNameOf<Source extends GenericAsyncEventSource> = keyof EventMapOf<Source> & string;
+type EventMapConstraint<T> = Record<keyof T, unknown[]>;
+type EventMapOf<Source> = Source extends AsyncEventSource<infer EventMap> ? EventMap : never;
+type GenericCallback = GenericPromisableVoidFunction<unknown[]>;
+/**
+ * An {@link AsyncDisposableEx} that unregisters an {@link AsyncEventRef} on dispose, via the event source stored
+ * on the ref itself. Async counterpart of the native `EventRefDisposable`.
+ */
+export declare class AsyncEventRefDisposable extends AsyncDisposableBase {
+    private readonly asyncEventRef;
+    /**
+     * Creates a disposable wrapping an existing {@link AsyncEventRef}.
+     *
+     * @param asyncEventRef - The async event reference to unregister on dispose.
+     */
+    constructor(asyncEventRef: AsyncEventRef);
+    /**
+     * Unregisters the event via the source stored on the ref (`asyncEventSource.offref`).
+     */
+    protected performDisposeAsync(): void;
+}
+/**
+ * Async event source implementation.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * When omitted, the emitter accepts any string event name with any arguments.
+ * When provided, methods enforce correct event names and argument types
+ * with full autocomplete. Works with both `type` aliases and `interface` declarations.
+ *
+ * @example
+ * ```ts
+ * // Untyped (default) — any event name, any args:
+ * const events = new AsyncEvents();
+ * events.on('my-event', (arg1: string) => { ... });
+ *
+ * // Typed — only declared events with correct args:
+ * interface MyEventMap {
+ *   save: [data: string];
+ *   load: [id: number, force: boolean];
+ * }
+ * const events = new AsyncEvents<MyEventMap>();
+ * events.on('save', (data) => { ... });   // data: string — autocomplete on event name
+ * events.on('load', (id, force) => { ... }); // id: number, force: boolean
+ * ```
+ */
+export declare abstract class AsyncEventsBase<EventMap extends EventMapConstraint<EventMap> = EventMapBase> implements AsyncEventSource<EventMap> {
+    /**
+     * The registry mapping each event name to its list of registered listener references.
+     */
+    protected readonly eventReferencesMap: Map<string, AsyncEventRef[]>;
+    /**
+     * Remove an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The types of the arguments the event callback accepts.
+     * @param name - The name of the event.
+     * @param callback - The callback to remove.
+     *
+     * @example
+     * ```ts
+     * events.off('my-event', myListener);
+     * ```
+     */
+    off<EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>): void;
+    /**
+     * Remove an event listener by reference.
+     *
+     * @param eventRef - The reference to the event listener.
+     *
+     * @example
+     * ```ts
+     * events.offref(myRef);
+     * ```
+     */
+    offref(eventRef: AsyncEventRef): void;
+    /**
+     * Add an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The types of the arguments the event callback accepts.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.on('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    on<EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown): AsyncEventRef;
+    /**
+     * Add an event listener that will be triggered only once.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The types of the arguments the event callback accepts.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.once('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    once<EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown): AsyncEventRef;
+    /**
+     * Trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     *
+     * @example
+     * ```ts
+     * events.trigger('my-event', 'arg1', 'arg2');
+     * ```
+     */
+    protected trigger<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): void;
+    /**
+     * Trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    protected triggerAsync<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     *
+     * @example
+     * ```ts
+     * events.tryTrigger(myRef, ['arg1', 'arg2']);
+     * ```
+     */
+    protected tryTrigger<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): void;
+    /**
+     * Try to trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    protected tryTriggerAsync<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): Promise<void>;
+}
+/**
+ * A class that extends {@link AsyncEventsBase} and provides public methods for triggering events.
+ *
+ * This class exists as parity with Obsidian's `Events`. But exposing publicly `trigger()` methods violates encapsulation.
+ *
+ * Avoid using it in favor of {@link AsyncEventsBase}.
+ *
+ * @typeParam EventMap - The type of the event map.
+ */
+export declare class AsyncEvents<EventMap extends EventMapConstraint<EventMap> = EventMapBase> extends AsyncEventsBase<EventMap> {
+    /**
+     * Trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    trigger<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): void;
+    /**
+     * Trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    triggerAsync<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    tryTrigger<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): void;
+    /**
+     * Try to trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    tryTriggerAsync<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): Promise<void>;
+}
+/**
+ * Mixin that adds {@link AsyncEventSource} delegation to a base class.
+ *
+ * All event methods delegate to a private {@link AsyncEventsBase} instance.
+ * The `EventMap` generic is fixed at mixin-application time — if you need a class
+ * that is itself generic over its event map, use composition instead.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * @returns A function that takes a base class and returns a new class extending it with {@link AsyncEventSource}.
+ *
+ * @example
+ * ```ts
+ * interface MyEvents {
+ *   save: [data: string];
+ * }
+ * class MyComponent extends mixinAsyncEvents<MyEvents>()(Component) {
+ *   // on(), off(), once(), offref() are available
+ * }
+ * ```
+ */
+export declare function mixinAsyncEvents<EventMap extends EventMapConstraint<EventMap> = EventMapBase>(): <TBase extends AbstractConstructor<object>>(baseClass: TBase) => AbstractConstructor<AsyncEventSource<EventMap> & AsyncEventTrigger<EventMap>> & TBase;
+/**
+ * Subscribes to an event on an {@link AsyncEventSource} and returns an {@link AsyncDisposableEx} that unregisters
+ * it on dispose. Async counterpart of the native `subscribeDisposableEvent`; the event name and callback argument
+ * types are inferred from the source's event map.
+ *
+ * @typeParam Source - The {@link AsyncEventSource} type.
+ * @typeParam EventName - The event name.
+ * @param params - The subscription parameters.
+ * @returns An {@link AsyncDisposableEx} that unregisters the handler when disposed.
+ */
+export declare function subscribeAsyncDisposableEvent<Source extends GenericAsyncEventSource, EventName extends AsyncEventNameOf<Source>>(params: SubscribeAsyncDisposableEventParams<Source, EventName>): AsyncDisposableEx;
+export {};

package/dist/lib/cjs/async-operation-hook.cjs

@@ -0,0 +1,113 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function () {
+function ensureDisposeSymbols(symbolConstructor = Symbol) {
+  symbolConstructor.asyncDispose ??= symbolConstructor.for('Symbol.asyncDispose');
+  symbolConstructor.dispose ??= symbolConstructor.for('Symbol.dispose');
+}
+
+function ensureBrowserProcess() {
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+
+  // eslint-disable-next-line obsidianmd/no-global-this, unicorn/no-unnecessary-global-this -- Must stay `globalThis`-qualified: in the emitted banner a bare `process` is a free identifier, so reading it where the host has none throws a ReferenceError instead of yielding `undefined`. That is the very case this function exists to handle.
+  const existingProcess = globalThis.process;
+
+  if (!existingProcess) {
+    // eslint-disable-next-line obsidianmd/no-global-this -- Actively use globalThis.
+    globalThis.process = browserProcess;
+    return;
+  }
+
+  if (existingProcess.versions?.node) {
+    return;
+  }
+
+  const existingProcessRecord = existingProcess;
+
+  for (const [key, value] of Object.entries(browserProcess)) {
+    existingProcessRecord[key] ??= value;
+  }
+
+  existingProcessRecord['browser'] = true;
+}
+
+function keepName($unknown) {
+  return $unknown;
+}
+
+(function initCjs() {
+  // eslint-disable-next-line obsidianmd/no-global-this -- Actively use globalThis.
+  const globalThisRecord = globalThis;
+  ensureDisposeSymbols();
+  globalThisRecord['__name'] ??= keepName;
+  globalThisRecord['__extractDefault'] ??= extractDefault;
+
+  ensureBrowserProcess();
+
+  // eslint-disable-next-line unicorn/consistent-function-scoping -- Serialized with initCjs into the banner; at module scope it would be left out of it.
+  function extractDefault(module) {
+    return module && module.__esModule && 'default' in module ? module.default : module;
+  }
+})();
+})();
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var async_operation_hook_exports = {};
+__export(async_operation_hook_exports, {
+  ASYNC_OPERATION_HOOK_KEY: () => ASYNC_OPERATION_HOOK_KEY,
+  ASYNC_OPERATION_HOOK_VERSION: () => ASYNC_OPERATION_HOOK_VERSION,
+  getAsyncOperationHook: () => getAsyncOperationHook,
+  notifyAsyncOperationStarted: () => notifyAsyncOperationStarted,
+  setAsyncOperationHook: () => setAsyncOperationHook
+});
+module.exports = __toCommonJS(async_operation_hook_exports);
+const ASYNC_OPERATION_HOOK_VERSION = 1;
+const ASYNC_OPERATION_HOOK_KEY = /* @__PURE__ */ Symbol.for("@mnaoumov/typescript-lib/async-operation-hook");
+function getAsyncOperationHook() {
+  return getSlot()[ASYNC_OPERATION_HOOK_KEY] ?? null;
+}
+function notifyAsyncOperationStarted(operation) {
+  getAsyncOperationHook()?.onAsyncOperationStarted(operation);
+}
+function setAsyncOperationHook(hook) {
+  getSlot()[ASYNC_OPERATION_HOOK_KEY] = hook;
+}
+function getSlot() {
+  return globalThis;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ASYNC_OPERATION_HOOK_KEY,
+  ASYNC_OPERATION_HOOK_VERSION,
+  getAsyncOperationHook,
+  notifyAsyncOperationStarted,
+  setAsyncOperationHook
+});
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2FzeW5jLW9wZXJhdGlvbi1ob29rLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogQW4gb3B0aW9uYWwgb2JzZXJ2ZXIgdGhhdCBmaXJlLWFuZC1mb3JnZXQgb3BlcmF0aW9ucyByZXBvcnQgdG8gd2hlbiB0aGV5IHN0YXJ0LlxuICpcbiAqIFByb2R1Y3Rpb24gY29kZSBvbmx5IGV2ZXIgQ0FMTFMgdGhlIGhvb2s6IHtAbGluayBub3RpZnlBc3luY09wZXJhdGlvblN0YXJ0ZWR9IGlzIGEgbm8tb3AgdW50aWwgc29tZXRoaW5nXG4gKiBpbnN0YWxscyBvbmUsIHNvIG5vIGJvb2trZWVwaW5nIGlzIGtlcHQgd2hlbiBub3RoaW5nIGlzIGxpc3RlbmluZy4gVGhlIHRlc3Qgc3VwcG9ydFxuICogKGBhc3luYy1vcGVyYXRpb24tdHJhY2tpbmcudHNgKSBpcyB3aGF0IGluc3RhbGxzIGl0LCBhbmQgaXQgb3ducyB0aGUgcmVnaXN0cnkgb2YgcGVuZGluZyBvcGVyYXRpb25zLlxuICpcbiAqIFRoZSBzbG90IGxpdmVzIG9uIGBnbG9iYWxUaGlzYCB1bmRlciBhIGBTeW1ib2wuZm9yYCBrZXkgcmF0aGVyIHRoYW4gaW4gYSBtb2R1bGUtbGV2ZWwgdmFyaWFibGUuIFR3b1xuICogaW5zdGFsbGVkIGNvcGllcyBvZiB0aGlzIG1vZHVsZSBcdTIwMTQgdGhlIGNvZGUgdW5kZXIgdGVzdCBidW5kbGluZyBvbmUgdmVyc2lvbiwgdGhlIHRlc3Qgc3VwcG9ydCBkZXBlbmRpbmcgb25cbiAqIGFub3RoZXIgXHUyMDE0IHRoZW4gc3RpbGwgc2hhcmUgb25lIHNsb3QsIHNvIHRoZSBob29rIHRoZSB0ZXN0cyBpbnN0YWxsIGlzIHRoZSBob29rIHRoZSBjb2RlIHVuZGVyIHRlc3QgY2FsbHMuXG4gKiBBIG1vZHVsZS1sZXZlbCB2YXJpYWJsZSB3b3VsZCBsZXQgZWFjaCBjb3B5IGtlZXAgaXRzIG93biwgYW5kIHRyYWNraW5nIHdvdWxkIHNpbGVudGx5IHNlZSBub3RoaW5nLlxuICpcbiAqIFRoZSBzbG90IGlzIGEgY3Jvc3MtdmVyc2lvbiB3aXJlIGZvcm1hdDogaXRzIGtleSBhbmQgdGhlIG1lbWJlcnMgb2Yge0BsaW5rIEFzeW5jT3BlcmF0aW9uSG9va30gb25seSBldmVyXG4gKiBjaGFuZ2UgYWRkaXRpdmVseS5cbiAqL1xuXG4vKipcbiAqIFRoZSB2ZXJzaW9uIG9mIHRoZSB7QGxpbmsgQXN5bmNPcGVyYXRpb25Ib29rfSBzaGFwZSB0aGlzIGNvcHkgd3JpdGVzLlxuICovXG5leHBvcnQgY29uc3QgQVNZTkNfT1BFUkFUSU9OX0hPT0tfVkVSU0lPTiA9IDE7XG5cbi8qKlxuICogVGhlIGtleSBvZiB0aGUgZ2xvYmFsIHNsb3QgaG9sZGluZyB0aGUgaW5zdGFsbGVkIHtAbGluayBBc3luY09wZXJhdGlvbkhvb2t9LlxuICovXG5leHBvcnQgY29uc3QgQVNZTkNfT1BFUkFUSU9OX0hPT0tfS0VZOiB1bmlxdWUgc3ltYm9sID0gU3ltYm9sLmZvcignQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL2FzeW5jLW9wZXJhdGlvbi1ob29rJyk7XG5cbi8qKlxuICogQW4gb2JzZXJ2ZXIgbm90aWZpZWQgd2hlbmV2ZXIgYSBmaXJlLWFuZC1mb3JnZXQgb3BlcmF0aW9uIHN0YXJ0cy5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBBc3luY09wZXJhdGlvbkhvb2sge1xuICAvKipcbiAgICogQ2FsbGVkIHdpdGggZWFjaCBmaXJlLWFuZC1mb3JnZXQgb3BlcmF0aW9uIGFzIGl0IHN0YXJ0cy5cbiAgICpcbiAgICogQHBhcmFtIG9wZXJhdGlvbiAtIFRoZSBvcGVyYXRpb24uIEl0IG5ldmVyIHJlamVjdHM6IGVycm9ycyBhcmUgYWxyZWFkeSBoYW5kbGVkIGJlZm9yZSBpdCBpcyByZXBvcnRlZC5cbiAgICovXG4gIHJlYWRvbmx5IG9uQXN5bmNPcGVyYXRpb25TdGFydGVkOiAob3BlcmF0aW9uOiBQcm9taXNlPHZvaWQ+KSA9PiB2b2lkO1xuXG4gIC8qKlxuICAgKiBUaGUgdmVyc2lvbiBvZiB0aGUgaG9vayBzaGFwZSB0aGUgaW5zdGFsbGVyIHdyb3RlLiBJbmZvcm1hdGlvbmFsOiB0aGUgbWVtYmVycyBvbmx5IGNoYW5nZSBhZGRpdGl2ZWx5LlxuICAgKi9cbiAgcmVhZG9ubHkgdmVyc2lvbjogbnVtYmVyO1xufVxuXG50eXBlIEFzeW5jT3BlcmF0aW9uSG9va1Nsb3QgPSBQYXJ0aWFsPFJlY29yZDx0eXBlb2YgQVNZTkNfT1BFUkFUSU9OX0hPT0tfS0VZLCBBc3luY09wZXJhdGlvbkhvb2sgfCBudWxsPj47XG5cbi8qKlxuICogR2V0cyB0aGUgaW5zdGFsbGVkIHtAbGluayBBc3luY09wZXJhdGlvbkhvb2t9LlxuICpcbiAqIEByZXR1cm5zIFRoZSBpbnN0YWxsZWQgaG9vaywgb3IgYG51bGxgIHdoZW4gbm9uZSBpcyBpbnN0YWxsZWQuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBnZXRBc3luY09wZXJhdGlvbkhvb2soKTogQXN5bmNPcGVyYXRpb25Ib29rIHwgbnVsbCB7XG4gIHJldHVybiBnZXRTbG90KClbQVNZTkNfT1BFUkFUSU9OX0hPT0tfS0VZXSA/PyBudWxsO1xufVxuXG4vKipcbiAqIFJlcG9ydHMgYSBmaXJlLWFuZC1mb3JnZXQgb3BlcmF0aW9uIHRvIHRoZSBpbnN0YWxsZWQge0BsaW5rIEFzeW5jT3BlcmF0aW9uSG9va30sIGlmIGFueS5cbiAqXG4gKiBAcGFyYW0gb3BlcmF0aW9uIC0gVGhlIG9wZXJhdGlvbiB0aGF0IGhhcyBqdXN0IHN0YXJ0ZWQuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBub3RpZnlBc3luY09wZXJhdGlvblN0YXJ0ZWQob3BlcmF0aW9uOiBQcm9taXNlPHZvaWQ+KTogdm9pZCB7XG4gIGdldEFzeW5jT3BlcmF0aW9uSG9vaygpPy5vbkFzeW5jT3BlcmF0aW9uU3RhcnRlZChvcGVyYXRpb24pO1xufVxuXG4vKipcbiAqIEluc3RhbGxzIGFuIHtAbGluayBBc3luY09wZXJhdGlvbkhvb2t9LCByZXBsYWNpbmcgYW55IGluc3RhbGxlZCBvbmUsIG9yIHJlbW92ZXMgaXQuXG4gKlxuICogQHBhcmFtIGhvb2sgLSBUaGUgaG9vayB0byBpbnN0YWxsLCBvciBgbnVsbGAgdG8gcmVtb3ZlIHRoZSBpbnN0YWxsZWQgb25lLlxuICovXG5leHBvcnQgZnVuY3Rpb24gc2V0QXN5bmNPcGVyYXRpb25Ib29rKGhvb2s6IEFzeW5jT3BlcmF0aW9uSG9vayB8IG51bGwpOiB2b2lkIHtcbiAgZ2V0U2xvdCgpW0FTWU5DX09QRVJBVElPTl9IT09LX0tFWV0gPSBob29rO1xufVxuXG5mdW5jdGlvbiBnZXRTbG90KCk6IEFzeW5jT3BlcmF0aW9uSG9va1Nsb3Qge1xuICAvLyBlc2xpbnQtZGlzYWJsZS1uZXh0LWxpbmUgb2JzaWRpYW5tZC9uby1nbG9iYWwtdGhpcyAtLSBUaGUgaG9vayBzbG90IGludGVudGlvbmFsbHkgbGl2ZXMgb24gdGhlIHJlYWxtIGdsb2JhbCwgc2hhcmVkIGJ5IGV2ZXJ5IGNvcHkgb2YgdGhpcyBtb2R1bGUuXG4gIHJldHVybiBnbG9iYWxUaGlzIGFzIEFzeW5jT3BlcmF0aW9uSG9va1Nsb3Q7XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFxQk8sTUFBTSwrQkFBK0I7QUFLckMsTUFBTSwyQkFBMEMsdUJBQU8sSUFBSSwrQ0FBK0M7QUEwQjFHLFNBQVMsd0JBQW1EO0FBQ2pFLFNBQU8sUUFBUSxFQUFFLHdCQUF3QixLQUFLO0FBQ2hEO0FBT08sU0FBUyw0QkFBNEIsV0FBZ0M7QUFDMUUsd0JBQXNCLEdBQUcsd0JBQXdCLFNBQVM7QUFDNUQ7QUFPTyxTQUFTLHNCQUFzQixNQUF1QztBQUMzRSxVQUFRLEVBQUUsd0JBQXdCLElBQUk7QUFDeEM7QUFFQSxTQUFTLFVBQWtDO0FBRXpDLFNBQU87QUFDVDsiLAogICJuYW1lcyI6IFtdCn0K

package/dist/lib/cjs/async-operation-hook.d.cts

@@ -0,0 +1,59 @@
+/// <reference path="./library.d.cts" />
+/**
+ * @file
+ *
+ * An optional observer that fire-and-forget operations report to when they start.
+ *
+ * Production code only ever CALLS the hook: {@link notifyAsyncOperationStarted} is a no-op until something
+ * installs one, so no bookkeeping is kept when nothing is listening. The test support
+ * (`async-operation-tracking.ts`) is what installs it, and it owns the registry of pending operations.
+ *
+ * The slot lives on `globalThis` under a `Symbol.for` key rather than in a module-level variable. Two
+ * installed copies of this module — the code under test bundling one version, the test support depending on
+ * another — then still share one slot, so the hook the tests install is the hook the code under test calls.
+ * A module-level variable would let each copy keep its own, and tracking would silently see nothing.
+ *
+ * The slot is a cross-version wire format: its key and the members of {@link AsyncOperationHook} only ever
+ * change additively.
+ */
+/**
+ * The version of the {@link AsyncOperationHook} shape this copy writes.
+ */
+export declare const ASYNC_OPERATION_HOOK_VERSION = 1;
+/**
+ * The key of the global slot holding the installed {@link AsyncOperationHook}.
+ */
+export declare const ASYNC_OPERATION_HOOK_KEY: unique symbol;
+/**
+ * An observer notified whenever a fire-and-forget operation starts.
+ */
+export interface AsyncOperationHook {
+    /**
+     * Called with each fire-and-forget operation as it starts.
+     *
+     * @param operation - The operation. It never rejects: errors are already handled before it is reported.
+     */
+    readonly onAsyncOperationStarted: (operation: Promise<void>) => void;
+    /**
+     * The version of the hook shape the installer wrote. Informational: the members only change additively.
+     */
+    readonly version: number;
+}
+/**
+ * Gets the installed {@link AsyncOperationHook}.
+ *
+ * @returns The installed hook, or `null` when none is installed.
+ */
+export declare function getAsyncOperationHook(): AsyncOperationHook | null;
+/**
+ * Reports a fire-and-forget operation to the installed {@link AsyncOperationHook}, if any.
+ *
+ * @param operation - The operation that has just started.
+ */
+export declare function notifyAsyncOperationStarted(operation: Promise<void>): void;
+/**
+ * Installs an {@link AsyncOperationHook}, replacing any installed one, or removes it.
+ *
+ * @param hook - The hook to install, or `null` to remove the installed one.
+ */
+export declare function setAsyncOperationHook(hook: AsyncOperationHook | null): void;