@amazon/vinyl-util 1.0.0

package/dist/types/ts4.1/util/object/object.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Returns the keys (both property names and symbols) of all own properties.
+ * Unlike `Object.keys`, this will also return non-enumerable properties.
+ * Does not return keys inherited from the object's prototype.
+ *
+ * Implementation details:
+ * If Reflect is supported, Reflect.ownKeys will be used, wrapping in a Set, otherwise
+ * Object.getOwnPropertyNames and Object.getOwnPropertySymbols will be used. This will typically
+ * be equivalent. Proxies may alter the order of keys but platforms that do not support Reflect
+ * will also typically not support Proxies.
+ *
+ * @see Reflect.ownKeys
+ * @see Object.getOwnPropertyNames
+ * @see Object.getOwnPropertySymbols
+ * @param obj
+ * @return Returns a `Set` of the own properties of the target object, including non-enumerable.
+ * The ordering will be: positive numeric indexes in order, strings in insertion order,
+ * symbols in insertion order.
+ */
+export declare function ownKeys<T>(obj: T): Set<keyof T>;
+/**
+ * Returns the prototype chain of the given object.
+ *
+ * Example:
+ * ```
+ * class A {}
+ * class B extends A {}
+ * class C extends B {}
+ * const c = new C()
+ * getPrototypeChain(c) // [c, C.prototype, B.prototype, A.prototype, Object.prototype]
+ * ```
+ * @param obj
+ */
+export declare function getPrototypeChain(obj: any): any[];
+/**
+ * Returns true if the given object represents a plain object and not a class instance.
+ */
+export declare function isPlainObject(value: any): boolean;
+/**
+ * Gets the object's value for the given key if it exists, otherwise sets [key] to
+ * `defaultValue`, returning the newly set value.
+ *
+ * @param object
+ * @param key
+ * @param defaultValue
+ */
+export declare function getOrSetProp<K extends keyof T, T extends object>(object: T, key: K, defaultValue: () => T[K]): T[K];
+/**
+ * Returns true if value is not null. Provides a type guard which can be used in filters.
+ * Example:
+ * [1, null, 2, 3, null, 4].filter(isNonNull) // type number[]
+ * @param value
+ */
+export declare function isNonNull<T>(value: T): value is NonNullable<T>;
+//# sourceMappingURL=object.d.ts.map

package/dist/types/ts4.1/util/object/readonlyType.d.ts

