@amazon/vinyl-util 1.0.0

package/dist/types/ts4.7/network/RequesterImplEventMap.d.ts

@@ -0,0 +1,230 @@
+import type { Timestamp } from '../util/date/date';
+import type { ErrorBodyType } from '../network/Requester';
+/**
+ * Events {@link RequesterImpl} emits.
+ */
+export interface RequesterImplEventMap {
+    /**
+     * A request has been requested.
+     * This is emitted immediately when {@link Requester.request} is called.
+     */
+    readonly request: RequestEvent;
+    /**
+     * A request attempt has begun. For implementations with retry behavior, this is expected to be
+     * emitted for each try.
+     */
+    readonly requestAttemptStart: RequestAttemptStartEvent;
+    /**
+     * A request attempt has completed.
+     */
+    readonly requestAttemptComplete: RequestCompletedEvent;
+    /**
+     * The request promise is about to settle.
+     */
+    readonly requestComplete: RequestCompletedEvent;
+}
+export interface RequestEvent {
+    /**
+     * Information about the request.
+     */
+    readonly requestInfo: FetchRequestInfo;
+}
+export interface RequestAttemptStartEvent {
+    /**
+     * Information about the request.
+     */
+    readonly requestInfo: FetchRequestInfo;
+    /**
+     * Information about the current attempt.
+     */
+    readonly attemptInfo: RequestAttemptInfo;
+}
+/**
+ * When a request has been made, information about the request is gathered for logging.
+ */
+export interface FetchRequestInfo {
+    /**
+     * The identifier for the request. The request id for the `requesting` event will match its
+     * corresponding `requestComplete` event.
+     */
+    readonly requestId: string;
+    /**
+     * The input parameter passed to `request`.
+     */
+    readonly input: RequestInfo | URL;
+    /**
+     * The init parameter passed to `request`.
+     */
+    readonly init: RequestInit;
+    /**
+     * The maximum number of retries.
+     */
+    readonly maxRetries: number;
+    /**
+     * Options the request is using.
+     */
+    readonly requestOptions: {
+        /**
+         * The resolved service id.
+         */
+        readonly serviceId: string | null;
+        /**
+         * Determines how error responses are read and reported.
+         */
+        readonly readErrorBody: ErrorBodyType;
+    };
+    /**
+     * The timestamp the request was originally requested.
+     */
+    readonly timestamp: Timestamp;
+}
+/**
+ * Information about the current try.
+ */
+export interface RequestAttemptInfo {
+    /**
+     * The current try (1 = first).
+     */
+    readonly currentTry: number;
+    /**
+     * The timestamp the actual request attempt began. This will be after awaiting network
+     * availability.
+     */
+    readonly timestamp: Timestamp;
+}
+/**
+ * Information about a request completion, either from a successful response or a failure.
+ */
+export type RequestCompletedEvent = RequestSuccessEvent | RequestErrorEvent;
+export interface RequestCompletedEventBase {
+    /**
+     * True if the request was successful.
+     */
+    readonly ok: boolean;
+    /**
+     * The local timestamp of the request result or error.
+     */
+    readonly timestamp: Timestamp;
+    /**
+     * Information about the request.
+     */
+    readonly requestInfo: FetchRequestInfo;
+}
+export interface RequestSuccessEvent extends RequestCompletedEventBase {
+    /**
+     * The response was successful.
+     */
+    readonly ok: true;
+    /**
+     * The serializable and loggable response.
+     */
+    readonly responseInfo: ResponseInfo;
+    /**
+     * Information about the current attempt.
+     */
+    readonly attemptInfo: RequestAttemptInfo;
+}
+export declare enum RequestFailureType {
+    /**
+     * The request has been aborted.
+     */
+    ABORT = "abort",
+    /**
+     * The request failed due to a caught internal error.
+     */
+    INTERNAL = "internal",
+    /**
+     * The request failed with a caught error.
+     */
+    NETWORK = "network",
+    /**
+     * An `!ok` response was received.
+     */
+    RESPONSE = "response"
+}
+export type RequestErrorEvent = RequestCaughtErrorEvent | RequestNetworkErrorEvent | RequestResponseErrorEvent;
+export interface RequestErrorEventBase extends RequestCompletedEventBase {
+    /**
+     * The request failed.
+     */
+    readonly ok: false;
+    /**
+     * The failure type.
+     */
+    readonly type: RequestFailureType;
+    /**
+     * If false, the request will not be retried, even if there are more tries remaining.
+     *
+     * This will be false if the error is an internal error, retries have been exhausted or the
+     * response did not pass the `shouldRetry` filter.
+     */
+    readonly willRetry: boolean;
+    /**
+     * The timestamp of the next try.
+     * If `willRetry` is true, the request will try again at this timestamp.
+     */
+    readonly retryAfter: Timestamp | null;
+    /**
+     * The caught or rejected reason.
+     */
+    readonly reason: any;
+}
+export interface RequestCaughtErrorEvent extends RequestErrorEventBase {
+    readonly type: RequestFailureType.INTERNAL | RequestFailureType.ABORT;
+    /**
+     * Caught errors will not be retried.
+     */
+    readonly willRetry: false;
+}
+export interface RequestNetworkErrorEvent extends RequestErrorEventBase {
+    readonly type: RequestFailureType.NETWORK;
+    /**
+     * Information about the current attempt.
+     */
+    readonly attemptInfo: RequestAttemptInfo;
+}
+export interface RequestResponseErrorEvent extends RequestErrorEventBase {
+    readonly type: RequestFailureType.RESPONSE;
+    /**
+     * The serializable and loggable response.
+     */
+    readonly responseInfo: ResponseInfo;
+    /**
+     * Information about the current attempt.
+     */
+    readonly attemptInfo: RequestAttemptInfo;
+}
+/**
+ * Serializable response metadata, excluding the body.
+ */
+export interface ResponseInfo {
+    /**
+     * True if status is in the 200–299 range.
+     */
+    readonly ok: boolean;
+    /**
+     * True if the response resulted from a redirect.
+     */
+    readonly redirected: boolean;
+    /**
+     * HTTP status code (e.g. 200).
+     */
+    readonly status: number;
+    /**
+     * HTTP status text (e.g. "OK").
+     */
+    readonly statusText: string;
+    /**
+     * Type of response (e.g. "basic", "cors").
+     */
+    readonly type: ResponseType;
+    /**
+     * Final resolved URL of the response.
+     */
+    readonly url: string;
+    /**
+     * Size of the response body in bytes, or null if unknown.
+     */
+    readonly contentLength: number | null;
+}
+//# sourceMappingURL=RequesterImplEventMap.d.ts.map

