@amazon-devices/vega-carousel 0.1.3

package/dist/utils/CarouselLogger.d.ts

@@ -0,0 +1,295 @@
+import { AnyValue } from './HelperTypes';
+/**
+ * Convenient type encapsulating all supported log levels.
+ *
+ * @internal
+ */
+export type LogLevelType = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'log';
+/**
+ * Helper type that encapsulates all types that are considered a "valid message"
+ * by the {@link Logger} class.
+ *
+ * When used as a string, the variable of this type is the message. When used as
+ * an array of strings, a _space character_ will join all the array elements to
+ * form the message. When used as a function, the function will be called to
+ * resolve the message string.
+ *
+ * @internal
+ */
+export type LogMessage = string | Array<string> | (() => string);
+/**
+ * Helper class to log messages to the {@link Console} using a `printf` style
+ * syntax for string interpolation, and a _Robot-like_ API.
+ *
+ * When using the `printf`-like interpolation, you'll need to use the syntax
+ * explained on the {@link Logger.format} function.
+ *
+ * @see {@link Logger.format}
+ * @internal
+ */
+export declare class Logger {
+    /**
+     * The string to be prepended to all log message logged with this utility
+     * class.
+     * @private
+     */
+    readonly tag: string;
+    /**
+     * Attribute that holds static information about an instance of `Logger`.
+     * @private
+     */
+    private readonly levelInfo;
+    constructor(tag: string);
+    /**
+     * Function to interpolate values from the variadic argument `args` into the
+     * given `message`.
+     *
+     * To embed one of the variadic arguments into the string, use the `{N}`
+     * syntax, where `N` is the positional index of the arg.
+     *
+     * You can also repeat the usage of an arg by repeating its `{N}` placeholder.
+     *
+     * @param {string} message The string message to be interpolated with values
+     *        from the given `args`.
+     * @param {...any} args A variadic list of arguments to be used to interpolate
+     *        matches of `{N}` in the given `message`.
+     * @private
+     */
+    private static format;
+    /**
+     * Helper function to create the log prefix for a `tag` and a log `level`.
+     *
+     * This function is mainly used in tests to help us build log messages that
+     * mach the real log output.
+     *
+     * @param {string} tag An arbitrary string to go at the start of the log
+     *        message. Inside a {@link Logger} class, this will be
+     *        {@link Logger.tag}.
+     * @param {LogLevelType?} level An optional string representing one of the
+     *        supported logs.
+     */
+    static buildLogPrefix(tag: string, level?: LogLevelType): string;
+    /**
+     * Helper function used to allow us to test this class. When running a test,
+     * the function returned by this wrapper is a simple pass-through of the log
+     * message.
+     *
+     * @param {(text: string) => string} wrapper The function that will wrap the
+     *        log message before sending it to the console.
+     *
+     * @return {(text: string) => string} Returns the given message back to the
+     *         caller, unless it is running in a test environment, which, in such
+     *         a case, it will return a simple pass-through function
+     *         (`msg => mst`).
+     * @private
+     */
+    private static logWrapper;
+    /**
+     * Main function to perform the console log.
+     *
+     * This function also augments each log message to the appropriate color for
+     * its level.
+     *
+     * @param {boolean} useRawConsole Flag indicating if the message being logged
+     *        is using the `printf`-like syntax or not.
+     * @param {LogLevelType} level The log level to use to output the given
+     *        `message`.
+     * @param {LogMessage} message The message to be sent to the console output.
+     *        If this argument is given as an array of strings, a space character
+     *        will _join_ each entry in the array to form the final message. If it
+     *        is a function, the function will be called to resolve the string.
+     * @param {...any} args A variadic list of arguments to be used to interpolate
+     *        matches of `{N}` in the given `message`.
+     * @private
+     */
+    private consoleLog;
+    /**
+     * Logs a message to the {@link Console.trace} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link traceRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link traceRaw}
+     * @see {@link t}
+     */
+    trace(msg: LogMessage, ...args: AnyValue[]): void;
+    /**
+     * Logs a message to the {@link Console.trace} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link trace}
+     * or {@link t} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.trace} function.
+     *
+     * @see {@link trace}
+     * @see {@link t}
+     */
+    traceRaw(msg: LogMessage, ...args: AnyValue[]): void;
+    /** This function is just an alias to the {@link trace} function. */
+    t: (msg: LogMessage, ...args: AnyValue[]) => void;
+    /**
+     * Logs a message to the {@link Console.debug} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link debugRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link debugRaw}
+     * @see {@link d}
+     */
+    debug(msg: LogMessage, ...args: AnyValue[]): void;
+    /**
+     * Logs a message to the {@link Console.debug} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link debug}
+     * or {@link d} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.debug} function.
+     *
+     * @see {@link debug}
+     * @see {@link d}
+     */
+    debugRaw(msg: LogMessage, ...args: AnyValue[]): void;
+    /** This function is just an alias to the {@link debug} function. */
+    d: (msg: LogMessage, ...args: AnyValue[]) => void;
+    /**
+     * Logs a message to the {@link Console.info} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link infoRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link infoRaw}
+     * @see {@link i}
+     */
+    info(msg: LogMessage, ...args: AnyValue[]): void;
+    /**
+     * Logs a message to the {@link Console.info} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link info}
+     * or {@link i} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.info} function.
+     *
+     * @see {@link info}
+     * @see {@link i}
+     */
+    infoRaw(msg: LogMessage, ...args: AnyValue[]): void;
+    /** This function is just an alias to the {@link info} function. */
+    i: (msg: LogMessage, ...args: AnyValue[]) => void;
+    /**
+     * Logs a message to the {@link Console.warn} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link warnRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link warnRaw}
+     * @see {@link w}
+     */
+    warn(msg: LogMessage, ...args: AnyValue[]): void;
+    /**
+     * Logs a message to the {@link Console.warn} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link warn}
+     * or {@link w} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.warn} function.
+     *
+     * @see {@link warn}
+     * @see {@link w}
+     */
+    warnRaw(msg: LogMessage, ...args: AnyValue[]): void;
+    /** This function is just an alias to the {@link warn} function. */
+    w: (msg: LogMessage, ...args: AnyValue[]) => void;
+    /**
+     * Logs a message to the {@link Console.error} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link errorRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link errorRaw}
+     * @see {@link e}
+     */
+    error(msg: LogMessage, ...args: AnyValue[]): void;
+    /**
+     * Logs a message to the {@link Console.error} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link error}
+     * or {@link e} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.error} function.
+     *
+     * @see {@link error}
+     * @see {@link e}
+     */
+    errorRaw(msg: LogMessage, ...args: AnyValue[]): void;
+    /** This function is just an alias to the {@link error} function. */
+    e: (msg: LogMessage, ...args: AnyValue[]) => void;
+    /**
+     * Logs a message to the {@link Console.log} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link logRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link logRaw}
+     */
+    log(msg: LogMessage, ...args: AnyValue[]): void;
+    /**
+     * Logs a message to the {@link Console.log} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link error}
+     * function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.log} function.
+     *
+     * @see {@link log}
+     */
+    logRaw(msg: LogMessage, ...args: AnyValue[]): void;
+}
+export declare const Log: Logger;

