@amazon/vinyl-util 1.0.0

package/dist/types/ts4.1/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.1/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.1/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

package/dist/types/ts4.1/network/requesterGlobal.d.ts

@@ -0,0 +1,19 @@
+import type { Maybe } from '../util/type';
+import type { Requester, RequestInitOptions, RequestOptions } from './Requester';
+/**
+ * @private
+ */
+export declare const requesterWithRetryRef: import("../global/globalRegistry").GlobalRef<Requester>;
+/**
+ * Requests a resource.
+ *
+ * Note: Unlike `window.fetch`, the returned promise is expected to reject if the
+ * response is !ok.
+ *
+ * @param input A url string, URL Object, or RequestInfo object.
+ * @param init A RequestInit object.
+ * @param options Additional configuration such as an abort reference or service id for metrics
+ * and retries.
+ */
+export declare function requestWithRetry(input: RequestInfo | URL, init?: Maybe<RequestInitOptions>, options?: Partial<RequestOptions>): Promise<Response>;
+//# sourceMappingURL=requesterGlobal.d.ts.map

package/dist/types/ts4.1/network/requesterUtil.d.ts

@@ -0,0 +1,28 @@
+import type { ResponseInfo } from './RequesterImplEventMap';
+import type { Timestamp } from '../util/date/date';
+import type { Maybe } from '../util/type';
+/**
+ * Returns true if the failed request should be retried.
+ * @private
+ */
+export declare function shouldRetry(status: number): boolean;
+/**
+ * The default jitter amount after waiting for a retry-after timestamp.
+ */
+export declare function retryAfterJitter(): number;
+/**
+ * Retry-After  = "Retry-After" ":" ( HTTP-date | delta-seconds )
+ * https://www.rfc-editor.org/rfc/rfc2616#page-141
+ *
+ * @param retryAfter The string to parse into a timestamp. If nullish, null is returned.
+ * @returns The unix timestamp to wait until before retrying. If the Retry-After header
+ * could not be found, or provided a date that cannot be parsed, returns null.
+ */
+export declare function parseRetryAfter(retryAfter: Maybe<string>): Timestamp | null;
+/**
+ * Returns serializable response information.
+ *
+ * @param response The Response object. The body will not be read, this does not need to be cloned.
+ */
+export declare function getResponseInfo(response: Response): ResponseInfo;
+//# sourceMappingURL=requesterUtil.d.ts.map

package/dist/types/ts4.1/network/responseUtil.d.ts

@@ -0,0 +1,10 @@
+import type { RequestResponseErrorEvent } from './RequesterImplEventMap';
+import { RequestError } from './RequestError';
+/**
+ * Returns true if the given object is a RequestError with type RESPONSE.
+ * @param error
+ */
+export declare function isResponseError(error: any): error is RequestError & {
+    readonly info: RequestResponseErrorEvent;
+};
+//# sourceMappingURL=responseUtil.d.ts.map

package/dist/types/ts4.1/patch/network/fetch.d.ts

@@ -0,0 +1,11 @@
+import type { Fetch } from '../../network/Requester';
+export declare function requiresPreventCacheRangeRequestsPatch(): boolean;
+/**
+ * On affected UAs, Range requests from cache can fail with a TypeError.
+ *
+ * A message will display in the browser such as net::ERR_CONNECTION_FAILED, which isn't accessible from the Error.
+ * @param original
+ */
+export declare function preventCacheRangeRequestsPatch(original: Fetch): Fetch;
+export declare function patchFetch(original: Fetch): Fetch;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/types/ts4.1/patch/patchTarget.d.ts