package/dist/types/ts4.7/network/browser/NetworkInformation.d.ts

@@ -0,0 +1,48 @@
+export interface NetworkInformationEventMap {
+    readonly change: Event;
+}
+export type NetworkInformationEffectiveType = 'slow-2g' | '2g' | '3g' | '4g';
+export type NetworkInformationType = 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
+/**
+ * Provides information about the system’s current network connection,
+ * such as estimated bandwidth, round-trip time, and connection type.
+ * Also exposes events for monitoring changes to the network state.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation
+ */
+export interface NetworkInformation extends EventTarget {
+    /**
+     * Approximate downlink speed in megabits per second.
+     * Rounded to the nearest 25 kbps, based on recent throughput
+     * over active connections. May be undefined if no estimate is available.
+     */
+    readonly downlink: number | undefined;
+    /**
+     * A string describing the general quality of the connection
+     * (for example, "4g", "3g"). Determined from both downlink
+     * and latency estimates.
+     */
+    readonly effectiveType: NetworkInformationEffectiveType;
+    /**
+     * Estimated round-trip latency of the current connection in milliseconds,
+     * rounded to the nearest multiple of 25 ms.
+     */
+    readonly rtt: number;
+    /**
+     * Indicates whether the user has requested reduced data usage
+     * in the user agent’s settings.
+     */
+    readonly saveData: boolean;
+    /**
+     * Type of underlying network connection in use
+     * (for example, "wifi", "cellular"). May be omitted if unknown.
+     */
+    readonly type?: NetworkInformationType;
+    addEventListener<K extends keyof NetworkInformationEventMap>(type: K, listener: (this: NetworkInformation, ev: NetworkInformationEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof NetworkInformationEventMap>(type: K, listener: (this: NetworkInformation, ev: NetworkInformationEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+}
+/**
+ * Returns the browser's NetworkInformation interface, if it's defined.
+ */
+export declare function getNetworkInformation(): NetworkInformation | undefined;
+//# sourceMappingURL=NetworkInformation.d.ts.map

package/dist/types/ts4.7/network/createRequester.d.ts

@@ -0,0 +1,12 @@
+import type { Requester } from './Requester';
+import type { RequesterImplDeps, RequesterImplOptions } from './RequesterImpl';
+import type { Maybe, PartialDeep } from '../util/type';
+/**
+ * Creates a default Requester implementation with optional configuration or dependency overrides.
+ * The new Requester is watched for global logging and network metrics.
+ *
+ * @param options
+ * @param deps
+ */
+export declare function createRequester(options?: Maybe<PartialDeep<RequesterImplOptions>>, deps?: Partial<RequesterImplDeps>): Requester;
+//# sourceMappingURL=createRequester.d.ts.map

package/dist/types/ts4.7/network/logging/networkLoggingHandler.d.ts

@@ -0,0 +1,14 @@
+import type { Disposable } from '../../core/disposable';
+import type { ReadonlyEventHost } from '../../event/EventHost';
+import type { RequesterImplEventMap } from '../../network/RequesterImplEventMap';
+import { type LogTarget } from '../../logging/LogTarget';
+/**
+ * Logs all network events.
+ *
+ * @param requester The event host with request events to observe.
+ * @return Returns a disposable handle to remove all added handlers.
+ */
+export declare function networkLoggingHandler(requester: ReadonlyEventHost<RequesterImplEventMap>): Disposable & {
+    readonly target: LogTarget;
+};
+//# sourceMappingURL=networkLoggingHandler.d.ts.map

package/dist/types/ts4.7/network/metrics/NetworkMetricsController.d.ts

@@ -0,0 +1,41 @@
+import type { ReadonlyEventHost } from '../../event/EventHost';
+import type { AnyRecord, Maybe } from '../../util/type';
+import type { NetworkMetrics, NetworkMetricsEntry, NetworkTransferEntry, ServiceMetrics } from './networkMetricsModel';
+export interface NetworkMetricsEventMap {
+    /**
+     * The network metrics state has changed.
+     */
+    readonly metricsChange: AnyRecord;
+}
+export interface ReadonlyNetworkMetricsController extends ReadonlyEventHost<NetworkMetricsEventMap> {
+    /**
+     * The current metrics state.
+     * The returned object is static at the time of request.
+     */
+    readonly metrics: NetworkMetrics;
+    /**
+     * Returns metrics for the given service id.
+     * If the service id is nullish, or there is no history for the given service, empty service
+     * metrics will be returned.
+     *
+     * The returned object is static at the time of request.
+     *
+     * @param serviceId
+     */
+    getServiceMetrics(serviceId: Maybe<string>): ServiceMetrics;
+}
+export interface NetworkMetricsController extends ReadonlyNetworkMetricsController {
+    /**
+     * Adds information about a completed settled request.
+     * Note: This does not update estimated bandwidth.
+     * @param entry
+     */
+    addMetricsEntry(entry: NetworkMetricsEntry): void;
+    /**
+     * Adds information about a completed downlink content transfer.
+     *
+     * @param entry
+     */
+    addDownlinkTransferEntry(entry: NetworkTransferEntry): void;
+}
+//# sourceMappingURL=NetworkMetricsController.d.ts.map

package/dist/types/ts4.7/network/metrics/NetworkMetricsControllerImpl.d.ts

@@ -0,0 +1,119 @@
+import { EventHostImpl } from '../../event/EventHost';
+import type { NetworkInformation } from '../../network/browser/NetworkInformation';
+import type { NetworkMetricsController, NetworkMetricsEventMap } from './NetworkMetricsController';
+import type { NetworkMetrics, NetworkMetricsEntry, NetworkTransferEntry, ServiceMetrics } from './networkMetricsModel';
+import type { ReadonlyDeep } from '../../util/object/readonlyType';
+import type { Maybe } from '../../util/type';
+import type { Timestamp } from '../../util/date/date';
+export interface NetworkMetricsControllerImplOptions {
+    /**
+     * The smoothing factor for EWMA (Exponential Moving Weighted Average), used in
+     * bandwidth and response time moving averages.
+     *
+     * The purpose is to give more weight to recent events than old events, while keeping
+     * calculations simple and avoiding the need to keep histories as a rolling average would.
+     *
+     * This value should be between 0 and 1.
+     * The closer to 1 this value is, the more weight new values have.
+     * A value of 0.2 for example would mean that after 10 updates, the current average after
+     * ten new data points would influence the new average by (1-0.2)^10 ≈ 10% and the latest
+     * update would influence the average by 20%.
+     */
+    readonly ewmaSmoothing: number;
+    /**
+     * For biased values such as ewmaHigh/ewmaLow, when the value is in the direction of the
+     * bias, this smoothing will be used.
+     * This should be a value between 0 and 1 and be more than bias negative smoothing.
+     */
+    readonly ewmaBiasPositiveSmoothing: number;
+    /**
+     * For biased values such as ewmaHigh/ewmaLow, when the value is not in the direction of the
+     * bias, this smoothing will be used.
+     * This should be a value between 0 and 1 and be less than bias positive smoothing.
+     */
+    readonly ewmaBiasNegativeSmoothing: number;
+    /**
+     * When the user's bandwidth cannot be determined due to lack of NetworkInformation support
+     * and no reported downlink history, then this value will be used.
+     * This should be in bits per second.
+     */
+    readonly unknownDownlinkBandwidthEstimate: number;
+    /**
+     * Maximum bandwidth in bps we will attribute to any single measurement.
+     * Transfers measured above this are clamped; zero-duration transfers are
+     * treated as this speed rather than discarded.
+     * Default: 30_000_000
+     */
+    readonly maxMeasuredBandwidthBps: number;
+    /**
+     * Time window (in seconds) for amortizing network transfer entries in bandwidth estimation.
+     *
+     * This window enables accurate bandwidth calculation across multiple concurrent streams
+     * (audio, video, etc.) by aggregating transfer data over time.
+     *
+     * - Too low: Streams won't be properly combined, leading to inaccurate estimates
+     * - Too high: Bandwidth estimation becomes slow to adapt to network changes
+     *
+     * @default 4
+     */
+    readonly bandwidthEstimationWindow: number;
+}
+/**
+ * Default configuration for NetworkMetricsControllerImpl
+ */
+export declare const defaultNetworkMetricsControllerImplOptions: {
+    readonly ewmaSmoothing: 0.2;
+    readonly ewmaBiasNegativeSmoothing: 0.1;
+    readonly ewmaBiasPositiveSmoothing: 0.5;
+    readonly unknownDownlinkBandwidthEstimate: 2200000;
+    readonly maxMeasuredBandwidthBps: 30000000;
+    readonly bandwidthEstimationWindow: 4;
+};
+export interface NetworkMetricsControllerImplDependencies {
+    readonly networkInformation?: Maybe<NetworkInformation>;
+}
+export declare class NetworkMetricsControllerImpl extends EventHostImpl<NetworkMetricsEventMap> implements NetworkMetricsController {
+    private readonly deps;
+    private _metrics;
+    /**
+     * A clone of _metrics, copied on read after a change.
+     * @private
+     */
+    private _metricsSnapshot;
+    private hasChanged;
+    private readonly options;
+    private readonly transferEntries;
+    private readonly refreshEstimatedBandwidthThrottled;
+    private readonly disposer;
+    constructor(deps: NetworkMetricsControllerImplDependencies, options?: Partial<NetworkMetricsControllerImplOptions>);
+    get [Symbol.toStringTag](): string;
+    get metrics(): NetworkMetrics;
+    getServiceMetrics(serviceId: Maybe<string>): ReadonlyDeep<ServiceMetrics>;
+    addMetricsEntry(entry: NetworkMetricsEntry): void;
+    private readonly refreshEstimatedBandwidth;
+    addDownlinkTransferEntry(entry: NetworkTransferEntry): void;
+    private onDownloadSpeedChange;
+    private notifyMetricsChange;
+    dispose(): void;
+}
+/**
+ * Estimates the timestamp when the first response byte was received for a network transfer.
+ *
+ * When the browser's Resource Timing API provides `responseStart`, that value is used directly.
+ * Otherwise, a logistic model estimates the latency fraction (the proportion of total
+ * request time spent waiting for the first byte) from the transfer size and total duration.
+ *
+ * The model uses a sigmoid function parameterized on a feature combining `log(bytes)` and
+ * `log(totalTime)`. Larger transfers relative to their duration are assumed to have a smaller
+ * latency fraction (most time is spent downloading), while small or slow transfers are assumed
+ * to be latency-dominated.
+ *
+ * `responseEnd` represents when the fetch promise settled (approximately when HTTP headers
+ * arrived). This provides an upper bound on when the first byte was received — the actual
+ * responseStart is at or before this point.
+ *
+ * @param entry - A completed network transfer entry with timing information.
+ * @returns The estimated timestamp (ms since epoch) when the first response byte arrived.
+ */
+export declare function estimateResponseStart(entry: NetworkTransferEntry): Timestamp;
+//# sourceMappingURL=NetworkMetricsControllerImpl.d.ts.map

package/dist/types/ts4.7/network/metrics/networkMetricsGlobal.d.ts

@@ -0,0 +1,11 @@
+import type { NetworkMetricsController } from './NetworkMetricsController';
+import type { NetworkMetrics } from './networkMetricsModel';
+/**
+ * A global reference to the network metrics controller.
+ */
+export declare const networkMetricsController: import("../../global/globalRegistry").GlobalRef<NetworkMetricsController>;
+/**
+ * Returns the global network metrics.
+ */
+export declare function getNetworkMetrics(): NetworkMetrics;
+//# sourceMappingURL=networkMetricsGlobal.d.ts.map

package/dist/types/ts4.7/network/metrics/networkMetricsModel.d.ts

@@ -0,0 +1,147 @@
+import type { Timestamp } from '../../util/date/date';
+import type { ReadonlyRecord } from '../../util/object/readonlyType';
+import type { Maybe } from '../../util/type';
+/**
+ * Statistics for service calls and content transfers.
+ * Immutable
+ */
+export interface NetworkMetrics {
+    /**
+     * Totals for all service metrics, including requests without service ids.
+     */
+    readonly totals: ServiceMetrics;
+    /**
+     * Requests that were made with a service id will have their statistics tracked in this map.
+     * key - The serviceId provided to fetch options.
+     * value - cumulative metrics for that service.
+     */
+    readonly serviceMetrics: ReadonlyRecord<string, ServiceMetrics>;
+    /**
+     * The estimated client bandwidth. Uses data points from totals, network information downlink changes,
+     * and the fallback P90 downlink estimate.
+     */
+    readonly estimatedDownlinkBandwidth: StatMetrics;
+}
+export interface ServiceMetrics {
+    /**
+     * Metrics for OK responses.
+     */
+    readonly successTotals: ServiceTotals;
+    /**
+     * Metrics for !OK responses.
+     */
+    readonly failureTotals: ServiceTotals;
+    /**
+     * If the last request was !ok and there was a retry-after header, this will be set.
+     */
+    readonly retryAfter: Timestamp | null;
+    /**
+     * Metrics describing the response timing for this service, in seconds.
+     */
+    readonly responseTime: StatMetrics;
+}
+/**
+ * Basic statistical values describing the distribution of a datapoint.
+ */
+export interface StatMetrics {
+    /**
+     * The lowest value this stat has recorded.
+     */
+    readonly min: number;
+    /**
+     * The highest value this stat has recorded.
+     */
+    readonly max: number;
+    /**
+     * The simple average.
+     */
+    readonly average: number;
+    /**
+     * The last value recorded.
+     */
+    readonly latest: number;
+    /**
+     * The Exponentially Weighted Moving Average, weighing lower values more than high.
+     */
+    readonly ewmaLow: number;
+    /**
+     * The Exponentially Weighted Moving Average, weighing higher values more than low.
+     */
+    readonly ewmaHigh: number;
+    /**
+     * The Exponentially Weighted Moving Average.
+     */
+    readonly ewma: number;
+    /**
+     * The number of data points these averages represent.
+     */
+    readonly dataPoints: number;
+}
+export interface ServiceTotals {
+    /**
+     * The number of consecutive results with this result.
+     */
+    readonly consecutiveCount: number;
+    /**
+     * The total count with this result.
+     */
+    readonly totalCount: number;
+}
+/**
+ * Information about a completed request attempt.
+ */
+export interface NetworkMetricsEntry {
+    /**
+     * True if the request was successful.
+     */
+    readonly ok: boolean;
+    /**
+     * The id of the service, or null.
+     */
+    readonly serviceId: string | null;
+    /**
+     * If the request was !ok and there was a retry-after header, this will be set.
+     */
+    readonly retryAfter: Timestamp | null;
+    /**
+     * The number of seconds the response took or null for no response.
+     */
+    readonly responseTime: number | null;
+}
+/**
+ * Information about a completed content transfer.
+ */
+export interface NetworkTransferEntry {
+    /**
+     * The id of the service, or null.
+     */
+    readonly serviceId: string | null;
+    /**
+     * Timestamp when the request was initiated.
+     */
+    readonly requestStart: Timestamp;
+    /**
+     * Timestamp when the first byte of the response was transferred.
+     * This should only be provided if performance resource timing
+     * is available.
+     */
+    readonly responseStart?: Maybe<Timestamp>;
+    /**
+     * Timestamp when the response was received.
+     */
+    readonly responseEnd: Timestamp;
+    /**
+     * Timestamp when the full response body was received.
+     */
+    readonly contentEnd: Timestamp;
+    /**
+     * The content-length of the transfer.
+     */
+    readonly bytes: number;
+}
+export declare const EMPTY_SERVICE_TOTALS: ServiceTotals;
+export declare const EMPTY_STAT_METRICS: StatMetrics;
+export declare const EMPTY_SERVICE_METRICS: ServiceMetrics;
+export declare const EMPTY_NETWORK_METRICS: NetworkMetrics;
+export declare const EMPTY_NETWORK_METRICS_ENTRY: NetworkMetricsEntry;
+//# sourceMappingURL=networkMetricsModel.d.ts.map

package/dist/types/ts4.7/network/network.d.ts

@@ -0,0 +1,47 @@
+import { DomEventHost } from '../event/DomEventHost';
+import type { ReadonlyEventHost } from '../event/EventHost';
+import type { ReadonlyAbort } from '../util/async/Abort';
+import type { Maybe } from '../util/type';
+export type DomEventTarget = EventTarget;
+export interface NetworkStateEventMap {
+    readonly offline: Event;
+    readonly online: Event;
+}
+/**
+ * Online status.
+ */
+export interface NetworkState extends ReadonlyEventHost<NetworkStateEventMap> {
+    /**
+     * Returns the online status of the browser.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
+     */
+    readonly onLine: boolean;
+    /**
+     * Returns a promise that resolves when the network state is next online.
+     * Rejects immediately if the given `abortSignal` is in an aborted state.
+     * Resolves immediately if the navigator is currently online.
+     * @param abort If provided, rejects the returned promise when aborted.
+     */
+    nextOnLine(abort?: Maybe<ReadonlyAbort>): Promise<void>;
+}
+export interface NetworkStateImplDeps {
+    readonly eventTarget: DomEventTarget;
+    readonly navigator: {
+        readonly onLine: boolean;
+    };
+}
+export declare class NetworkStateImpl extends DomEventHost<NetworkStateEventMap> implements NetworkState {
+    protected readonly deps: NetworkStateImplDeps;
+    static createDefaultDeps(): NetworkStateImplDeps;
+    constructor(deps?: NetworkStateImplDeps);
+    get onLine(): boolean;
+    nextOnLine(abort?: Maybe<ReadonlyAbort>): Promise<void>;
+}
+/**
+ * A global reference to the network state.
+ */
+export declare const networkState: import("../global/globalRegistry").GlobalRef<NetworkState>;
+export declare function getNetworkState(): NetworkState;
+export declare function onLine(): boolean;
+//# sourceMappingURL=network.d.ts.map