@prozilla-os/shared 1.2.1 → 1.3.0

package/dist/main.d.ts

@@ -1,4 +1,12 @@
+/**
+ * ANSI escape codes.
+ *
+ * @see [ANSI escape code - Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code).
+ */
 export declare const ANSI: {
+    /**
+     * Foreground colors.
+     */
     fg: {
         black: string;
         red: string;
@@ -9,63 +17,578 @@ export declare const ANSI: {
         cyan: string;
         white: string;
     };
-    bg: {};
+    /**
+     * Background colors.
+     */
+    bg: {
+        black: string;
+        red: string;
+        green: string;
+        yellow: string;
+        blue: string;
+        magenta: string;
+        cyan: string;
+        white: string;
+    };
+    /**
+     * Screen buffer and clearing controls.
+     */
+    screen: {
+        enterAltBuffer: string;
+        exitAltBuffer: string;
+        clear: string;
+        home: string;
+    };
+    /**
+     * Decorations.
+     */
     decoration: {
         dim: string;
         bold: string;
+        underline: string;
     };
     reset: string;
 };
 
+/**
+ * Provides utility functions for wrapping text in ANSI escape codes.
+ *
+ * @see {@link ANSI}
+ * @hideconstructor
+ */
+export declare class Ansi {
+    #private;
+    /**
+     * Makes text black using {@link ANSI.fg.black}.
+     */
+    static black(text: string): string;
+    /**
+     * Makes text red using {@link ANSI.fg.red}.
+     */
+    static red(text: string): string;
+    /**
+     * Makes text green using {@link ANSI.fg.green}.
+     */
+    static green(text: string): string;
+    /**
+     * Makes text yellow using {@link ANSI.fg.yellow}.
+     */
+    static yellow(text: string): string;
+    /**
+     * Makes text blue using {@link ANSI.fg.blue}.
+     */
+    static blue(text: string): string;
+    /**
+     * Makes text magenta using {@link ANSI.fg.magenta}.
+     */
+    static magenta(text: string): string;
+    /**
+     * Makes text cyan using {@link ANSI.fg.cyan}.
+     */
+    static cyan(text: string): string;
+    /**
+     * Makes text white using {@link ANSI.fg.white}.
+     */
+    static white(text: string): string;
+    /**
+     * Makes text bold using {@link ANSI.decoration.bold}.
+     */
+    static bold(text: string): string;
+    /**
+     * Makes text dim using {@link ANSI.decoration.dim}.
+     */
+    static dim(text: string): string;
+    /**
+     * Removes all ANSI escape sequences.
+     */
+    static strip(text: string): string;
+    /**
+     * Removes ANSI escape sequences for colors and background colors (SGR).
+     */
+    static stripColors(text: string): string;
+}
+
+/**
+ * A function that handles an event asynchronously.
+ * @typeParam T - A record of all events.
+ * @typeParam K - The event this function handles.
+ */
+export declare type AsyncListener<T extends Record<keyof T, unknown[]>, K extends keyof T> = (...args: T[K]) => Promise<void>;
+
+declare function bold(text: string): string;
+
+/**
+ * Clamps a value between an upper and lower bound.
+ * @param value - The value to clamp.
+ * @param min - The lower bound.
+ * @param max - The upper bound.
+ * @returns The clamped value.
+ */
 export declare function clamp(value: number, min: number, max: number): number;
 
-export declare class EventEmitter<EventMap extends EventNamesMap> {
+declare function code(text: string): string;
+
+declare function codeBlock(text: string): string;
+
+/**
+ * A simple event emitter.
+ * @typeParam T - A record of all events.
+ */
+export declare class EventEmitter<T extends Record<keyof T, unknown[]>> {
     #private;
-    static EVENT_NAMES: EventNamesMap;
     /**
-     * Add event listener for an event
+     * Starts listening to an event.
+     * @param event - The event to listen to.
+     * @param listener - The function to call when the event is emitted.
+     * @returns The listener.
      */
-    on<Key extends keyof EventMap>(eventName: Key, callback: Listener): Listener;
+    on<K extends keyof T>(event: K, listener: Listener<T, K>): Listener<T, K>;
     /**
-     * Remove event listener for an event
+     * Registers an event listener that is automatically removed when called.
+     * @param event - The event to listen to.
+     * @param listener - The function to call once the event is emitted.
+     * @returns The wrapped listener.
      */
-    off<Key extends keyof EventMap>(eventName: Key, callback: Listener): void;
+    once<K extends keyof T>(event: K, listener: Listener<T, K>): Listener<T, K>;
     /**
-     * Dispatch event
+     * Starts listening to an event.
+     * @param event - The event to listen to.
+     * @param listener - The function to call when the event is emitted.
+     * @returns The wrapped listener.
      */
-    emit<Key extends keyof EventMap>(eventName: Key, data?: unknown): void;
+    onAsync<K extends keyof T>(event: K, listener: AsyncListener<T, K>, onRejected?: Parameters<Promise<void>["catch"]>[0]): Listener<T, K>;
+    /**
+     * Removes an event listener.
+     * @param event - The event to remove the listener from.
+     * @param listener - The listener to remove.
+     */
+    off<K extends keyof T>(event: K, listener: Listener<T, K>): void;
+    /**
+     * Emits an event to all its listeners.
+     * @param event - The event to emit.
+     * @param args - The arguments to pass to the listeners.
+     */
+    emit<K extends keyof T>(event: K, ...args: T[K]): void;
 }
 
-export declare type EventNamesMap = Record<string, string>;
+/**
+ * Formats time relative to now.
+ * @param date - The date.
+ * @param maxLength - The maximum amount of units, e.g.: 3 => years, months, days.
+ */
+export declare function formatRelativeTime(date: Date, maxLength?: number, allowAffixes?: boolean): string;
+
+/**
+ * Applies a format to a string.
+ * @param text - The text to format.
+ * @returns The formatted text.
+ */
+export declare type Formatter = (text: string) => string;
 
 /**
- * Format a time relative to now
- * @param date - The date
- * @param maxLength - The maximum amount of units, e.g.: 3 => years, months, days
+ * Formats time in a human-readable format.
+ * @param time - Time in milliseconds.
+ * @param maxLength - The maximum amount of units, e.g.: 3 => years, months, days.
  */
-export declare function formatRelativeTime(date: Date, maxLength: number | undefined, allowAffixes: boolean): string;
+export declare function formatTime(time: number, maxLength?: number, allowAffixes?: boolean): string;
 
 /**
- * Format a time
- * @param time - Time in milliseconds
- * @param maxLength - The maximum amount of units, e.g.: 3 => years, months, days
+ * Returns the longest common prefix from a list of strings.
  */
-export declare function formatTime(time: number, maxLength: number | undefined, allowAffixes: boolean): string;
+export declare function getLongestCommonPrefix(strings: string[]): string;
+
+declare function heading1(text: string): string;
+
+declare function heading2(text: string): string;
+
+declare function heading3(text: string): string;
 
-export declare function isValidInteger(number: number | string): number | boolean;
+declare function heading4(text: string): string;
 
-export declare type Listener = (data: unknown) => void;
+declare function heading5(text: string): string;
 
+declare function heading6(text: string): string;
+
+declare function horizontalRule(): string;
+
+/**
+ * Checks if `input` is a valid integer.
+ */
+export declare function isValidInteger(input: number | string): boolean;
+
+/**
+ * Checks if `input` is a valid number.
+ */
+export declare function isValidNumber(input: number | string): boolean;
+
+declare function italic(text: string): string;
+
+declare function link(label: string, url: string): string;
+
+/**
+ * A function that handles an event.
+ * @typeParam T - A record of all events.
+ * @typeParam K - The event this function handles.
+ */
+export declare type Listener<T extends Record<keyof T, unknown[]>, K extends keyof T> = (...args: T[K]) => void;
+
+/**
+ * A simple wrapper for {@link console} that logs formatted text and supports log levels.
+ */
+export declare class Logger {
+    #private;
+    /**
+     * The minimum log level or an array of log levels to enable.
+     *
+     * `undefined` enables all log levels. An array enables all log levels in that array. A single level enables that log level and the ones above.
+     * @default LogLevel.Debug
+     */
+    level?: LogLevel | LogLevel[];
+    /**
+     * The current level of indentation.
+     * @default 0
+     */
+    indent: number;
+    /**
+     * The string to use for indentation.
+     * @default "\t"
+     */
+    indentString?: string;
+    /**
+     * The function to use when highlighting text.
+     * @default Ansi.cyan
+     * @see {@link Ansi.cyan}
+     */
+    highlight: Formatter;
+    /**
+     * The function to use when emphasizing text.
+     * @default Ansi.bold
+     * @see {@link Ansi.bold}
+     */
+    emphasize: Formatter;
+    /**
+     * The prefixes to prepend to logs.
+     * @default {
+     [LogLevel.Info]: Ansi.cyan("[info]"),
+     [LogLevel.Success]: Ansi.green("[success]"),
+     [LogLevel.Warning]: Ansi.yellow("[warning]"),
+     [LogLevel.Error]: Ansi.red("[error]"),
+     }
+     */
+    prefix: {
+        [key in LogLevel | "global"]?: string;
+    };
+    constructor(options?: {
+        /** {@inheritDoc Logger.level}. */
+        level?: Logger["level"];
+        /**
+         * The prefix(es) to prepend to logs.
+         *
+         * Does not override default prefixes unless specified.
+         */
+        prefix?: Logger["prefix"] | string;
+    });
+    /**
+     * @param level - The minimum log level.
+     */
+    constructor(level: LogLevel);
+    /**
+     * @param levels - The log levels to enable.
+     */
+    constructor(levels: LogLevel[]);
+    /**
+     * Resets all properties to their default values.
+     */
+    reset(): this;
+    /**
+     * Calls a function while the level of indentation is increased.
+     *
+     * Increases the level of indentation, then calls the function and finally restores the indentation.
+     * @param callback - The function to call.
+     * @param indentation - The amount of indentation to use.
+     */
+    indented(callback: (this: undefined) => void, indentation?: number): this;
+    /**
+     * Logs every line while the level of indentation is increased.
+     *
+     * Increases the level of indentation, then logs every line and finally restores the indentation.
+     * @param lines - The lines to log.
+     * @param indentation - The amount of indentation to use.
+     * @param level - The log level.
+     */
+    indented(lines: unknown[], indentation?: number, level?: LogLevel): this;
+    /**
+     * Logs a message while the level of indentation is increased.
+     *
+     * Increases the level of indentation, then logs the message and finally restores the indentation.
+     * @param message - The message to log.
+     * @param indentation - The amount of indentation to use.
+     * @param level - The log level.
+     */
+    indented(message: unknown, indentation?: number, level?: LogLevel): this;
+    /**
+     * Increases the level of indentation.
+     * @param amount - The amount to increase the level of indentation with.
+     */
+    tab(amount?: number): this;
+    /**
+     * Decreases the level of indentation.
+     * @param amount - The amount to decrease the level of indentation with.
+     */
+    shiftTab(amount?: number): this;
+    /**
+     * Sets the prefix to prepend to all logs.
+     * @param prefix - The prefix to use.
+     */
+    setPrefix(prefix: string): this;
+    /**
+     * Sets the prefixes to prepend to logs.
+     *
+     * Will override any existing prefixes.
+     * @param prefixes - The prefixes to use.
+     */
+    setPrefix(prefixes: Logger["prefix"]): this;
+    /**
+     * Sets the prefix to prepend to logs at a given log level.
+     * @param level - The log level.
+     * @param prefix - The prefix to use.
+     */
+    setPrefix(level: LogLevel, prefix: string): this;
+    /**
+     * Logs an info message about a URL being fetched.
+     * @param url - The URL being fetched.
+     */
+    fetching(url: string): this;
+    /**
+     * Logs an info message that implies a pending state.
+     * @param message - The status message.
+     */
+    pending(message: string): this;
+    /**
+     * Logs an error message.
+     * @param message - The error message or reason.
+     * @param details - The details of the error message.
+     */
+    error(message: unknown, ...details: unknown[]): this;
+    /**
+     * Logs a warning message.
+     * @param message - The warning message.
+     * @param details - The details of the warning message.
+     */
+    warn(message: string, ...details: unknown[]): this;
+    /**
+     * Logs a success message.
+     * @param message - The success message.
+     * @param details - The details of the success message.
+     */
+    success(message: string, ...details: unknown[]): this;
+    /**
+     * Logs an info message.
+     * @param message - The info message.
+     * @param details - The details of the info message.
+     */
+    info(message: string, ...details: unknown[]): this;
+    /**
+     * Logs a status message.
+     * @param message - The status message.
+     * @param details - The details of the status message.
+     * @param level - The log level.
+     */
+    statusMessage(message: string, details: unknown[], level?: LogLevel): this;
+    /**
+     * Logs the amount of errors and warnings that have been logged since the previous call to this function or the creation of this logger.
+     */
+    summary(): this;
+    /**
+     * Logs a labeled parameter.
+     *
+     * The value is emphasized using {@link emphasize}.
+     * @param label - The label of the parameter.
+     * @param value - The value of the parameter.
+     * @param level - The log level.
+     */
+    parameter(label: string, value: unknown, level?: LogLevel): this;
+    /**
+     * Logs properties as a list of key-value pairs.
+     * @param properties - The properties to log.
+     * @param level - The log level.
+     * @see {@link value()}
+     */
+    properties(properties: Record<string, unknown>, level?: LogLevel): this;
+    /**
+     * Logs a labeled value.
+     *
+     * The value is highlighted using {@link highlight}.
+     * @param label - The label of the value.
+     * @param value - The value.
+     * @param level - The log level.
+     */
+    value(label: string, value: unknown, level?: LogLevel): this;
+    /**
+     * Logs emphasized text.
+     * @param text - The text to log.
+     * @param level - The log level.
+     */
+    emphasized(text: string, level?: LogLevel): this;
+    /**
+     * Logs highlighted text.
+     * @param text - The text to log.
+     * @param level - The log level.
+     */
+    highlighted(text: string, level?: LogLevel): this;
+    /**
+     * Logs each item on a new line.
+     * @param lines - The items to log.
+     * @param level - The log level.
+     */
+    lines(lines: unknown[], level?: LogLevel): this;
+    /**
+     * Logs a message.
+     * @param message - The message to log.
+     * @param level - The log level.
+     */
+    log(message: unknown, level?: LogLevel): this;
+    /**
+     * Logs text using this logger's format.
+     * @param text - The text to log.
+     * @param level - The log level.
+     */
+    text(text: string, level?: LogLevel): this;
+    /**
+     * Logs an newline character.
+     */
+    newLine(): this;
+    /**
+     * Checks if the given log level is enabled.
+     * @param level - The log level to check.
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    /**
+     * Formats text using this logger's formatting properties.
+     * @param text - The text to format.
+     */
+    format(text: string): string;
+    /**
+     * Prepends a prefix to text.
+     * @param text - The text to apply the prefix to.
+     * @param level - The log level.
+     */
+    applyPrefix(text: string, level?: LogLevel): string;
+}
+
+export declare enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Success = 2,
+    Warning = 3,
+    Error = 4
+}
+
+export declare namespace Markdown {
+    export {
+        heading1,
+        heading2,
+        heading3,
+        heading4,
+        heading5,
+        heading6,
+        bold,
+        italic,
+        code,
+        codeBlock,
+        strikethrough,
+        link,
+        quote,
+        horizontalRule
+    }
+}
+
+/**
+ * Converts a string to a boolean.
+ * @param input - The string to parse.
+ */
 export declare function parseBool(input: string): boolean;
 
+export declare function parseOptionalFloat(input?: string, defaultValue?: number): number;
+
+export declare function parseOptionalInteger(input?: string, defaultValue?: number): number;
+
+declare function quote(text: string): string;
+
+/**
+ * Returns a random item from an array.
+ */
 export declare function randomFromArray<Type>(array: Type[]): Type;
 
+/**
+ * Returns a random value inside a range.
+ * @param min - The lower bound.
+ * @param max - The upper bound.
+ */
 export declare function randomRange(min: number, max: number): number;
 
+/**
+ * Removes all duplicate items from an array.
+ */
 export declare function removeDuplicatesFromArray<Type>(array: Type[]): Type[];
 
+/**
+ * Removes an item from an array.
+ * @param item - The item to remove.
+ */
 export declare function removeFromArray<Type>(item: Type, array: Type[]): void;
 
-export declare function round(value: number, precision: number): number;
+/**
+ * Rounds a value.
+ * @param value - The value to round.
+ * @param precision - The precision to round with.
+ */
+export declare function round(value: number, precision?: number): number;
+
+declare function strikethrough(text: string): string;
+
+export declare class Vector2 {
+    x: number;
+    y: number;
+    constructor(xy: number);
+    constructor(x: number, y?: number);
+    static get ZERO(): Vector2;
+    get clone(): Vector2;
+    get magnitude(): number;
+    setX(x: number): this;
+    setY(y: number): this;
+    set(x: number, y: number): this;
+    round(): this;
+    normalize(): this;
+    scale(scalar: number): this;
+    getDistanceSquared(x: number, y?: number): number;
+    getDistanceSquared(vector2: Vector2): number;
+    getDistance(x: number, y?: number): number;
+    getDistance(vector2: Vector2): number;
+    add(x: number, y?: number): this;
+    add(vector2: Vector2): this;
+    subtract(x: number, y?: number): this;
+    subtract(vector2: Vector2): this;
+    multiply(x: number, y?: number): this;
+    multiply(vector2: Vector2): this;
+    divide(x: number, y?: number): this;
+    divide(vector2: Vector2): this;
+    lerp(vector2: Vector2, t: number): this;
+    static sum(vector2A: Vector2, vector2B: Vector2): Vector2;
+    static difference(vector2A: Vector2, vector2B: Vector2): Vector2;
+    static product(vector2A: Vector2, vector2B: Vector2): Vector2;
+    static division(vector2A: Vector2, vector2B: Vector2): Vector2;
+    static scale(vector2: Vector2, scalar: number): Vector2;
+    static normalize(vector2: Vector2): Vector2;
+    static lerp(vector2A: Vector2, vector2B: Vector2, t: number): Vector2;
+    static from({ x, y }: {
+        x: number;
+        y: number;
+    }): Vector2;
+    static parseVector(x: number | Vector2, y?: number): {
+        x: number;
+        y: number;
+    };
+}
 
 export { }