@amazon/vinyl-util 1.0.0

package/dist/types/ts4.7/util/string/string.d.ts

@@ -0,0 +1,130 @@
+import type { Maybe } from '../../util/type';
+import type { ReadonlyRecord } from '../../util/object/readonlyType';
+/**
+ * Substitutes named variable references in a string.
+ *
+ * Example:
+ * ```
+ * substitute('{fruit}, {veg}', { fruit: 'apples', veg: 'carrots' }) // 'apples, carrots'
+ * ```
+ *
+ * @param str The template string.
+ * @param variables A record of variable names to values.
+ * @param pattern A regex whose first capture group is the variable name. Defaults to `{name}`.
+ * @throws IllegalArgumentError if a referenced variable is not defined.
+ */
+export declare function substitute(str: string, variables: Readonly<Record<string, any>>, pattern?: RegExp): string;
+/**
+ * Replaces substitution tokens.
+ *
+ * Each identifier may be suffixed, within the enclosing '$' characters, with an additional format tag for number
+ * padding following the prototype: `%0[width]d`
+ * For example:
+ * 'Segment_$Time%04d$' Where the `Time` property is `42` will have a replacement value of: `Segment_0042`
+ */
+export declare function substituteIdentifiers(str: string, props: ReadonlyRecord<string, string | number>): string;
+/**
+ * Returns true if the character is one of: ' ', '\t', '\n', '\r'
+ *
+ * @param charCode The character code to test
+ */
+export declare function isWhitespaceChar(charCode: number): boolean;
+/**
+ * Predefined general xml entities
+ * https://www.w3.org/TR/2008/REC-xml-20081126/#sec-predefined-ent
+ */
+export declare const predefinedDecodeEntities: ReadonlyMap<string, string>;
+/**
+ * Replaces all specified entities with their mapped representations.
+ * For example (using {@link predefinedDecodeEntities}):
+ * ```
+ * `&lt;Hello to y&apos;all&#33;&gt;` becomes `<Hello to y'all!>`
+ * ```
+ *
+ * @param str
+ * @param namedEntities
+ */
+export declare function decodeEntities(str: string, namedEntities?: ReadonlyMap<string, string>): string;
+/**
+ * Encodes the predefined xml standard entities into their entity names.
+ *
+ * & to &amp;
+ * ' to &apos;
+ * > to &gt;
+ * < to &lt;
+ * " to &quot;
+ *
+ * @param str
+ */
+export declare function encodeEntities(str: string): string;
+/**
+ * Returns true if the two strings are equal, optionally ignoring case.
+ *
+ * @param a
+ * @param b
+ * @param ignoreCase
+ */
+export declare function eqStr(a: string | null, b: string | null, ignoreCase?: boolean): boolean;
+/**
+ * Given a single character string, returns the char code of the first character.
+ *
+ * @param str A single character string from which to get the first code point.
+ */
+export declare function char(str: string): number;
+/**
+ * Returns the substring of string after the last instance of searchString, excluding searchString.
+ * If searchString is not found, the whole string will be returned.
+ *
+ * @param string
+ * @param searchString
+ * @param caseSensitive If true (default) the search will be case-sensitive.
+ */
+export declare function substringAfterLast(string: string, searchString: string, caseSensitive?: boolean): string;
+/**
+ * Returns the substring of string before the first occurrence of searchString, excluding
+ * searchString.
+ * If searchString is not found, the whole string will be returned.
+ *
+ * @param string
+ * @param searchString
+ * @param caseSensitive If true (default) the search will be case-sensitive.
+ */
+export declare function substringBefore(string: string, searchString: string, caseSensitive?: boolean): string;
+/**
+ * Tokenizes a string into lowercase alphanumeric words.
+ *
+ * E.g. `'Amazon Music x86_64'` becomes `['amazon', 'music', 'x86', '64']`
+ *
+ * @param str
+ */
+export declare function tokenizeWords(str: string): string[];
+export declare function toLowerCase<T extends string>(str: T): Lowercase<T>;
+export declare function toUpperCase<T extends string>(str: T): Uppercase<T>;
+/**
+ * If the given string is greater than a max length, truncate the string with an indicator.
+ * Example:
+ * truncate('a very long string', 10) // 'a very ...'
+ *
+ * @param str A nullable string.
+ * @param maxLength
+ * @param indicator The string to indicate there was truncation, default is an ellipses … (U+2026)
+ * @return Returns the truncated string, or the nullish value if str is nullish.
+ */
+export declare function truncate<T extends Maybe<string>>(str: T, maxLength: number, indicator?: string): T | string;
+/**
+ * Converts a string to kebab-case.
+ *
+ * This function transforms camelCase, PascalCase, snake_case, and space-separated
+ * strings into a normalized kebab-case format. It removes non-alphanumeric characters
+ * (excluding hyphens), collapses multiple delimiters, and trims leading/trailing hyphens.
+ *
+ * @example
+ * toKebabCase("HelloWorld")         // "hello-world"
+ * toKebabCase("hello_world test")   // "hello-world-test"
+ * toKebabCase("SomeText123")        // "some-text123"
+ *
+ * @param str - The input string to convert.
+ * @returns The kebab-case version of the input.
+ */
+export declare function toKebabCase(str: string): string;
+//# sourceMappingURL=string.d.ts.map