@@ -0,0 +1,100 @@
+import type { Fun } from '../../util/type';
+/**
+ * Recursively marks Objects, Arrays, Maps, Sets, or Dates as read only.
+ * Other non-primitive types will retain their method signatures, potentially exposing mutation
+ * methods.
+ * This type does not represent an immutable value, merely a readonly variant of T.
+ */
+export type ReadonlyDeep<T> = T extends Array<any> ? ReadonlyTupleOrArrayDeep<T> : T extends Fun ? T : T extends Date ? ReadonlyDate : T extends Map<infer K, infer V> ? ReadonlyMapDeep<K, V> : T extends Set<infer V> ? ReadonlySetDeep<ReadonlyDeep<V>> : T extends object ? ReadonlyObjectDeep<T> : T;
+/**
+ * Recursively marks a tuple (up to 5 in length) or an array as read only.
+ */
+export type ReadonlyTupleOrArrayDeep<T extends any[]> = T extends [
+    infer V0
+] ? readonly [
+    ReadonlyDeep<V0>
+] : T extends [
+    infer V0,
+    infer V1
+] ? readonly [
+    ReadonlyDeep<V0>,
+    ReadonlyDeep<V1>
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2
+] ? readonly [
+    ReadonlyDeep<V0>,
+    ReadonlyDeep<V1>,
+    ReadonlyDeep<V2>
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3
+] ? readonly [
+    ReadonlyDeep<V0>,
+    ReadonlyDeep<V1>,
+    ReadonlyDeep<V2>,
+    ReadonlyDeep<V3>
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3,
+    infer V4
+] ? readonly [
+    ReadonlyDeep<V0>,
+    ReadonlyDeep<V1>,
+    ReadonlyDeep<V2>,
+    ReadonlyDeep<V3>,
+    ReadonlyDeep<V4>
+] : ReadonlyArrayDeep<T[number]>;
+/**
+ * A recursively deep read only array. Do not use this directly, use {@link ReadonlyDeep} instead,
+ * which works for Objects and Arrays.
+ */
+export type ReadonlyArrayDeep<E> = readonly ReadonlyDeep<E>[];
+/**
+ * A recursively deep read only object. Do not use this directly, use {@link ReadonlyDeep} instead,
+ * which works for Objects and Arrays.
+ */
+export type ReadonlyObjectDeep<T> = {
+    readonly [P in keyof T]: ReadonlyDeep<T[P]>;
+};
+/**
+ * A shallow, readonly Record.
+ * Note, this differs from Record only by readonly modifiers, as such there is no compile time
+ * safety preventing a ReadonlyRecord from being assigned to a Record type.
+ */
+export type ReadonlyRecord<K extends keyof any, T> = {
+    readonly [P in K]: T;
+};
+/**
+ * A Date type with mutation functions omitted.
+ */
+export type ReadonlyDate = Readonly<Omit<Date, 'setDate' | 'setFullYear' | 'setHours' | 'setMilliseconds' | 'setMinutes' | 'setMonth' | 'setSeconds' | 'setTime' | 'setUTCDate' | 'setUTCFullYear' | 'setUTCHours' | 'setUTCMilliseconds' | 'setUTCMinutes' | 'setUTCMonth' | 'setUTCSeconds'>>;
+/**
+ * A Map type with mutation functions omitted.
+ */
+export type ReadonlyMap<K, V> = Readonly<Omit<Map<K, V>, 'clear' | 'delete' | 'set'>>;
+/**
+ * A deep, readonly map.
+ */
+export type ReadonlyMapDeep<K, V> = ReadonlyMap<K, ReadonlyDeep<V>>;
+/**
+ * A Set type with mutation functions omitted.
+ */
+export type ReadonlySet<E> = Readonly<Omit<Set<E>, 'add' | 'clear' | 'delete'>>;
+/**
+ * A deep, readonly set.
+ */
+export type ReadonlySetDeep<E> = ReadonlySet<ReadonlyDeep<E>>;
+/**
+ * A type alias to ReadonlyDeep that has the additional connotation that the value is constant.
+ *
+ * An immutable object may or may not be frozen, but write access should always consider to be
+ * forbidden.
+ */
+export type Immutable<T> = ReadonlyDeep<T>;
+//# sourceMappingURL=readonlyType.d.ts.map

package/dist/types/ts4.1/util/range/IntersectionRanges.d.ts

@@ -0,0 +1,38 @@
+import type { Range, ReadonlyRanges } from './Ranges';
+import { ReadonlyRangesImpl } from './Ranges';
+import type { Maybe } from '../../util/type';
+export interface IntersectionRangesOptions {
+    /**
+     * If true, only recomputes ranges after a call to `invalidate`.
+     * After `invalidate()`, the ranges are recalculated on next read.
+     * Default: false
+     */
+    readonly useCache?: boolean;
+}
+/**
+ * Takes a list of ranges and computes the intersection ranges on read.
+ */
+export declare class IntersectionRanges extends ReadonlyRangesImpl {
+    private readonly options?;
+    private backingRanges;
+    private valid;
+    private _innerRanges;
+    constructor(
+    /**
+     * The ranges for which to compute the intersection.
+     */
+    innerRanges: readonly ReadonlyRanges[], options?: Maybe<IntersectionRangesOptions>);
+    get innerRanges(): readonly ReadonlyRanges[];
+    set innerRanges(value: readonly ReadonlyRanges[]);
+    get ranges(): ArrayLike<Range>;
+    /**
+     * Flags the intersection ranges as invalid.
+     * This has no effect if options.useCache is not true.
+     */
+    invalidate(): void;
+    /**
+     * Refreshes the backing ranges by computing intersection.
+     */
+    private validate;
+}
+//# sourceMappingURL=IntersectionRanges.d.ts.map