package/dist/utils/CarouselLogger.js

@@ -0,0 +1,370 @@
+"use strict";
+/*
+ * Copyright (c) 2024 - 2025 Amazon.com, Inc. or its affiliates. All rights reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL. USE IS SUBJECT TO LICENSE TERMS.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Log = exports.Logger = void 0;
+const ansi_colors_1 = __importDefault(require("ansi-colors"));
+const CarouselReactNativeUtilities_1 = require("./CarouselReactNativeUtilities");
+/**
+ * Helper class to log messages to the {@link Console} using a `printf` style
+ * syntax for string interpolation, and a _Robot-like_ API.
+ *
+ * When using the `printf`-like interpolation, you'll need to use the syntax
+ * explained on the {@link Logger.format} function.
+ *
+ * @see {@link Logger.format}
+ * @internal
+ */
+class Logger {
+    /**
+     * The string to be prepended to all log message logged with this utility
+     * class.
+     * @private
+     */
+    tag;
+    /**
+     * Attribute that holds static information about an instance of `Logger`.
+     * @private
+     */
+    levelInfo;
+    constructor(tag) {
+        this.tag = tag;
+        this.levelInfo = {
+            trace: {
+                prefix: Logger.buildLogPrefix(this.tag, 'trace'),
+                wrapLog: Logger.logWrapper(ansi_colors_1.default.blackBright),
+            },
+            debug: {
+                prefix: Logger.buildLogPrefix(this.tag, 'debug'),
+                wrapLog: Logger.logWrapper(ansi_colors_1.default.green),
+            },
+            info: {
+                prefix: Logger.buildLogPrefix(this.tag, 'info'),
+                wrapLog: Logger.logWrapper(ansi_colors_1.default.reset),
+            },
+            warn: {
+                prefix: Logger.buildLogPrefix(this.tag, 'warn'),
+                wrapLog: Logger.logWrapper(ansi_colors_1.default.yellow),
+            },
+            error: {
+                prefix: Logger.buildLogPrefix(this.tag, 'error'),
+                wrapLog: Logger.logWrapper(ansi_colors_1.default.red),
+            },
+            log: {
+                prefix: Logger.buildLogPrefix(this.tag),
+                wrapLog: Logger.logWrapper(ansi_colors_1.default.reset),
+            },
+        };
+    }
+    /**
+     * Function to interpolate values from the variadic argument `args` into the
+     * given `message`.
+     *
+     * To embed one of the variadic arguments into the string, use the `{N}`
+     * syntax, where `N` is the positional index of the arg.
+     *
+     * You can also repeat the usage of an arg by repeating its `{N}` placeholder.
+     *
+     * @param {string} message The string message to be interpolated with values
+     *        from the given `args`.
+     * @param {...any} args A variadic list of arguments to be used to interpolate
+     *        matches of `{N}` in the given `message`.
+     * @private
+     */
+    static format(message, ...args) {
+        let dynIndex = 0;
+        return message.replace(/{(\d*)}/g, (match, index) => {
+            const idx = index === '' ? dynIndex++ : index;
+            const argValue = idx >= 0 && idx < args.length ? args[idx] : match;
+            return argValue === null ? '<null>' : (argValue ?? '<undefined>');
+        });
+    }
+    /**
+     * Helper function to create the log prefix for a `tag` and a log `level`.
+     *
+     * This function is mainly used in tests to help us build log messages that
+     * mach the real log output.
+     *
+     * @param {string} tag An arbitrary string to go at the start of the log
+     *        message. Inside a {@link Logger} class, this will be
+     *        {@link Logger.tag}.
+     * @param {LogLevelType?} level An optional string representing one of the
+     *        supported logs.
+     */
+    static buildLogPrefix(tag, level) {
+        if (level) {
+            return `${tag} (JS) [${level.toUpperCase()}]`;
+        }
+        return `${tag} (JS)`;
+    }
+    /**
+     * Helper function used to allow us to test this class. When running a test,
+     * the function returned by this wrapper is a simple pass-through of the log
+     * message.
+     *
+     * @param {(text: string) => string} wrapper The function that will wrap the
+     *        log message before sending it to the console.
+     *
+     * @return {(text: string) => string} Returns the given message back to the
+     *         caller, unless it is running in a test environment, which, in such
+     *         a case, it will return a simple pass-through function
+     *         (`msg => mst`).
+     * @private
+     */
+    static logWrapper(wrapper) {
+        return CarouselReactNativeUtilities_1.isTest ? msg => msg : /* istanbul ignore next */ wrapper;
+    }
+    /**
+     * Main function to perform the console log.
+     *
+     * This function also augments each log message to the appropriate color for
+     * its level.
+     *
+     * @param {boolean} useRawConsole Flag indicating if the message being logged
+     *        is using the `printf`-like syntax or not.
+     * @param {LogLevelType} level The log level to use to output the given
+     *        `message`.
+     * @param {LogMessage} message The message to be sent to the console output.
+     *        If this argument is given as an array of strings, a space character
+     *        will _join_ each entry in the array to form the final message. If it
+     *        is a function, the function will be called to resolve the string.
+     * @param {...any} args A variadic list of arguments to be used to interpolate
+     *        matches of `{N}` in the given `message`.
+     * @private
+     */
+    consoleLog(useRawConsole, level, message, ...args) {
+        const logMessage = typeof message === 'string'
+            ? message
+            : typeof message === 'function'
+                ? message()
+                : message.join(' ');
+        const logInfo = this.levelInfo[level];
+        if (useRawConsole) {
+            console[level](logInfo.prefix, logMessage, ...args);
+        }
+        else {
+            const fullMessage = `${logInfo.prefix} ${Logger.format(logMessage, ...args)}`;
+            console[level](logInfo.wrapLog(fullMessage));
+        }
+    }
+    /**
+     * Logs a message to the {@link Console.trace} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link traceRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link traceRaw}
+     * @see {@link t}
+     */
+    trace(msg, ...args) {
+        this.consoleLog(false, 'trace', msg, ...args);
+    }
+    /**
+     * Logs a message to the {@link Console.trace} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link trace}
+     * or {@link t} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.trace} function.
+     *
+     * @see {@link trace}
+     * @see {@link t}
+     */
+    traceRaw(msg, ...args) {
+        this.consoleLog(true, 'trace', msg, ...args);
+    }
+    /** This function is just an alias to the {@link trace} function. */
+    t = this.trace;
+    /**
+     * Logs a message to the {@link Console.debug} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link debugRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link debugRaw}
+     * @see {@link d}
+     */
+    debug(msg, ...args) {
+        this.consoleLog(false, 'debug', msg, ...args);
+    }
+    /**
+     * Logs a message to the {@link Console.debug} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link debug}
+     * or {@link d} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.debug} function.
+     *
+     * @see {@link debug}
+     * @see {@link d}
+     */
+    debugRaw(msg, ...args) {
+        this.consoleLog(true, 'debug', msg, ...args);
+    }
+    /** This function is just an alias to the {@link debug} function. */
+    d = this.debug;
+    /**
+     * Logs a message to the {@link Console.info} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link infoRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link infoRaw}
+     * @see {@link i}
+     */
+    info(msg, ...args) {
+        this.consoleLog(false, 'info', msg, ...args);
+    }
+    /**
+     * Logs a message to the {@link Console.info} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link info}
+     * or {@link i} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.info} function.
+     *
+     * @see {@link info}
+     * @see {@link i}
+     */
+    infoRaw(msg, ...args) {
+        this.consoleLog(true, 'info', msg, ...args);
+    }
+    /** This function is just an alias to the {@link info} function. */
+    i = this.info;
+    /**
+     * Logs a message to the {@link Console.warn} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link warnRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link warnRaw}
+     * @see {@link w}
+     */
+    warn(msg, ...args) {
+        this.consoleLog(false, 'warn', msg, ...args);
+    }
+    /**
+     * Logs a message to the {@link Console.warn} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link warn}
+     * or {@link w} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.warn} function.
+     *
+     * @see {@link warn}
+     * @see {@link w}
+     */
+    warnRaw(msg, ...args) {
+        this.consoleLog(true, 'warn', msg, ...args);
+    }
+    /** This function is just an alias to the {@link warn} function. */
+    w = this.warn;
+    /**
+     * Logs a message to the {@link Console.error} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link errorRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link errorRaw}
+     * @see {@link e}
+     */
+    error(msg, ...args) {
+        this.consoleLog(false, 'error', msg, ...args);
+    }
+    /**
+     * Logs a message to the {@link Console.error} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link error}
+     * or {@link e} functions.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.error} function.
+     *
+     * @see {@link error}
+     * @see {@link e}
+     */
+    errorRaw(msg, ...args) {
+        this.consoleLog(true, 'error', msg, ...args);
+    }
+    /** This function is just an alias to the {@link error} function. */
+    e = this.error;
+    /**
+     * Logs a message to the {@link Console.log} function using a `printf` style
+     * API for string interpolation.
+     *
+     * To use the same API as the one offered by the {@link Console}, use the
+     * {@link logRaw} function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be used as arguments on the
+     *        string interpolation.
+     *
+     * @see {@link logRaw}
+     */
+    log(msg, ...args) {
+        this.consoleLog(false, 'log', msg, ...args);
+    }
+    /**
+     * Logs a message to the {@link Console.log} function using the same API as
+     * the one offered by the {@link Console}.
+     *
+     * To use a `printf`-like API for string interpolation, use the {@link error}
+     * function.
+     *
+     * @param {LogMessage} msg The message to be logged.
+     * @param {any[]} args A variadic argument to be passed down to the
+     *        {@link Console.log} function.
+     *
+     * @see {@link log}
+     */
+    logRaw(msg, ...args) {
+        this.consoleLog(true, 'log', msg, ...args);
+    }
+}
+exports.Logger = Logger;
+exports.Log = new Logger('com.amazon.kepler.tv.pnc');