package/dist/types/ts4.7/util/string/uid.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns a short unique id.
+ * Optimized for performance. (2.1M ops/s ± 0.71%)
+ * The returned value is 7-22 A-Za-z0-9 characters.
+ *
+ * The uniqueness of the returned string is the current timestamp to ms precision plus 2^53-1
+ * possible values.
+ *
+ * The odds of a collision where n is the number of UIDs created within the same millisecond:
+ * 1-((2^53-2)/(2^53-1))^C(n, 2)
+ *
+ * For 1000 UIDs created within the same millisecond the odds of a collision are:
+ * 00.0000000055%, or 1 in 550 billion.
+ */
+export declare function createShortUid(): string;
+/**
+ * @deprecated use createShortUid
+ */
+export declare const createUid: typeof createShortUid;
+//# sourceMappingURL=uid.d.ts.map

package/dist/types/ts4.7/util/type.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Distributes the value types of an array into a union.
+ */
+export type Flatten<T> = T extends readonly any[] ? T[number] : T;
+/**
+ * Property keys of an object that do not map to functions.
+ */
+export type NonFunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends (...args: any) => any ? never : K;
+}[keyof T];
+/**
+ * All primitive types.
+ */
+export type Primitive = bigint | boolean | number | string | symbol | null | undefined;
+/**
+ * An empty object, safer than using `object` type.
+ */
+export type AnyRecord = Record<never, any>;
+/**
+ * never, with a message to help explain the problem.
+ * https://github.com/microsoft/TypeScript/issues/33098
+ */
+export type Never<Message extends string> = [
+    never,
+    Message
+];
+/**
+ * A type representing any type of function.
+ */
+export type Fun = (...args: any[]) => any;
+/**
+ * Enforces that the type represents data that can be serialized via JSON.stringify.
+ */
+export type JsonCompatible<T> = unknown extends T ? never : T extends bigint | symbol | Fun ? never : T extends boolean | number | string | null | undefined | {
+    toJSON(): any;
+} ? T : T extends readonly any[] ? readonly JsonCompatible<T[number]>[] : {
+    [P in keyof T]: JsonCompatible<T[P]>;
+};
+/**
+ * A compile-time check that the given value/array/object is serializable via JSON.stringify.
+ *
+ * A value is serializable if any of these are true:
+ * - It is an object with a toJSON() function
+ * - It is an object with only serializable members.
+ * - It is an array with only serializable elements.
+ * - It is type boolean, string, number, null, or undefined.
+ */
+export declare function jsonCompatible<T>(value: JsonCompatible<T>): T;
+/**
+ * An object whose properties are all optional, and all sub-properties are optional.
+ * Note: does not convert array or tuple elements to Partial.
+ */
+export type PartialDeep<T> = T extends Fun | Primitive ? T : T extends object ? {
+    [P in keyof T]?: PartialDeep<T[P]>;
+} : T;
+/**
+ * Defines specific properties of T that are not required.
+ */
+export type PickPartial<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Possible values `typeof` operator may return.
+ */
+export type Typeof = 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'undefined';
+/**
+ * Given a possible result from `typeof`, provides the type to the matched value.
+ */
+export type FromTypeof<T extends Typeof> = T extends 'bigint' ? bigint : T extends 'boolean' ? boolean : T extends 'function' ? Fun : T extends 'number' ? number : T extends 'object' ? object | null : T extends 'string' ? string : T extends 'symbol' ? symbol : T extends 'undefined' ? undefined : any;
+/**
+ * Extracts values from T which extends type U.
+ */
+export type ExtractValues<T, U> = Pick<T, {
+    [P in keyof T]: T[P] extends U ? P : never;
+}[keyof T]>;
+/**
+ * Excludes values from T which extends type U.
+ */
+export type ExcludeValues<T, U> = Pick<T, {
+    [P in keyof T]: T[P] extends U ? never : P;
+}[keyof T]>;
+export type Maybe<T> = T | undefined | null;
+/**
+ * Infers the element type from an Array type.
+ */
+export type ElementType<T extends readonly any[]> = T extends ReadonlyArray<infer E> ? E : never;
+/**
+ * Infers the element type from a Set type.
+ */
+export type SetElementType<T extends ReadonlySet<any>> = T extends ReadonlySet<infer E> ? E : never;
+/**
+ * Enforces type T to be in an invariant position.
+ * For example `Invariant<Square>` cannot be assigned to type `Invariant<Polygon>` or vice versa.
+ *
+ * This should be used when an interface with type parameter T needs strict invariance in addition to what the
+ * compiler can infer from use.
+ *
+ * {@link https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)}
+ */
+export type Invariant<T> = T & Required<T> & ((input: T & Required<T>) => T & Required<T>);
+export declare function invariant<T>(): Invariant<T>;
+/**
+ * Enforces type T to be in a covariant position.
+ * For example `Invariant<Square>` can be assigned to type `Invariant<Polygon>` but not vice versa.
+ *
+ * This should be used when an interface with type parameter T does not explicitly use T in an
+ * output position, but the interface implies `out T`.
+ */
+export type Covariant<T> = () => T;
+export declare function covariant<T>(): Covariant<T>;
+/**
+ * Enforces type T to be in a covariant position.
+ * For example `Invariant<Polygon>` can be assigned to type `Invariant<Square>` but not vice versa.
+ *
+ * This should be used when an interface with type parameter T does not explicitly use T in an
+ * input position, but the interface implies `in T`.
+ */
+export type Contravariant<T> = (input: T) => void;
+export declare function contravariant<T>(): Contravariant<T>;
+/**
+ * A type which may either be a direct instance of T or a promise that resolves to T.
+ */
+export type MaybePromise<T> = PromiseLike<T> | T;
+/**
+ * Deeply excludes all keys from T extending K.
+ */
+export type OmitDeep<T, K extends keyof any> = Omit<{
+    [P in keyof T]: T[P] extends Primitive ? T[P] : OmitDeep<T[P], K>;
+}, K>;
+/**
+ * Make properties of T extending K optional.
+ */
+export type Optional<T, K extends keyof T> = Partial<Pick<T, K>> & Omit<T, K>;
+/**
+ * Make properties of T extending K optional, recursively.
+ */
+export type OptionalDeep<T, K extends keyof any> = Optional<{
+    [P in keyof T]: T[P] extends Primitive ? T[P] : OptionalDeep<T[P], K>;
+}, K & keyof T>;
+/**
+ * true if T extends never, otherwise false
+ */
+export type IsNever<T> = [
+    T
+] extends [
+    never
+] ? true : false;
+/**
+ * true if T extends any, otherwise false
+ */
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * Determines whether a property `P` of object type `U` is declared as optional.
+ *
+ * This checks whether the `{}` type (an empty object) is assignable to
+ * `Pick<U, P>`. In TypeScript, this is true only when `P` is marked optional
+ * using the `?` modifier in the type definition.
+ *
+ * Importantly, this detects *actual optionality* rather than checking whether
+ * the property's type includes `undefined`. For example:
+ *
+ * ```ts
+ * type A = { x?: string };               // optional
+ * type B = { x: string | undefined };    // required but allows undefined
+ *
+ * IsPropertyOptional<A, "x"> // true
+ * IsPropertyOptional<B, "x"> // false
+ * ```
+ *
+ * @template U - The object type containing the property.
+ * @template P - The key of the property to test.
+ * @returns `true` if `P` is an optional property, otherwise `false`.
+ */
+export type IsPropertyOptional<U, P extends keyof U> = AnyRecord extends Pick<U, P> ? true : false;
+//# sourceMappingURL=type.d.ts.map