package/dist/types/ts4.1/util/range/Ranges.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Query utilities for a list of ranges.
+ * Ranges are expected to be start, end pairs where no two ranges overlap or touch.
+ * All ranges are in incremental order.
+ */
+export interface ReadonlyRanges extends Iterable<Range> {
+    /**
+     * Returns true if there are zero ranges.
+     */
+    readonly empty: boolean;
+    /**
+     * The ranges array like this reader encapsulates.
+     * Ranges are [start, end] tuples, they will always be ordered, never touch, and never overlap.
+     */
+    readonly ranges: ArrayLike<Range>;
+    /**
+     * Returns the range at the given value, or null if all ranges are outside the given tolerance.
+     * Range values are considered inclusive.
+     * That is, a ReadonlyRanges with `[0, 1]` will return `[0, 1]` for value `1`.
+     *
+     * @param value The value to compare to current ranges.
+     * @param tolerance The tolerance the value may be outside a range and still considered
+     * to be within. Default: 0
+     */
+    getRangeAt(value: number, tolerance?: number): Range | null;
+    /**
+     * Returns the range that includes the entire from-to span, within a given tolerance.
+     *
+     * Range values are considered inclusive.
+     * That is, a `ReadonlyRanges` with `[0, 2]` will return `[0, 2]` for
+     * `getRangeContaining(2, 2)` or `getRangeContaining(0, 0)`.
+     *
+     * `from` does not need to be lesser than `to`.
+     *
+     * @param from
+     * @param to
+     * @param tolerance
+     */
+    getRangeContaining(from: number, to: number, tolerance?: number): Range | null;
+    /**
+     * Returns all ranges where at least part of the range is within the given from-to span.
+     *
+     * `from` does not need to be lesser than `to`.
+     *
+     * @param from
+     * @param to
+     * @param tolerance
+     */
+    getRangesWithin(from: number, to: number, tolerance?: number): Range[];
+    [Symbol.iterator](): IterableIterator<Range>;
+}
+/**
+ * A [start, end] tuple.
+ */
+export type Range = readonly [
+    start: number,
+    end: number
+];
+export declare abstract class ReadonlyRangesImpl implements ReadonlyRanges {
+    /**
+     * An accessor to the backed ranges.
+     * Implementations must provide an ArrayLike<Range> for random-access reading.
+     * This will be called at most once per read operation.
+     */
+    abstract get ranges(): ArrayLike<Range>;
+    get empty(): boolean;
+    getRangeAt(value: number, tolerance?: number): Range | null;
+    getRangeContaining(from: number, to: number, tolerance?: number): Range | null;
+    getRangesWithin(from: number, to: number, tolerance?: number): Range[];
+    [Symbol.iterator](): IterableIterator<Range>;
+    toString(): string;
+}
+/**
+ * Creates a ReadonlyRanges view for the given array of ranges.
+ *
+ * @param value An array of ranges. The ReadonlyRanges reader does not clone
+ * this value and will access this backing array directly.
+ */
+export declare function rangesOf(value: readonly Range[]): ReadonlyRanges;
+/**
+ * A static, empty ranges representation.
+ */
+export declare const emptyRanges: ReadonlyRanges;
+/**
+ * A collection of Range start/end tuples.
+ * When ranges are added they are merged and sorted, making for fast within range checks.
+ */
+export declare class RangesImpl implements ReadonlyRanges {
+    private readonly reader;
+    readonly ranges: Range[];
+    /**
+     * @param ranges The non-normalized ranges to add.
+     * @see #add
+     */
+    constructor(ranges?: readonly Range[]);
+    get empty(): boolean;
+    /**
+     * Adds the given range to this list.
+     * If end is less than start, the range will not be added.
+     * Ranges will be merged when there is overlap or touching. Example,
+     * `add(1, 4); add(2, 5)` results in the final ranges: `[1, 5]`
+     */
+    add(start: number, end: number): void;
+    /**
+     * Removes the given range span from this list.
+     * Ranges partially intersecting will be changed to not include the start-end span.
+     * If start is after end, nothing will be removed.
+     */
+    remove(start: number, end: number): void;
+    /**
+     * Clears all ranges.
+     */
+    clear(): void;
+    getRangeAt(value: number, tolerance?: number): Range | null;
+    getRangeContaining(from: number, to: number, tolerance?: number): Range | null;
+    getRangesWithin(from: number, to: number, tolerance?: number): Range[];
+    clone(): RangesImpl;
+    [Symbol.iterator](): IterableIterator<Range>;
+    toString(): string;
+}
+/**
+ * Returns true if the two ranges intersect.
+ * Adjacent ranges (touching but not overlapping) will not be considered to intersect.
+ */
+export declare function rangeIntersects(rangeA: Range, rangeB: Range): boolean;
+//# sourceMappingURL=Ranges.d.ts.map

