@amazon/vinyl-util 1.0.0

package/dist/types/ts4.7/global/globalRegistry.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Manages global initializers.
+ */
+export declare class GlobalRegistry {
+    private registry;
+    /**
+     * Returns the number of references currently in the registry.
+     */
+    get size(): number;
+    /**
+     * Registers an initializer that will be invoked during global state initialization.
+     * @param initializer
+     */
+    register<T extends GlobalRef<any>>(initializer: T): T;
+    /**
+     * Removes a global ref from the registry.
+     * May be called at any time.
+     * @param ref
+     * @return Returns true if the global ref was removed.
+     */
+    unregister(ref: GlobalRef<any>): boolean;
+    /**
+     * Resets all registered initializers and sets this registry back to its pre-initialized state.
+     * This is typically only done within unit tests, but may be called if all players are
+     * disposed and the consumer intends to teardown global state.
+     */
+    reset(): void;
+}
+/**
+ * Gets or creates the global registry instance.
+ */
+export declare function getGlobalRegistry(): GlobalRegistry;
+export interface GlobalRef<T> {
+    /**
+     * True if this has been initialized.
+     */
+    readonly initialized: boolean;
+    /**
+     * Returns the factory-produced value.
+     * Throws an {@link IllegalStateError} if the global registry has not been initialized.
+     */
+    readonly value: T;
+    /**
+     * Overrides this initializer.
+     * The previous initializer will be provided as an argument for extension.
+     *
+     * Throws an {@link IllegalStateError} if the global registry has been initialized.
+     * @return Returns this
+     */
+    set(newInitializer: (previousInitializer: () => T) => T): GlobalRef<T>;
+    /**
+     * Resets this initializer back to its pre-initialized state.
+     * If the initializer produced a disposable value, it will be disposed.
+     */
+    reset(): void;
+    /**
+     * Initializes the global ref.
+     * This is done automatically on first use of `value`, but may be initialized eagerly.
+     */
+    initialize(): void;
+}
+export declare function setGlobalRefDebug(enabled: boolean): void;
+export declare class GlobalRefImpl<T> implements GlobalRef<T> {
+    private readonly defaultInitializer;
+    private _value;
+    private _initialized;
+    private constructing;
+    private initializer;
+    private lastInitStack;
+    constructor(defaultInitializer: () => T);
+    get initialized(): boolean;
+    get value(): T;
+    reset(): void;
+    initialize(): void;
+    set(newInitializer: (previousInitializer: () => T) => T): GlobalRef<T>;
+    private assertNotInitialized;
+    private assertNotConstructing;
+}
+/**
+ * Creates a global reference that can be lazily initialized.
+ * This function is tree-shakable as it doesn't perform any side effects on import.
+ *
+ * @param init Factory function that creates the value
+ */
+export declare function globalRef<T>(init: () => T): GlobalRef<T>;
+//# sourceMappingURL=globalRegistry.d.ts.map

package/dist/types/ts4.7/global/globalTarget.d.ts

@@ -0,0 +1,8 @@
+import type { LogTarget } from '../logging/LogTarget';
+/**
+ * The global path target.
+ * Global systems such as logging or uncaught error handling may use this when a pathTarget
+ * is needed.
+ */
+export declare const globalTarget: LogTarget;
+//# sourceMappingURL=globalTarget.d.ts.map

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