package/dist/types/ts4.7/util/url/resolveUrl.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolves a relative URI against a base URL using string manipulation,
+ * avoiding the overhead of constructing `URL` objects.
+ *
+ * Handles the same cases as `new URL(relative, base)`:
+ * - Absolute URIs (with scheme) are returned as-is.
+ * - Protocol-relative URIs (`//host/path`) inherit the base scheme.
+ * - Absolute paths (`/path`) replace the base path.
+ * - Relative paths are resolved against the base directory.
+ *
+ * @param relative The relative (or absolute) URI to resolve.
+ * @param base The base URL string to resolve against.
+ * @returns A resolved absolute URL string.
+ */
+export declare function resolveUrl(relative: string, base: string): string;
+/**
+ * Extracts the hostname from an absolute URL string.
+ *
+ * @param url An absolute URL string (e.g. `https://example.com:8080/path`).
+ * @returns The hostname (e.g. `example.com`).
+ */
+export declare function getHostname(url: string): string;
+//# sourceMappingURL=resolveUrl.d.ts.map

package/docs/EVENTS.md

@@ -0,0 +1,187 @@
+# Events
+
+Amazon Vinyl uses a statically-typed observer pattern. Event hosts describe the
+events they emit using an event map type. Observers may subscribe to those
+events, and unsubscribe using the returned unsubscribe handles.
+
+An event host is not tied to the DOM, it may be used anywhere an observer
+pattern is needed and will work in both Node and Browser environments.
+
+## Usage
+
+To subscribe to an event from an event host, use the `on` function, which
+returns a function that, when invoked, removes the listener.
+
+## Example:
+
+```typescript
+import { EventHostImpl } from '@amazon/vinyl-util'
+
+export type CountEvent = {
+    readonly value: number
+}
+
+export type CounterEventMap = {
+    readonly count: CountEvent
+}
+
+export class Counter extends EventHostImpl<CounterEventMap> {
+    private _count = 0
+
+    increment() {
+        this._count++
+        this.dispatch('count', { value: this._count })
+    }
+}
+
+const counter = new Counter()
+const sub = counter.on('count', (event) => {
+    console.log('count event:', event.value)
+})
+
+counter.increment() // count event: 1
+counter.increment() // count event: 2
+counter.increment() // count event: 3
+
+sub() // remove listener
+
+counter.increment() // event not observed
+```
+
+## Once Listeners
+
+```typescript
+const counter = new Counter()
+counter.on(
+    'count',
+    (event) => {
+        console.log('count event:', event.count)
+    },
+    { once: true }
+)
+
+counter.increment() // count event: 1
+counter.increment() // event not observed
+```
+
+## ReadonlyEventHost
+
+When typing interfaces, `ReadonlyEventHost<T>` may be used to expose a readonly
+interface to observers. This allows event maps to have correct variance and
+enable TypeScript to ensure events are not incorrectly dispatched from outside
+systems.
+
+## Cleanup
+
+When an event host is disposed, all listeners will be removed. To ensure good
+garbage collection, follow an ownership principle. When adding listeners to a
+provided dependency, added listeners must be paired with an unsubscribe.
+
+## EventTarget
+
+EventTarget objects may be wrapped using `DomEventHost`. Using DomEventHost
+allows applications to use a consistent observer pattern, shared utilities, and
+easier cleanup.
+
+TypeScript provides event map types that may be used to statically type an
+EventTarget's events.
+
+```typescript
+import { DomEventHost } from '@amazon/vinyl-util'
+
+const div = document.querySelector('div')
+const divEvents = new DomEventHost<HTMLElementEventMap>(div)
+
+divEvents.on('click', (event) => console.log('clicked'))
+```
+
+When subscribing to a DomEventHost, additional options are available such as
+'passive', or 'capture'.
+
+```typescript
+divEvents.on('wheel', (event) => console.log('wheel'), {
+    passive: true,
+    capture: true,
+})
+```
+
+Note: The event option 'signal' is not supported, to unsubscribe to many
+handlers at once, create a disposer.
+
+E.g.
+
+```typescript
+import { createDisposer } from '@amazon/vinyl-util'
+
+const { add, dispose } = createDisposer()
+
+add(divEvents.on('click', (event) => console.log('click')))
+add(divEvents.on('wheel', (event) => console.log('wheel')))
+
+dispose() // removes all handlers added
+```
+
+## Redispatching Events
+
+To redispatch events, use the `redispatchEvents` utility method.
+
+Example:
+
+```typescript
+import { EventHostImpl } from '@amazon/vinyl-util'
+
+class MyWrapper extends EventHostImpl<HTMLElementEventMap> {
+    private readonly divEvents = new DomEventHost<HTMLElementEventMap>(div)
+
+    constructor() {
+        super()
+        redispatchEvents(this, this.divEvents, [
+            'click',
+            'mouseMove',
+            'touchStart',
+            'touchEnd',
+        ])
+    }
+}
+```
+
+## Extending EventHost Implementations
+
+To extend an EventHost implementation, adding new events to a subclass, certain
+functions on EventHostImpl must be overridden.
+
+_note_ This scenario is in need of improvement. To ensure full static checking
+for events and event types, method overrides when extending EventHostImpl is
+necessary, however the ergonomics can be improved.
+
+```typescript
+import type { EmptyObject, EventHost } from '@amazon/vinyl-util'
+
+export type CounterWithResetEventMap = CounterEventMap & {
+    readonly reset: EmptyObject
+}
+
+class CounterWithReset
+    extends Counter
+    implements EventHost<CounterWithResetEventMap>
+{
+    hasListeners(type: keyof CounterWithResetEventMap): boolean {
+        return super.hasListeners(type as any)
+    }
+
+    on<K extends keyof CounterWithResetEventMap>(
+        type: K,
+        handler: EventHandler<CounterWithResetEventMap[K]>,
+        options?: SignalOptions
+    ): Unsubscribe {
+        return super.on(type as any, handler, options)
+    }
+
+    dispatch<K extends keyof CounterWithResetEventMap>(
+        type: K,
+        event: CounterWithResetEventMap[K]
+    ) {
+        super.dispatch(type as any, event)
+    }
+}
+```