package/dist/types/ts4.1/util/range/UnionRanges.d.ts

@@ -0,0 +1,38 @@
+import type { Range, ReadonlyRanges } from './Ranges';
+import { ReadonlyRangesImpl } from './Ranges';
+import type { Maybe } from '../../util/type';
+export interface UnionRangesOptions {
+    /**
+     * If true, only recomputes ranges after a call to `invalidate`.
+     * After `invalidate()`, the ranges are recalculated on next read.
+     * Default: false
+     */
+    readonly useCache?: boolean;
+}
+/**
+ * Takes a list of ranges and computes the union ranges on read.
+ */
+export declare class UnionRanges extends ReadonlyRangesImpl {
+    private readonly options?;
+    private readonly backingRanges;
+    private valid;
+    private _innerRanges;
+    constructor(
+    /**
+     * The ranges for which to compute the union.
+     */
+    innerRanges: readonly ReadonlyRanges[], options?: Maybe<UnionRangesOptions>);
+    get innerRanges(): readonly ReadonlyRanges[];
+    set innerRanges(value: readonly ReadonlyRanges[]);
+    get ranges(): readonly Range[];
+    /**
+     * Flags the union ranges as invalid.
+     * This has no effect if options.useCache is not true.
+     */
+    invalidate(): void;
+    /**
+     * Refreshes the backing ranges.
+     */
+    private validate;
+}
+//# sourceMappingURL=UnionRanges.d.ts.map

package/dist/types/ts4.1/util/range/timeRanges.d.ts

@@ -0,0 +1,14 @@
+import type { Range, ReadonlyRanges } from './Ranges';
+/**
+ * Converts a `TimeRanges` object to an Array for utility purposes.
+ *
+ * @param timeRanges
+ */
+export declare function timeRangesToArray(timeRanges: TimeRanges): Range[];
+/**
+ * Creates a reader for a TimeRanges object for easier querying.
+ *
+ * @param timeRanges
+ */
+export declare function createTimeRangesReader(timeRanges: TimeRanges): ReadonlyRanges;
+//# sourceMappingURL=timeRanges.d.ts.map

package/dist/types/ts4.1/util/serialization/ParseError.d.ts

@@ -0,0 +1,48 @@
+export interface ParseError {
+    /**
+     * The full reason and location.
+     */
+    readonly message: string;
+    /**
+     * The reason for the error.
+     */
+    readonly reason: string;
+    /**
+     * A description of the location the error occurred.
+     */
+    readonly location: string;
+}
+export interface PrintStringPositionOptions {
+    /**
+     * The maximum number of character columns to output.
+     * The number of columns shown will be the min of this value and the number of columns
+     * at the index row.
+     * The default is 60.
+     */
+    maxColumns?: number;
+    /**
+     * The caret indicator.
+     * The caret will be printed on a second row, directly underneath the column index
+     * represents. This may more than one character, where the first character will align
+     * with the index column.
+     * The default value is '^'.
+     */
+    caret?: string;
+    /**
+     * A number between 0 and 1 representing the percentage of trailing to leading characters.
+     * 0 Indicates all trailing, 1 indicates all leading, and 0.5 indicates that the index
+     * column is as close to the middle as possible.
+     * The default value is 0.6.
+     */
+    split?: number;
+}
+/**
+ * Given a string and a position index, gets the row the index represents, displaying the
+ * surrounding characters, with a second row showing a caret indicator pointing at the index.
+ *
+ * @param str
+ * @param index The
+ * @param options Display options
+ */
+export declare function printStringPosition(str: string, index: number, options?: PrintStringPositionOptions): string;
+//# sourceMappingURL=ParseError.d.ts.map