@@ -0,0 +1,118 @@
+/** Auto-generated from build scripts */
+export * from './util/type';
+export * from './util/url/resolveUrl';
+export * from './util/string/uid';
+export * from './util/string/string';
+export * from './util/string/StringReader';
+export * from './util/set/set';
+export * from './util/serialization/stringifyForPrint';
+export * from './util/serialization/primitives';
+export * from './util/serialization/json';
+export * from './util/serialization/ParseError';
+export * from './util/range/timeRanges';
+export * from './util/range/UnionRanges';
+export * from './util/range/Ranges';
+export * from './util/range/IntersectionRanges';
+export * from './util/object/readonlyType';
+export * from './util/object/object';
+export * from './util/object/mutableType';
+export * from './util/object/mergeDeep';
+export * from './util/object/merge';
+export * from './util/object/lazy';
+export * from './util/object/equalDeep';
+export * from './util/object/clone';
+export * from './util/network/request';
+export * from './util/mpeg/parseSidxBox';
+export * from './util/math/math';
+export * from './util/map/map';
+export * from './util/iteration/iterable';
+export * from './util/fun/throttle';
+export * from './util/fun/memoize';
+export * from './util/fun/function';
+export * from './util/fun/flow';
+export * from './util/fun/debounce';
+export * from './util/error/stack';
+export * from './util/date/date';
+export * from './util/config/ValueProvider';
+export * from './util/comparison/compare';
+export * from './util/collection/typedArray';
+export * from './util/collection/array';
+export * from './util/collection/LruCache';
+export * from './util/collection/LinkedList';
+export * from './util/collection/CacheMap';
+export * from './util/buffer/buffer';
+export * from './util/buffer/BufferWriter';
+export * from './util/buffer/BufferReader';
+export * from './util/buffer/BufferError';
+export * from './util/browser/searchParams';
+export * from './util/async/timeout';
+export * from './util/async/sleep';
+export * from './util/async/promise';
+export * from './util/async/never';
+export * from './util/async/abortUtils';
+export * from './util/async/TimeoutSlot';
+export * from './util/async/TimeoutController';
+export * from './util/async/TaskQueue';
+export * from './util/async/Deferred';
+export * from './util/async/Abort';
+export * from './persistence/persistenceRef';
+export * from './persistence/StoragePersistence';
+export * from './persistence/PersistentItem';
+export * from './persistence/KeyValuePersistence';
+export * from './patch/patchTarget';
+export * from './patch/network/fetch';
+export * from './network/responseUtil';
+export * from './network/requesterUtil';
+export * from './network/requesterGlobal';
+export * from './network/network';
+export * from './network/createRequester';
+export * from './network/RequesterImplEventMap';
+export * from './network/RequesterImpl';
+export * from './network/Requester';
+export * from './network/RequestInterceptor';
+export * from './network/RequestError';
+export * from './network/metrics/networkMetricsModel';
+export * from './network/metrics/networkMetricsGlobal';
+export * from './network/metrics/NetworkMetricsControllerImpl';
+export * from './network/metrics/NetworkMetricsController';
+export * from './network/logging/networkLoggingHandler';
+export * from './network/browser/NetworkInformation';
+export * from './logging/logTimer';
+export * from './logging/getLogLevelFromSearch';
+export * from './logging/VinylLogging';
+export * from './logging/Logger';
+export * from './logging/LogTarget';
+export * from './logging/HistoryLogHandler';
+export * from './logging/ConsoleLogHandler';
+export * from './global/globalTarget';
+export * from './global/globalRegistry';
+export * from './global/environment';
+export * from './event/redispatchEvents';
+export * from './event/onAny';
+export * from './event/nextEventAsPromise';
+export * from './event/Signal';
+export * from './event/EventHost';
+export * from './event/DomEventHost';
+export * from './error/ValidationError';
+export * from './error/UnreachableCodeError';
+export * from './error/TimeoutError';
+export * from './error/StackOverflowError';
+export * from './error/ServiceResponseError';
+export * from './error/ReportableError';
+export * from './error/MediaUnsupportedError';
+export * from './error/IllegalStateError';
+export * from './error/IllegalArgumentError';
+export * from './error/ErrorOrigin';
+export * from './error/AbortError';
+export * from './core/disposable';
+export * from './core/cloneable';
+export * from './core/clearable';
+export * from './core/Unsubscribe';
+export * from './client/Version';
+export * from './client/userAgent/userAgentRuleHelpers';
+export * from './client/userAgent/tokenizeUserAgent';
+export * from './client/userAgent/parseUserAgent';
+export * from './client/userAgent/hasBrowser';
+export * from './client/userAgent/defaultUserAgentRules';
+export * from './client/userAgent/UserAgentInfo';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.7/logging/ConsoleLogHandler.d.ts