package/docs/GLOBALS.md

@@ -0,0 +1,45 @@
+# Globals
+
+Amazon Vinyl has a registry of a select few global references.
+
+Global state is limited to that which is scoped to the window, such as the
+networking layer and logging.
+
+To override a global reference, before the reference is first used (that is,
+before the first player is created or first utility method called), set an
+override via `set`. Example:
+
+```typescript
+import { requesterWithRetryRef } from '@amazon/vinyl-util'
+
+// Overridden until the global registry is reset:
+requesterWithRetryRef.set(() => {
+    return createRequester({
+        retryOptions: RetryStrategy.NO_RETRIES,
+    })
+})
+```
+
+Global references are constructed upon first use, and will throw if a cyclic
+dependency is detected.
+
+All global state may be cleared and reset with `globalRegistry.reset`. For
+example if an application has a dormant state, all players can be disposed and
+global state reset to free memory. After a reset, overrides will be removed and
+can be reset with their override references.
+
+Example:
+
+```typescript
+import { globalRef, getGlobalRegistry } from '@amazon/vinyl-util'
+
+const globalRef = globalRef(() => 1)
+
+const override = globalRef.set(() => 2)
+
+globalRef.value // 2
+
+getGlobalRegistry().reset() // Overrides cleared
+override.initialize() // Resets the initializer
+globalRef.value // 2
+```