package/dist/types/ts4.1/util/serialization/json.d.ts

@@ -0,0 +1,30 @@
+import type { AnyRecord, Fun, IsAny } from '../../util/type';
+/**
+ * A representation of the conversion the toJson function will apply to make an input JSON compatible.
+ */
+export type Json<T = any> = IsAny<T> extends true ? AnyRecord : unknown extends T ? never : T extends bigint | symbol | Fun ? string : T extends {
+    toJSON(): infer R;
+} ? R : T extends boolean | number | string | null | undefined ? T : T extends Set<infer U> ? Json<U>[] : T extends readonly any[] ? Json<T[number]>[] : {
+    [P in keyof T]: Json<T[P]>;
+};
+/**
+ * Converts a dynamic value to a serializable value.
+ * The value must be either an object with a toJSON function, a primitive, or a plain object
+ * where all enumerable properties map to values supported by this function.
+ * Properties not enumerable will be omitted, properties not serializable will be converted
+ * to strings.
+ * - bigint -> value.toString
+ * - function -> [function <name>]
+ * - symbol -> [symbol <name>]
+ *
+ * Error instances have a special case where non-serializable errors will still have their
+ * name, message, and stack properties serialized.
+ *
+ * Note that this is not intended for use in serializing objects where all values are known;
+ * it's intended to cover the case of reporting or logging an unknown object that may or may not
+ * be serializable.
+ *
+ * @param value
+ */
+export declare function toJson<T>(value: T): Json<T>;
+//# sourceMappingURL=json.d.ts.map

package/dist/types/ts4.1/util/serialization/primitives.d.ts

@@ -0,0 +1,24 @@
+import type { Maybe } from '../../util/type';
+/**
+ * Returns true if the given string is 'true' or '1'
+ *
+ * @param str
+ */
+export declare function parseBoolean(str: Maybe<string>): boolean;
+/**
+ * Returns the toString() value of the given object.
+ *
+ * @param value
+ */
+export declare function stringify(value: any): string;
+/**
+ * Parses a string into an integer.
+ * If the string is nullish, empty, or is not a finite number, returns null.
+ */
+export declare function parseIntSafe(str: Maybe<string>, radix?: number): number | null;
+/**
+ * Parses a string into a number.
+ * If the string is nullish, empty, or is not a finite number, returns null.
+ */
+export declare function parseFloatSafe(str: Maybe<string>): number | null;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/types/ts4.1/util/serialization/stringifyForPrint.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stringifies a value suitable for human-readable messages.
+ *
+ * The value is first run through {@link toJson} which makes it safe for serialization.
+ * (Circular references will become strings, and toJSON serializers will be respected)
+ * The safe json is then stringified, using a JSON.stringify replacer that preserves
+ * representations for NaN, Infinity, undefined, and Symbol.
+ *
+ * @param value Any value.
+ * @param maxLength If provided, will truncate the final string.
+ * @param indicator The truncation indicator.
+ */
+export declare function stringifyForPrint(value: any, maxLength?: number, indicator?: string): string;
+//# sourceMappingURL=stringifyForPrint.d.ts.map

package/dist/types/ts4.1/util/set/set.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns the union of two sets. That is, the unique elements of A and B.
+ *
+ * @param a
+ * @param b
+ * @return Returns a new Set `A ∪ B`
+ */
+export declare function union<T, U>(a: ReadonlySet<T>, b: ReadonlySet<U>): Set<T | U>;
+/**
+ * Returns the set difference of A and B. That is, the elements of A that are not in B.
+ *
+ * @param a
+ * @param b
+ * @return Returns a new Set that is `A \ B`
+ */
+export declare function diff<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): Set<T>;
+//# sourceMappingURL=set.d.ts.map

package/dist/types/ts4.1/util/string/StringReader.d.ts