@@ -0,0 +1,26 @@
+import type { Disposable } from '../core/disposable';
+import type { ReadonlyEventHost } from '../event/EventHost';
+import type { LogEventMap } from './Logger';
+import { LogLevel } from './Logger';
+export interface ConsoleLike {
+    log(message?: any, ...optionalParams: any[]): void;
+    debug(message?: any, ...optionalParams: any[]): void;
+    warn(message?: any, ...optionalParams: any[]): void;
+    error(message?: any, ...optionalParams: any[]): void;
+}
+/**
+ * A log target that logs to a console.
+ */
+export interface ConsoleLogHandler {
+    logLevel: LogLevel;
+}
+/**
+ * A {@link ConsoleLogHandler} implementation.
+ */
+export declare class ConsoleLogHandlerImpl implements ConsoleLogHandler, Disposable {
+    logLevel: LogLevel;
+    private readonly logSub;
+    constructor(host: ReadonlyEventHost<LogEventMap>, logLevel?: LogLevel, consoleLike?: ConsoleLike);
+    dispose(): void;
+}
+//# sourceMappingURL=ConsoleLogHandler.d.ts.map

package/dist/types/ts4.7/logging/HistoryLogHandler.d.ts

@@ -0,0 +1,56 @@
+import type { Disposable } from '../core/disposable';
+import type { ReadonlyEventHost } from '../event/EventHost';
+import type { LogEventMap } from './Logger';
+import { LogLevel } from './Logger';
+import type { ReadonlyDate } from '../util/object/readonlyType';
+/**
+ * The default maximum history size for the history log handler.
+ */
+export declare const DEFAULT_MAX_HISTORY = 100;
+export interface HistoryLogItem {
+    readonly timestamp: ReadonlyDate;
+    readonly messages: readonly any[];
+    readonly level: LogLevel;
+    /**
+     * The LogTarget's logPrefix.
+     */
+    readonly logPrefix: string;
+}
+/**
+ * Logs to a rolling list.
+ */
+export interface HistoryLogHandler {
+    /**
+     * This level and higher will be logged to the history.
+     * Default is {@link LogLevel.DEBUG}
+     */
+    logLevel: LogLevel;
+    /**
+     * The maximum number of logs to keep.
+     */
+    maxHistorySize: number;
+    /**
+     * The log history, kept up to {@link maxHistorySize}
+     */
+    get history(): readonly HistoryLogItem[];
+    /**
+     * Clears the log history.
+     */
+    clear(): void;
+}
+/**
+ * A basic HistoryLogHandler implementation.
+ */
+export declare class HistoryLogHandlerImpl implements HistoryLogHandler, Disposable {
+    logLevel: LogLevel;
+    private readonly _history;
+    private readonly logSub;
+    private _maxHistorySize;
+    constructor(host: ReadonlyEventHost<LogEventMap>, logLevel?: LogLevel);
+    get maxHistorySize(): number;
+    set maxHistorySize(value: number);
+    get history(): readonly HistoryLogItem[];
+    clear(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=HistoryLogHandler.d.ts.map

package/dist/types/ts4.7/logging/LogTarget.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Provides the logging prefix for all logs made by this target.
+ */
+export interface LogTarget {
+    /**
+     * A string prefix for all log statements made by this target.
+     */
+    readonly logPrefix: string;
+}
+/**
+ * Creates a unique log prefix.
+ *
+ * @param target Either a string or an object with a toStringTag.
+ * The log prefix will append a unique counter.
+ */
+export declare function createLogPrefix(target: string | {
+    readonly [Symbol.toStringTag]: string;
+}): string;
+//# sourceMappingURL=LogTarget.d.ts.map

package/dist/types/ts4.7/logging/Logger.d.ts

@@ -0,0 +1,66 @@
+import type { ReadonlyEventHost } from '../event/EventHost';
+import { EventHostImpl } from '../event/EventHost';
+import type { LogTarget } from '../logging/LogTarget';
+export declare enum LogLevel {
+    VERBOSE = 0,
+    DEBUG = 1,
+    INFO = 2,
+    WARN = 3,
+    ERROR = 4,
+    NONE = 5
+}
+export interface LogEvent {
+    readonly messages: any[];
+    readonly target: LogTarget;
+    readonly level: LogLevel;
+}
+export interface LogEventMap {
+    readonly log: LogEvent;
+}
+/**
+ * The interface for a basic logger implementation.
+ */
+export interface Logger extends ReadonlyEventHost<LogEventMap> {
+    logLevel: LogLevel;
+    log(target: LogTarget, level: LogLevel, ...messages: readonly any[]): void;
+}
+export declare class LoggerImpl extends EventHostImpl<LogEventMap> implements Logger {
+    logLevel: LogLevel;
+    get [Symbol.toStringTag](): string;
+    constructor(logLevel?: LogLevel);
+    log(target: LogTarget, level: LogLevel, ...messages: readonly any[]): void;
+}
+/**
+ * A global reference to the logger.
+ * @private
+ */
+export declare const loggerRef: import("../global/globalRegistry").GlobalRef<Logger>;
+/**
+ * Returns the current log level.
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * Sets the current log level.
+ *
+ * @param value
+ */
+export declare function setLogLevel(value: LogLevel): void;
+export declare function log(target: LogTarget, level: LogLevel, ...messages: readonly any[]): void;
+export declare function logVerbose(target: LogTarget, ...messages: readonly any[]): void;
+export declare function logDebug(target: LogTarget, ...messages: readonly any[]): void;
+export declare function logInfo(target: LogTarget, ...messages: readonly any[]): void;
+export declare function logWarn(target: LogTarget, ...messages: readonly any[]): void;
+export declare function logError(target: LogTarget, ...messages: readonly any[]): void;
+/**
+ * From a case-insensitive string, returns the log level.
+ * Possible values match to the keys in {@link LogLevel}.
+ *
+ * @param str
+ */
+export declare function parseLogLevel(str: string): LogLevel | null;
+/**
+ * Returns the log level as a lowercase string.
+ * E.g. stringifyLogLevel(LogLevel.DEBUG) returns 'debug'
+ */
+export declare function stringifyLogLevel(logLevel: LogLevel): string;
+//# sourceMappingURL=Logger.d.ts.map

package/dist/types/ts4.7/logging/VinylLogging.d.ts

@@ -0,0 +1,9 @@
+import type { ConsoleLogHandler } from './ConsoleLogHandler';
+import type { HistoryLogHandler } from './HistoryLogHandler';
+export declare const historyLogHandler: import("../global/globalRegistry").GlobalRef<HistoryLogHandler | undefined>;
+export declare const consoleLogHandler: import("../global/globalRegistry").GlobalRef<ConsoleLogHandler | undefined>;
+/**
+ * Initializes vinyl logging.
+ */
+export declare function initializeLogging(): void;
+//# sourceMappingURL=VinylLogging.d.ts.map

package/dist/types/ts4.7/logging/getLogLevelFromSearch.d.ts

@@ -0,0 +1,8 @@
+import { LogLevel } from '../logging/Logger';
+/**
+ * Returns the current vinyl logging level, as set by the querystring parameter: vinylLogLevel.
+ * @param search
+ * @param defaultLevel
+ */
+export declare function getLogLevelFromSearch(search?: string, defaultLevel?: LogLevel): LogLevel;
+//# sourceMappingURL=getLogLevelFromSearch.d.ts.map

package/dist/types/ts4.7/logging/logTimer.d.ts

@@ -0,0 +1,10 @@
+import type { LogTarget } from '../logging/LogTarget';
+/**
+ * Creates a timer that logs elapsed time when called.
+ *
+ * @param target - The log target
+ * @param message - Message to log with the elapsed time
+ * @returns Function that logs the elapsed time since creation
+ */
+export declare function logTimer(target: LogTarget, message: string): () => void;
+//# sourceMappingURL=logTimer.d.ts.map

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

@@ -0,0 +1,26 @@
+import { ReportableError } from '../error/ReportableError';
+import { type RequestErrorEvent } from './RequesterImplEventMap';
+import { type Json } from '../util/serialization/json';
+/**
+ * An error reported from a service response.
+ */
+export declare class RequestError extends ReportableError {
+    /**
+     * When the request failure is a !ok response, this will be set.
+     */
+    readonly response: Response | null;
+    readonly info: RequestErrorEvent;
+    get [Symbol.toStringTag](): string;
+    private static getErrorMessage;
+    /**
+     * 500 errors are external service errors, all other errors are considered internal.
+     */
+    static getErrorOrigin(info: RequestErrorEvent): string;
+    constructor(
+    /**
+     * When the request failure is a !ok response, this will be set.
+     */
+    response: Response | null, info: RequestErrorEvent);
+    toJSON(): Json;
+}
+//# sourceMappingURL=RequestError.d.ts.map

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

@@ -0,0 +1,14 @@
+export interface MutableRequestParams {
+    input: string;
+    init: Omit<RequestInit, 'signal'>;
+}
+/**
+ * Mutates a request before it's made.
+ * A request interceptor can be set in Vinyl dependencies. It will be called immediately before a request is made.
+ * The interceptor may modify the request, for example to add headers, change caching, or client-side redirection.
+ * Example to disable caching:
+ *
+ * `(params) => { params.init.cache = 'no-cache' }`
+ */
+export type RequestInterceptor = (params: MutableRequestParams) => void;
+//# sourceMappingURL=RequestInterceptor.d.ts.map

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

@@ -0,0 +1,84 @@
+import type { ReadonlyAbort } from '../util/async/Abort';
+import type { Maybe } from '../util/type';
+/**
+ * Init options for the request.
+ *
+ * This mirrors the fetch init parameter omitting `signal`. For request cancellation, use
+ * `abort` on RequestOptions.
+ */
+export type RequestInitOptions = Readonly<Omit<RequestInit, 'signal'>>;
+/**
+ * Encapsulates the parameters needed to make a request.
+ */
+export interface RequestParams {
+    readonly input: RequestInfo | Readonly<URL>;
+    readonly init?: Maybe<Readonly<RequestInitOptions>>;
+    readonly requestOptions?: Maybe<RequestOptions>;
+}
+/**
+ * An abstraction to fetching resources.
+ * Implementations may have retry or throttling behaviors.
+ */
+export interface Requester {
+    /**
+     * Requests a resource.
+     *
+     * Note: Unlike `window.fetch`, the returned promise is expected to reject if the
+     * response is !ok.
+     */
+    request(input: RequestInfo | Readonly<URL>, init?: Maybe<RequestInitOptions>, requestOptions?: Maybe<RequestOptions>): Promise<Response>;
+}
+/**
+ * Configuration for a fetch request.
+ */
+export interface RequestOptions {
+    /**
+     * If supplied, will cancel the request on abort.
+     */
+    readonly abort?: Maybe<ReadonlyAbort>;
+    /**
+     * Determines how error responses are read and reported.
+     */
+    readonly readErrorBody?: ErrorBodyType;
+    /**
+     * The service id is used to obtain a service controller for that service.
+     * If nullish, then empty service metrics will be used.
+     */
+    readonly serviceId?: Maybe<string>;
+}
+export declare enum ErrorBodyType {
+    DISABLED = 0,
+    TEXT = 1,
+    JSON = 2
+}
+/**
+ * The signature of `window.fetch`. Provided as a dependency for testing.
+ */
+export type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Capped exponential backoff timing with jitter.
+ *
+ * The timing follows the equation:
+ * `distribution() * min(interval * pow(exponentBase, failureCount), max)`
+ */
+export interface BackoffOptions {
+    /**
+     * The maximum time to wait between tries, in seconds, regardless of how many consecutive
+     * failures.
+     */
+    readonly maxTime: number;
+    /**
+     * The interval in seconds, multiplied by `pow(exponentBase, failureCount)`.
+     */
+    readonly interval: number;
+    /**
+     * pow(exponentBase, failureCount)
+     */
+    readonly exponentBase: number;
+    /**
+     * The distribution function to randomize request retry timing.
+     * This is to prevent all users from making retries at the same time.
+     */
+    readonly distribution: () => number;
+}
+//# sourceMappingURL=Requester.d.ts.map

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

@@ -0,0 +1,120 @@
+import { EventHostImpl } from '../event/EventHost';
+import type { NetworkMetricsController } from './metrics/NetworkMetricsController';
+import { type BackoffOptions, type Fetch, type Requester, type RequestInitOptions, type RequestOptions } from './Requester';
+import type { RequesterImplEventMap } from './RequesterImplEventMap';
+import type { Maybe, PartialDeep } from '../util/type';
+/**
+ * Request impl options configuring retry and timeout behavior.
+ */
+export interface RequesterImplOptions {
+    /**
+     * Retry configuration.
+     */
+    readonly retryOptions: RetryOptions;
+    /**
+     * The timeout (in seconds) before the request is aborted.
+     */
+    readonly timeout: number;
+}
+export interface RetryOptions {
+    /**
+     * The maximum number of retries for a single request.
+     * Default: 1
+     * For requests with side effects, this should be set to 0.
+     *
+     * "Various studies have collected data which shows that one max retry is sufficient to
+     * achieve 99.999% success. The idea is that a truly transient failure should succeed on
+     * the first retry.  And if the retry fails then it is likely more than a transient failure
+     * and additional retries are exhausting resources in the system for no benefit."
+     */
+    readonly retries: number;
+    /**
+     * The number of consecutive failures before retries are no longer attempted, only tries.
+     */
+    readonly retryFailureCutoff: number;
+    /**
+     * Retry backoff timing.
+     */
+    readonly retryBackoff: BackoffOptions;
+    /**
+     * First try backoff timing.
+     */
+    readonly tryBackoff: BackoffOptions;
+    /**
+     * If there is a retry-after header, add the returned amount of time (in seconds) to prevent
+     * clustered retry behavior.
+     */
+    readonly retryAfterJitter: () => number;
+    /**
+     * Given the network status code, returns true if the fetch should retry.
+     */
+    readonly shouldRetry: (status: number) => boolean;
+}
+/**
+ * The minimum amount of time to leave for network calls. If the `max try time -
+ * timeout` is less than this value, an IllegalArgumentError will be thrown.
+ */
+export declare const MIN_SERVICE_TIME = 10;
+/**
+ * Distribute requests across the last 50% of the exponential back-off time
+ */
+export declare function defaultBackoffDistribution(): number;
+/**
+ * Calculates the timer delay according to an exponential back off strategy.
+ *
+ * @param failedCount The number of times the service has consecutively failed.
+ * @param options Retry timing options (default values from:
+ *   `defaultRetryOptions`)
+ *
+ * @returns The delay to retry a network request in seconds. This will be clamped
+ *   between 1 and `options.maxRetryTime`.
+ */
+export declare function getBackoffTime(failedCount: number, options: BackoffOptions): number;
+/**
+ * Dependencies for {@link RequesterImpl}
+ */
+export interface RequesterImplDeps {
+    readonly fetch: Fetch;
+    readonly networkMetricsController: NetworkMetricsController;
+}
+export declare const RetryStrategy: {
+    readonly NO_RETRIES: RetryOptions;
+    readonly ONE_RETRY: RetryOptions;
+};
+/**
+ * A quality of service wrapper to `global.fetch`.
+ * Handles retries, network status, and emits events that may be used in reporting or metrics.
+ */
+export declare class RequesterImpl extends EventHostImpl<RequesterImplEventMap> implements Requester {
+    protected readonly deps: RequesterImplDeps;
+    get [Symbol.toStringTag](): string;
+    /**
+     * Default values for fetch options.
+     */
+    private _options;
+    constructor(deps: RequesterImplDeps);
+    /**
+     * The current base options.
+     * {@link request} may override these values.
+     */
+    get options(): RequesterImplOptions;
+    /**
+     * Applies the given partial configuration.
+     *
+     * @param newOptions
+     */
+    configure(newOptions: PartialDeep<RequesterImplOptions>): void;
+    request(input: RequestInfo | Readonly<URL>, init?: Maybe<RequestInitOptions>, requestOptions?: Maybe<RequestOptions>): Promise<Response>;
+    /**
+     * Executes a single fetch.
+     * If the request is aborted via `requestInfo.init.signal` the promise will be rejected with
+     * the abort reason.
+     *
+     * @throws RequestError
+     * @private
+     */
+    private doRequest;
+    private reportMetricsEntry;
+}
+export declare const nativeFetchRef: import("../global/globalRegistry").GlobalRef<Fetch>;
+//# sourceMappingURL=RequesterImpl.d.ts.map