@@ -0,0 +1,114 @@
+import type { Disposable } from '../core/disposable';
+import type { Unsubscribe } from '../core/Unsubscribe';
+import type { Signal } from '../event/Signal';
+import type { AnyRecord } from '../util/type';
+import type { LogTarget } from '../logging/LogTarget';
+export interface Patch<T, EventMap = AnyRecord> extends Disposable {
+    /**
+     * A signal that emits synthetic events.
+     * These events will be dispatched on the proxy, not on the original event target.
+     * If undefined, no events are fabricated.
+     */
+    readonly eventFabricated?: Signal<Event>;
+    /**
+     * Overridden properties.
+     */
+    readonly properties?: PropertyPatches<T>;
+    /**
+     * Overridden events.
+     * Event patches may provide an alternate event to emit, or null to prevent an event from
+     * dispatching on the proxy.
+     *
+     * Note:
+     * Patched events have divergent behavior when using Event.stopImmediatePropagation.
+     * All handlers added to the patched Proxy will still be called after stopImmediatePropagation.
+     * It is the author's opinion that using stopImmediatePropagation is an anti-pattern, and one
+     * handler should not be allowed to influence the behavior of neighboring handlers.
+     */
+    readonly events?: EventPatches<EventMap>;
+}
+/**
+ * A record of property key to property patch.
+ */
+export type PropertyPatches<T> = {
+    readonly [P in keyof T]?: PropertyPatch<T, P>;
+};
+/**
+ * An override to a patched property.
+ */
+export interface PropertyPatch<T, K extends keyof T> {
+    /**
+     * @return Returns the value to return on the proxy.
+     */
+    get?(): T[K];
+    /**
+     * @param newValue The property value attempting to be set.
+     */
+    set?(newValue: T[K]): void;
+}
+/**
+ * Handles an event emitted from the event target. The returned event will be emitted in its
+ * place on the proxy.
+ *
+ * Fabricated events from `eventFabricated` will not be passed to this handler and cannot be
+ * squelched.
+ *
+ * @param event The original event from the event target. This should not be modified
+ * directly, but may be cloned and a modified clone may be returned.
+ *
+ * @return Returns the event to emit on the proxy or null to squelch the event.
+ */
+export type EventPatch<T> = (event: T) => T | null;
+/**
+ * A record of event type to an event patch.
+ */
+export type EventPatches<EventMap> = {
+    readonly [P in keyof EventMap]?: EventPatch<EventMap[P]>;
+};
+export type PatchFactory<T, EventMap> = (target: T) => Patch<T, EventMap>;
+export interface PatchedRef<T> extends Disposable {
+    /**
+     * The patched target.
+     */
+    readonly patched: T;
+    /**
+     * A signal for when a synthetic event was fabricated.
+     */
+    eventFabricated: Signal<Event>;
+    /**
+     * A signal for when an event was squelched.
+     */
+    eventSquelched: Signal<Event>;
+}
+/**
+ * Creates a Proxy for patched event and properties on the target. All patches from the provided
+ * factory list will be used in creating a proxy chain. Each patch is applied in order, and
+ * patches can rely on their target having been patched with all previous patches.
+ *
+ * @param target
+ * @param patchFactories A list of factories that each produce a new patch for the target.
+ * @return Returns a disposable object with a Proxy reference with overridden event and property
+ * behavior. When disposed, the event listeners are removed.
+ */
+export declare function patchTarget<T extends object, EventMap = AnyRecord>(target: T, ...patchFactories: PatchFactory<T, EventMap>[]): PatchedRef<T>;
+/**
+ * Logs debug messages when an event was squelched or fabricated.
+ *
+ * @param pathTarget
+ * @param patched
+ * @return Returns a function that when invoked, removes the logging.
+ */
+export declare function logPatchedEvents(pathTarget: LogTarget, patched: PatchedRef<any>): Unsubscribe;
+/**
+ * A tuple of `[flag, factory]`.
+ * Patches will be applied when flag is true.
+ */
+export type FlagAndPatchEntry<T extends object, EventMap, Key> = readonly [
+    flagKey: Key,
+    factory: PatchFactory<T, EventMap>
+];
+/**
+ * Given a list of [flagKey, patchFactory] tuples, patches the target with patches where flag is true.
+ */
+export declare function patchTargetFromFlags<T extends object, EventMap, Flags>(target: T, flags: Flags, ...patchEntries: readonly FlagAndPatchEntry<T, EventMap, keyof Flags>[]): PatchedRef<T>;
+//# sourceMappingURL=patchTarget.d.ts.map

package/dist/types/ts4.1/persistence/KeyValuePersistence.d.ts