@@ -0,0 +1,134 @@
+import { ReportableError } from '../../error/ReportableError';
+import type { ParseError } from '../../util/serialization/ParseError';
+import type { Json } from '../../util/serialization/json';
+/**
+ * A cursor on a string that allows for fast, naive parsing.
+ */
+export declare class StringReader {
+    data: string;
+    /**
+     * @param data The string to read.
+     */
+    constructor(data: string);
+    /**
+     * The current cursor.
+     * This should always be between the range 0 and `data.length`
+     */
+    position: number;
+    /**
+     * Returns true if the current {@link position} is less than the source data's length.
+     */
+    hasNext(): boolean;
+    get remaining(): number;
+    get length(): number;
+    /**
+     * Throws a {@link StringParseError} where the location uses {@link printStringPosition} to
+     * show a friendly message indicating the current position.
+     *
+     * @param message
+     * @param offset The offset to add to the current position.
+     */
+    err(message: string, offset?: number): never;
+    /**
+     * Reads and returns the character code at the current position.
+     * To read the next character without advancing the cursor, use {@link peek}
+     *
+     * Note:
+     * This method has no bounds checking; if {@link position} is greater than or equal to
+     * `str.length` then NaN will be returned and {@link position} will still be incremented.
+     *
+     * @see String.charCodeAt
+     */
+    next(): number;
+    /**
+     * Reads characters until the predicate returns false or the data length has been reached.
+     *
+     * @param predicate Given the char code at the cursor index, returns true if the character
+     * should be included in the substring result.
+     * @returns number The start position.
+     */
+    while(predicate: (charCode: number) => boolean): number;
+    /**
+     * Reads characters until the predicate returns true or the string length has been reached.
+     *
+     * @param predicate
+     * @returns number Returns the start index.
+     */
+    until(predicate: (charCode: number) => boolean): number;
+    /**
+     * Reads characters until the given character has been found or the string length has been
+     * reached.
+     *
+     * @param charCode
+     * @return number Returns the start index.
+     */
+    untilChar(charCode: number): number;
+    /**
+     * Reads characters until the given string has been found or the string length has been
+     * reached.
+     *
+     * @param string The string to match
+     * @return number Returns the start index.
+     */
+    untilString(string: string): number;
+    /**
+     * The same as {@link while} except returns the read substring as a result.
+     */
+    substringWhile(predicate: (charCode: number) => boolean): string;
+    /**
+     * The same as {@link until} except returns the read substring as a result.
+     */
+    substringUntil(predicate: (charCode: number) => boolean): string;
+    /**
+     * The same as {@link untilChar} except returns the read substring as a result.
+     */
+    substringUntilChar(charCode: number): string;
+    /**
+     * Reads the substring from the current index with the given length.
+     *
+     * @param length
+     */
+    substr(length: number): string;
+    /**
+     * Reads the expected string from the current position.
+     * If the read string doesn't match the given string, a {@link StringParseError} is thrown.
+     *
+     * @param str The string required to match at the current position.
+     * @param ignoreCase If true, the comparison will be case-insensitive.
+     */
+    read(str: string, ignoreCase?: boolean): string;
+    /**
+     * Reads the expected char code from the current position.
+     * If the read character doesn't match the given character, a {@link StringParseError} is
+     * thrown.
+     *
+     * @param charCode The character code required to match at the current position.
+     */
+    readChar(charCode: number): number;
+    get peek(): number;
+    /**
+     * Reads through all whitespace characters, returning the starting index.
+     */
+    white(): number;
+    /**
+     * If {@link peek} equals the given character code, returns true and advances the index by
+     * one.
+     *
+     * @param charCode
+     */
+    charIf(charCode: number): boolean;
+    /**
+     * If the given string matches the substring at the current position, returns true and advances
+     * the index by the string's length.
+     */
+    stringIf(string: string, ignoreCase?: boolean): boolean;
+}
+export declare class StringParseError extends ReportableError implements ParseError {
+    readonly position: number;
+    readonly reason: string;
+    get [Symbol.toStringTag](): string;
+    readonly location: string;
+    constructor(str: string, position: number, reason: string);
+    toJSON(): Json;
+}
+//# sourceMappingURL=StringReader.d.ts.map