@@ -0,0 +1,28 @@
+/**
+ * An abstract persistence interface for an async key / value store.
+ */
+export interface KeyValuePersistence<T> {
+    /**
+     * Resolves to the value for the given key, or null if non-existent.
+     * @param key
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Saves the given value to disk.
+     *
+     * @param key
+     * @param value
+     */
+    set(key: string, value: T): Promise<void>;
+    /**
+     * Removes the given key.
+     *
+     * @param key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Clears all items.
+     */
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=KeyValuePersistence.d.ts.map

package/dist/types/ts4.1/persistence/PersistentItem.d.ts

@@ -0,0 +1,86 @@
+import type { LogTarget } from '../logging/LogTarget';
+import type { KeyValuePersistence } from '../persistence/KeyValuePersistence';
+import type { Maybe } from '../util/type';
+/**
+ * Configuration for PersistentItemImpl
+ * These values will not be accessed until the persistent item is first used.
+ */
+export interface PersistentItemOptions<T, FormatType> {
+    /**
+     * The key to use in the Persistence layer.
+     */
+    readonly key: string;
+    /**
+     * The default to use when the key is not present or deserialization fails.
+     */
+    readonly defaultValue: T;
+    /**
+     * If provided, will be invoked on the persisted value.
+     */
+    readonly validator?: Maybe<(input: unknown) => asserts input is T>;
+    /**
+     * The key/value persistence raw data provider.
+     *
+     * Provides the KeyValuePersistence controller.
+     * Can be a method to lazily provide the controller, will be invoked once on first access.
+     */
+    readonly persistence: KeyValuePersistence<FormatType> | (() => KeyValuePersistence<FormatType>);
+    /**
+     * Serializes the value for persistence.
+     */
+    readonly serialize: (value: T) => FormatType;
+    /**
+     * Deserializes value into the output value.
+     */
+    readonly deserialize: (value: FormatType) => T;
+}
+export interface PersistentItem<T> {
+    /**
+     * Gets this item from persistence.
+     */
+    get(): Promise<T>;
+    /**
+     * Saves this item to persistence.
+     */
+    set(value: T): Promise<void>;
+    /**
+     * Removes this item from persistence.
+     */
+    remove(): Promise<void>;
+}
+export declare class PersistentItemImpl<T, FormatType> implements PersistentItem<T>, LogTarget {
+    private readonly options;
+    readonly logPrefix: string;
+    private readonly persistence;
+    constructor(options: PersistentItemOptions<T, FormatType>);
+    /**
+     * Gets this item from persistence.
+     */
+    get(): Promise<T>;
+    /**
+     * Saves this item to persistence.
+     */
+    set(value: T): Promise<void>;
+    /**
+     * Removes this item from persistence.
+     */
+    remove(): Promise<void>;
+}
+/**
+ * An alias for persistent item options with reasonable defaults for string
+ * serialization.
+ * This will use JSON stringify/parse and the global KeyValuePersistence object
+ * from `persistenceRef`.
+ */
+export type DefaultStringPersistentItemOptions<T> = Omit<PersistentItemOptions<T, string>, 'persistence' | 'deserialize' | 'serialize'> & Partial<Pick<PersistentItemOptions<T, string>, 'persistence' | 'deserialize' | 'serialize'>>;
+/**
+ * Creates a new PersistenceItem from the given options.
+ * If serializer, deserializer, and persistence is omitted, then
+ * JSON stringify/parse and the global KeyValuePersistence object
+ * from `persistenceRef` will be used.
+ *
+ * @param options
+ */
+export declare function createPersistentItem<T>(options: DefaultStringPersistentItemOptions<T>): PersistentItemImpl<T, string>;
+export declare function createPersistentItem<T, U>(options: PersistentItemOptions<T, U>): PersistentItemImpl<T, U>;
+//# sourceMappingURL=PersistentItem.d.ts.map

package/dist/types/ts4.1/persistence/StoragePersistence.d.ts

@@ -0,0 +1,11 @@
+import type { KeyValuePersistence } from '../persistence/KeyValuePersistence';
+import type { Maybe } from '../util/type';
+export declare class StoragePersistence implements KeyValuePersistence<string> {
+    private readonly storage;
+    constructor(storage: Maybe<Storage>);
+    clear(): Promise<void>;
+    get(key: string): Promise<string | null>;
+    remove(key: string): Promise<void>;
+    set(key: string, value: string): Promise<void>;
+}
+//# sourceMappingURL=StoragePersistence.d.ts.map

package/dist/types/ts4.1/persistence/persistenceRef.d.ts

@@ -0,0 +1,7 @@
+import type { KeyValuePersistence } from '../persistence/KeyValuePersistence';
+/**
+ * The default storage persistence for simple key / value pairs.
+ * This may be overridden, and by default resolves to local storage persistence.
+ */
+export declare const persistenceRef: import("../global/globalRegistry").GlobalRef<KeyValuePersistence<string>>;
+//# sourceMappingURL=persistenceRef.d.ts.map

package/dist/types/ts4.1/util/async/Abort.d.ts

@@ -0,0 +1,96 @@
+import type { ReadonlyEventHost } from '../../event/EventHost';
+import { EventHostImpl } from '../../event/EventHost';
+import type { Unsubscribe } from '../../core/Unsubscribe';
+export interface AbortEvent {
+    readonly reason: Error;
+}
+export interface AbortEventMap {
+    readonly abort: AbortEvent;
+}
+export interface ReadonlyAbort extends ReadonlyEventHost<AbortEventMap> {
+    /**
+     * True if aborted.
+     */
+    aborted(): boolean;
+    /**
+     * The reason passed to `abort`.
+     */
+    readonly reason: Error | null;
+    /**
+     * Throws the signal's abort reason if the signal has been aborted; otherwise it does nothing.
+     */
+    throwIfAborted(): void;
+    /**
+     * Invokes a callback on 'abort', or immediately if already aborted.
+     */
+    onAborted(callback: (event: AbortEvent) => void): Unsubscribe;
+    /**
+     * Returns a native signal on supported platforms.
+     */
+    readonly nativeSignal: AbortSignal | null;
+}
+/**
+ * Returns a new native abort controller, if this environment supports AbortController.abort.
+ *
+ * Supported in Chrome 66+, Edge 16+, Firefox 57+, Opera 53+, Safari 11.3+,
+ */
+export declare function createAbortController(): AbortController | null;
+export interface AbortDeps {
+    readonly abortControllerFactory?: () => AbortController | null;
+}
+/**
+ * An Abort instance emits an 'abort' event when aborted.
+ *
+ * A native `AbortController` is encapsulated if the platform supports it, allowing for fetch
+ * cancellation.
+ */
+export declare class Abort extends EventHostImpl<AbortEventMap> implements ReadonlyAbort {
+    private readonly deps?;
+    get [Symbol.toStringTag](): string;
+    constructor(deps?: AbortDeps | undefined);
+    private _reason;
+    /**
+     * True if this signal is aborted.
+     */
+    aborted(): boolean;
+    get reason(): (Error | null);
+    private _nativeSignal;
+    get nativeSignal(): (AbortSignal | null);
+    /**
+     * Throws this signal's abort reason if the signal has been aborted; otherwise it does nothing.
+     */
+    throwIfAborted(): void;
+    /**
+     * Invokes a callback on 'abort', or immediately if already aborted.
+     */
+    onAborted(callback: (event: AbortEvent) => void): Unsubscribe;
+    /**
+     * Sets to the aborted state with the given reason, and emits an 'abort' event.
+     * If this signal is already aborted, this will do nothing.
+     */
+    abort(reason?: Error): void;
+}
+export interface AbortSlot {
+    readonly value: ReadonlyAbort;
+    abort(reason?: Error): void;
+}
+/**
+ * Creates a reusable abort slot that exposes a read-only `Abort` instance.
+ *
+ * Each call to `abort()` triggers the current `Abort` instance, and then replaces it
+ * with a fresh instance for future use. This is useful in systems where cancelable operations
+ * are repeatedly started and each one needs its own `Abort` signal.
+ *
+ * @returns An object with:
+ * - `value`: A read-only reference to the current `Abort` instance.
+ * - `abort(reason)`: Aborts the current instance with the given reason, then creates a new one.
+ *
+ * Example:
+ * ```ts
+ * const slot = createAbortSlot()
+ * fetch(url, { signal: slot.value.signal })
+ * slot.abort() // aborts current Abort value and prepares a new instance
+ * ```
+ */
+export declare function createAbortSlot(): AbortSlot;
+//# sourceMappingURL=Abort.d.ts.map

package/dist/types/ts4.1/util/async/Deferred.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A Deferred object is a Promise with public methods to resolve and reject.
+ *
+ * Example:
+ *
+ * ```
+ *  const deferred = new Deferred<number>()
+ *  setTimeout(() => {
+ *      deferred.resolve(42)
+ *  }, 1000)
+ *
+ *  deferred.then(value => console.log('Resolved to:', value))
+ * ```
+ */
+export declare class Deferred<T> implements Promise<T> {
+    private readonly promise;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+    constructor();
+    catch<TResult = never>(onrejected?: ((reason: any) => PromiseLike<TResult> | TResult) | null): Promise<T | TResult>;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => PromiseLike<TResult1> | TResult1) | null, onrejected?: ((reason: any) => PromiseLike<TResult2> | TResult2) | null): Promise<TResult1 | TResult2>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=Deferred.d.ts.map