expensify-common 2.0.187 → 2.0.188

package/dist/CLI.d.ts

@@ -0,0 +1,160 @@
+import type { NonEmptyObject, NonEmptyTuple } from 'type-fest';
+/**
+ * A base CLI arg has only a description, which we will use in the help/usage message (built-in to any CLI).
+ */
+type CLIArg = {
+    description: string;
+};
+/**
+ * A boolean arg is characterized only by its presence or absence so has no other fields,
+ * but we'll create a type alias to clearly distinguish it from other argument types.
+ */
+type BooleanArg = CLIArg;
+/**
+ * Any other argument is provided raw in process.argv as a string.
+ * It can remain a string, or can be transformed into another type by a custom `parse` function.
+ * It can be optional (by providing a default) or required (no default value).
+ * It can also supersede other named arguments when provided.
+ */
+type StringArg<T = unknown> = CLIArg & {
+    default?: T;
+    parse?: (val: string) => T;
+    supersedes?: string[];
+    required?: boolean;
+};
+/**
+ * A positional argument is just a string arg, but also must be assigned a name which we will eventually expose the CLI consumer.
+ * If `variadic` is true, this must be the last positional arg and it collects all remaining positional args into a string[].
+ */
+type PositionalArg<T = unknown> = StringArg<T> & {
+    name: string;
+    variadic?: true;
+};
+/**
+ * This type represents the config for a CLI.
+ * The last positional arg can be marked `variadic: true` to collect all remaining positional args into a string[].
+ */
+type CLIConfig = NonEmptyObject<{
+    /**
+     * Record of named flags that are fully characterized by their presence or absence (present=true,absent=false).
+     * @example `--verbose`
+     */
+    flags?: Record<string, BooleanArg>;
+    /**
+     * Record of named arguments that are represented by a key and a value.
+     * @example `--threads=8`
+     * @example `--name Rory`
+     */
+    namedArgs?: Record<string, StringArg>;
+    /**
+     * Tuple of positional args.
+     * @example `myScript.ts arg1 arg2 arg3`
+     */
+    positionalArgs?: NonEmptyTuple<PositionalArg>;
+}>;
+/**
+ * Record of flags to boolean after parsing.
+ */
+type ParsedFlags<Flags extends CLIConfig['flags']> = {
+    [K in keyof NonNullable<Flags>]: boolean;
+};
+/**
+ * Utility type to infer the final value of a string param. Either:
+ * - it's a plain string, or
+ * - it has a parse function and the final value is inferred from the return type of that function
+ */
+type InferStringArgParsedValue<T extends StringArg> = T extends {
+    parse: (val: string) => infer R;
+} ? R : string;
+/**
+ * Record of named args after parsing.
+ */
+type ParsedNamedArgs<NamedArgs extends CLIConfig['namedArgs']> = {
+    [K in keyof NonNullable<NamedArgs>]: InferStringArgParsedValue<NonNullable<NamedArgs>[K]>;
+};
+/**
+ * Record of positional args after parsing.
+ * Variadic args are parsed as string[]; all others use InferStringArgParsedValue.
+ */
+type ParsedPositionalArgs<PositionalArgs extends CLIConfig['positionalArgs']> = {
+    [K in NonNullable<PositionalArgs>[number] as K['name']]: K extends {
+        variadic: true;
+    } ? string[] : InferStringArgParsedValue<K>;
+};
+/**
+ * Utility to parse command-line arguments to a script.
+ *
+ * @example
+ * ```
+ * const cli = new CLI({
+ *     flags: {
+ *         verbose: {
+ *             description: 'Enable verbose logging',
+ *         },
+ *     },
+ *     namedArgs: {
+ *         time: {
+ *             description: 'Time of day to greet (morning or evening)',
+ *             default: 'morning',
+ *             parse: (val) => {
+ *                 if (val !== 'morning' && val !== 'evening') {
+ *                     throw new Error('Must be "morning" or "evening"');
+ *                 }
+ *                 return val as 'morning' | 'evening';
+ *             },
+ *         },
+ *     },
+ *     positionalArgs: [
+ *         {
+ *             name: 'firstName'
+ *             description: 'First name to greet',
+ *         },
+ *         {
+ *             name: 'lastName',
+ *             description: 'Last name to greet',
+ *             default: '',
+ *         },
+ *     ],
+ * });
+ *
+ * let fullName = cli.positionalArgs.firstName;
+ * if (cli.flags.verbose) {
+ *     fullName += cli.positionalArgs.lastName;
+ * }
+ * console.log(fullName);
+ * console.log(cli.namedArgs.time);
+ * ```
+ */
+/**
+ * Built-in flags that are always available on any CLI.
+ */
+type BuiltInFlags = {
+    yes: boolean;
+    no: boolean;
+    help: boolean;
+};
+declare class CLI<TConfig extends CLIConfig> {
+    private readonly config;
+    /**
+     * Flags after parsing (includes built-in flags like --yes, --no, and --help).
+     */
+    readonly flags: ParsedFlags<TConfig['flags']> & BuiltInFlags;
+    /**
+     * Named args after parsing.
+     */
+    readonly namedArgs: ParsedNamedArgs<TConfig['namedArgs']>;
+    /**
+     * Positional args after parsing, collected into a record keyed by the name of each arg.
+     */
+    readonly positionalArgs: ParsedPositionalArgs<TConfig['positionalArgs']>;
+    constructor(config: TConfig);
+    private printHelp;
+    private static parseStringArg;
+    /**
+     * Prompts the user for confirmation and returns true if they confirm (y/yes), false otherwise.
+     * If --yes flag was passed, returns true immediately without prompting.
+     * If --no flag was passed, returns false immediately without prompting.
+     */
+    promptUserConfirmation(message: string): Promise<boolean>;
+}
+export default CLI;

package/dist/CLI.js

@@ -0,0 +1,282 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * This file contains a CLI utility class which can be used to declaratively implement a strongly-typed CLI.
+ * You provide a CLIConfig defining your arguments, then the class will handle parsing argv, type validation, error handling, and help messages.
+ */
+const readline = __importStar(require("readline"));
+const SafeString_js_1 = __importDefault(require("./SafeString.js"));
+class CLI {
+    constructor(config) {
+        var _a, _b, _c, _d, _e, _f;
+        this.config = config;
+        const rawArgs = process.argv.slice(2);
+        // Initialize all flags to false by default (including built-in flags)
+        this.flags = Object.assign(Object.assign({}, Object.fromEntries(Object.keys((_a = config.flags) !== null && _a !== void 0 ? _a : {}).map((key) => [key, false]))), { yes: false, no: false, help: false });
+        try {
+            const parsedNamedArgs = {};
+            const parsedPositionalArgs = {};
+            const providedNamedArgs = new Set();
+            let positionalIndex = 0;
+            for (let i = 0; i < rawArgs.length; i++) {
+                const rawArg = rawArgs.at(i);
+                if (rawArg === undefined) {
+                    continue;
+                }
+                if (rawArg.startsWith('--')) {
+                    // Either a flag or a named param
+                    const [rawArgName, rawArgValue] = rawArg.slice(2).split('=');
+                    if (rawArgName in this.flags) {
+                        // Arg is a flag
+                        this.flags[rawArgName] = true;
+                    }
+                    else if (config.namedArgs && rawArgName in config.namedArgs) {
+                        // Arg is a named arg
+                        providedNamedArgs.add(rawArgName);
+                        // Grab the value from the split token, otherwise go for the next token
+                        let argValueBeforeParse = '';
+                        if (rawArgValue) {
+                            argValueBeforeParse = rawArgValue;
+                        }
+                        else {
+                            argValueBeforeParse = (_b = rawArgs.at(++i)) !== null && _b !== void 0 ? _b : '';
+                            if (!argValueBeforeParse || argValueBeforeParse.startsWith('--')) {
+                                throw new Error(`Missing value for --${rawArgName}`);
+                            }
+                        }
+                        const spec = config.namedArgs[rawArgName];
+                        parsedNamedArgs[rawArgName] = CLI.parseStringArg(argValueBeforeParse, rawArgName, spec);
+                    }
+                    else {
+                        console.error(`Unknown flag: --${rawArgName}`);
+                        process.exit(1);
+                    }
+                }
+                else {
+                    // Arg is a positional arg
+                    const spec = (_c = config.positionalArgs) === null || _c === void 0 ? void 0 : _c.at(positionalIndex);
+                    if (spec === undefined) {
+                        throw new Error(`Unexpected arg: ${rawArg}`);
+                    }
+                    if (spec.variadic) {
+                        // Variadic: collect this and all remaining non-flag args into an array
+                        const collected = [];
+                        for (let j = i; j < rawArgs.length; j++) {
+                            const remaining = rawArgs.at(j);
+                            if (remaining === undefined || remaining.startsWith('--')) {
+                                break;
+                            }
+                            collected.push(remaining);
+                        }
+                        parsedPositionalArgs[spec.name] = collected;
+                        break;
+                    }
+                    parsedPositionalArgs[spec.name] = CLI.parseStringArg(rawArg, spec.name, spec);
+                    positionalIndex++;
+                }
+            }
+            // Handle help command
+            if (this.flags.help) {
+                this.printHelp();
+                process.exit(0);
+            }
+            // Handle supersession logic
+            const supersededArgs = new Set();
+            for (const [name, spec] of Object.entries((_d = config.namedArgs) !== null && _d !== void 0 ? _d : {})) {
+                if (providedNamedArgs.has(name) && spec.supersedes) {
+                    for (const supersededArg of spec.supersedes) {
+                        supersededArgs.add(supersededArg);
+                        if (providedNamedArgs.has(supersededArg)) {
+                            console.warn(`⚠️  Warning: --${supersededArg} is superseded by --${name} and will be ignored.`);
+                        }
+                    }
+                }
+            }
+            // Validate that all required args are present, assign defaults where values are not parsed
+            for (const [name, spec] of Object.entries((_e = config.namedArgs) !== null && _e !== void 0 ? _e : {})) {
+                if (name in parsedNamedArgs) {
+                    if (supersededArgs.has(name)) {
+                        parsedNamedArgs[name] = undefined;
+                    }
+                }
+                else if (supersededArgs.has(name)) {
+                    // This arg was superseded, so don't require it and don't assign a default
+                    continue;
+                }
+                else if (spec.default !== undefined) {
+                    parsedNamedArgs[name] = spec.default;
+                }
+                else if (spec.required === false) {
+                    // Explicitly marked as optional, leave undefined
+                    continue;
+                }
+                else {
+                    // Arguments without defaults are required by default (unless explicitly marked as optional)
+                    throw new Error(`Missing required named argument --${name}`);
+                }
+            }
+            for (const spec of (_f = config.positionalArgs) !== null && _f !== void 0 ? _f : []) {
+                if (!(spec.name in parsedPositionalArgs)) {
+                    if (spec.default !== undefined) {
+                        parsedPositionalArgs[spec.name] = spec.default;
+                    }
+                    else if (spec.variadic) {
+                        parsedPositionalArgs[spec.name] = [];
+                    }
+                    else {
+                        throw new Error(`Missing required positional argument --${spec.name}`);
+                    }
+                }
+            }
+            this.namedArgs = parsedNamedArgs;
+            this.positionalArgs = parsedPositionalArgs;
+        }
+        catch (err) {
+            // If help flag was set, the error is from process.exit(0) in tests (where it's mocked to throw) - just rethrow it
+            if (this.flags.help) {
+                throw err;
+            }
+            if (err instanceof Error) {
+                console.error(err.message);
+                this.printHelp();
+            }
+            else {
+                console.error('An unexpected error occurred initializing the CLI.');
+            }
+            process.exit(1);
+        }
+    }
+    printHelp() {
+        var _a;
+        const { flags = {}, namedArgs = {}, positionalArgs = [] } = this.config;
+        const scriptName = (_a = process.argv.at(1)) !== null && _a !== void 0 ? _a : 'script.ts';
+        const positionalUsage = positionalArgs
+            .map((arg) => {
+            const label = arg.variadic ? `${arg.name}...` : arg.name;
+            return arg.default === undefined ? `<${label}>` : `[${label}]`;
+        })
+            .join(' ');
+        const namedArgUsage = Object.keys(namedArgs)
+            .map((key) => `[--${key} <value>]`)
+            .join(' ');
+        const flagUsage = [...Object.keys(flags), '--yes', '--no', '--help'].map((key) => `[${key.startsWith('--') ? key : `--${key}`}]`).join(' ');
+        console.log(`\nUsage: npx ts-node ${scriptName} ${flagUsage} ${namedArgUsage} ${positionalUsage}\n`);
+        console.log('Flags:');
+        for (const [name, spec] of Object.entries(flags)) {
+            console.log(`  --${name.padEnd(20)} ${spec.description}`);
+        }
+        // Built-in flags
+        console.log(`  --${'yes'.padEnd(20)} Automatically answer "yes" to all confirmation prompts.`);
+        console.log(`  --${'no'.padEnd(20)} Automatically answer "no" to all confirmation prompts.`);
+        console.log(`  --${'help'.padEnd(20)} Show this help message.`);
+        console.log('');
+        if (Object.keys(namedArgs).length > 0) {
+            console.log('Named Arguments:');
+            for (const [name, spec] of Object.entries(namedArgs)) {
+                const defaultLabel = spec.default !== undefined ? ` (default: ${(0, SafeString_js_1.default)(spec.default)})` : '';
+                const supersededLabel = spec.supersedes && spec.supersedes.length > 0 ? ` (supersedes: ${spec.supersedes.join(', ')})` : '';
+                console.log(`  --${name.padEnd(20)} ${spec.description}${defaultLabel}${supersededLabel}`);
+            }
+            console.log('');
+        }
+        if (positionalArgs.length > 0) {
+            console.log('Positional Arguments:');
+            for (const arg of positionalArgs) {
+                const defaultLabel = arg.default !== undefined ? ` (default: ${(0, SafeString_js_1.default)(arg.default)})` : '';
+                console.log(`  ${arg.name.padEnd(22)} ${arg.description}${defaultLabel}`);
+            }
+            console.log('');
+        }
+    }
+    static parseStringArg(rawString, paramName, spec) {
+        if ('parse' in spec && !!spec.parse) {
+            try {
+                return spec.parse(rawString);
+            }
+            catch (error) {
+                let errorMessage = '';
+                if (error instanceof Error) {
+                    errorMessage = error.message;
+                }
+                console.error(`Invalid value for --${paramName}: ${errorMessage}`);
+                process.exit(1);
+            }
+        }
+        else {
+            return rawString;
+        }
+    }
+    /**
+     * Prompts the user for confirmation and returns true if they confirm (y/yes), false otherwise.
+     * If --yes flag was passed, returns true immediately without prompting.
+     * If --no flag was passed, returns false immediately without prompting.
+     */
+    promptUserConfirmation(message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Check for built-in flags first
+            if (this.flags.yes) {
+                return true;
+            }
+            if (this.flags.no) {
+                return false;
+            }
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            return new Promise((resolve) => {
+                rl.question(message, (answer) => {
+                    rl.close();
+                    const normalizedAnswer = answer.trim().toLowerCase();
+                    resolve(normalizedAnswer === 'y' || normalizedAnswer === 'yes');
+                });
+            });
+        });
+    }
+}
+exports.default = CLI;

package/dist/esm/CLI.d.ts

@@ -0,0 +1,160 @@
+import type { NonEmptyObject, NonEmptyTuple } from 'type-fest';
+/**
+ * A base CLI arg has only a description, which we will use in the help/usage message (built-in to any CLI).
+ */
+type CLIArg = {
+    description: string;
+};
+/**
+ * A boolean arg is characterized only by its presence or absence so has no other fields,
+ * but we'll create a type alias to clearly distinguish it from other argument types.
+ */
+type BooleanArg = CLIArg;
+/**
+ * Any other argument is provided raw in process.argv as a string.
+ * It can remain a string, or can be transformed into another type by a custom `parse` function.
+ * It can be optional (by providing a default) or required (no default value).
+ * It can also supersede other named arguments when provided.
+ */
+type StringArg<T = unknown> = CLIArg & {
+    default?: T;
+    parse?: (val: string) => T;
+    supersedes?: string[];
+    required?: boolean;
+};
+/**
+ * A positional argument is just a string arg, but also must be assigned a name which we will eventually expose the CLI consumer.
+ * If `variadic` is true, this must be the last positional arg and it collects all remaining positional args into a string[].
+ */
+type PositionalArg<T = unknown> = StringArg<T> & {
+    name: string;
+    variadic?: true;
+};
+/**
+ * This type represents the config for a CLI.
+ * The last positional arg can be marked `variadic: true` to collect all remaining positional args into a string[].
+ */
+type CLIConfig = NonEmptyObject<{
+    /**
+     * Record of named flags that are fully characterized by their presence or absence (present=true,absent=false).
+     * @example `--verbose`
+     */
+    flags?: Record<string, BooleanArg>;
+    /**
+     * Record of named arguments that are represented by a key and a value.
+     * @example `--threads=8`
+     * @example `--name Rory`
+     */
+    namedArgs?: Record<string, StringArg>;
+    /**
+     * Tuple of positional args.
+     * @example `myScript.ts arg1 arg2 arg3`
+     */
+    positionalArgs?: NonEmptyTuple<PositionalArg>;
+}>;
+/**
+ * Record of flags to boolean after parsing.
+ */
+type ParsedFlags<Flags extends CLIConfig['flags']> = {
+    [K in keyof NonNullable<Flags>]: boolean;
+};
+/**
+ * Utility type to infer the final value of a string param. Either:
+ * - it's a plain string, or
+ * - it has a parse function and the final value is inferred from the return type of that function
+ */
+type InferStringArgParsedValue<T extends StringArg> = T extends {
+    parse: (val: string) => infer R;
+} ? R : string;
+/**
+ * Record of named args after parsing.
+ */
+type ParsedNamedArgs<NamedArgs extends CLIConfig['namedArgs']> = {
+    [K in keyof NonNullable<NamedArgs>]: InferStringArgParsedValue<NonNullable<NamedArgs>[K]>;
+};
+/**
+ * Record of positional args after parsing.
+ * Variadic args are parsed as string[]; all others use InferStringArgParsedValue.
+ */
+type ParsedPositionalArgs<PositionalArgs extends CLIConfig['positionalArgs']> = {
+    [K in NonNullable<PositionalArgs>[number] as K['name']]: K extends {
+        variadic: true;
+    } ? string[] : InferStringArgParsedValue<K>;
+};
+/**
+ * Utility to parse command-line arguments to a script.
+ *
+ * @example
+ * ```
+ * const cli = new CLI({
+ *     flags: {
+ *         verbose: {
+ *             description: 'Enable verbose logging',
+ *         },
+ *     },
+ *     namedArgs: {
+ *         time: {
+ *             description: 'Time of day to greet (morning or evening)',
+ *             default: 'morning',
+ *             parse: (val) => {
+ *                 if (val !== 'morning' && val !== 'evening') {
+ *                     throw new Error('Must be "morning" or "evening"');
+ *                 }
+ *                 return val as 'morning' | 'evening';
+ *             },
+ *         },
+ *     },
+ *     positionalArgs: [
+ *         {
+ *             name: 'firstName'
+ *             description: 'First name to greet',
+ *         },
+ *         {
+ *             name: 'lastName',
+ *             description: 'Last name to greet',
+ *             default: '',
+ *         },
+ *     ],
+ * });
+ *
+ * let fullName = cli.positionalArgs.firstName;
+ * if (cli.flags.verbose) {
+ *     fullName += cli.positionalArgs.lastName;
+ * }
+ * console.log(fullName);
+ * console.log(cli.namedArgs.time);
+ * ```
+ */
+/**
+ * Built-in flags that are always available on any CLI.
+ */
+type BuiltInFlags = {
+    yes: boolean;
+    no: boolean;
+    help: boolean;
+};
+declare class CLI<TConfig extends CLIConfig> {
+    private readonly config;
+    /**
+     * Flags after parsing (includes built-in flags like --yes, --no, and --help).
+     */
+    readonly flags: ParsedFlags<TConfig['flags']> & BuiltInFlags;
+    /**
+     * Named args after parsing.
+     */
+    readonly namedArgs: ParsedNamedArgs<TConfig['namedArgs']>;
+    /**
+     * Positional args after parsing, collected into a record keyed by the name of each arg.
+     */
+    readonly positionalArgs: ParsedPositionalArgs<TConfig['positionalArgs']>;
+    constructor(config: TConfig);
+    private printHelp;
+    private static parseStringArg;
+    /**
+     * Prompts the user for confirmation and returns true if they confirm (y/yes), false otherwise.
+     * If --yes flag was passed, returns true immediately without prompting.
+     * If --no flag was passed, returns false immediately without prompting.
+     */
+    promptUserConfirmation(message: string): Promise<boolean>;
+}
+export default CLI;

package/{lib/CLI.ts → dist/esm/CLI.js}

@@ -3,226 +3,58 @@
  * You provide a CLIConfig defining your arguments, then the class will handle parsing argv, type validation, error handling, and help messages.
  */
 import * as readline from 'readline';
-import type {NonEmptyObject, NonEmptyTuple, ValueOf, Writable} from 'type-fest';
-import SafeString from './SafeString';
-
-/**
- * A base CLI arg has only a description, which we will use in the help/usage message (built-in to any CLI).
- */
-type CLIArg = {
-    description: string;
-};
-
-/**
- * A boolean arg is characterized only by its presence or absence so has no other fields,
- * but we'll create a type alias to clearly distinguish it from other argument types.
- */
-type BooleanArg = CLIArg;
-
-/**
- * Any other argument is provided raw in process.argv as a string.
- * It can remain a string, or can be transformed into another type by a custom `parse` function.
- * It can be optional (by providing a default) or required (no default value).
- * It can also supersede other named arguments when provided.
- */
-type StringArg<T = unknown> = CLIArg & {
-    default?: T;
-    parse?: (val: string) => T;
-    supersedes?: string[];
-    required?: boolean;
-};
-
-/**
- * A positional argument is just a string arg, but also must be assigned a name which we will eventually expose the CLI consumer.
- * If `variadic` is true, this must be the last positional arg and it collects all remaining positional args into a string[].
- */
-type PositionalArg<T = unknown> = StringArg<T> & {
-    name: string;
-    variadic?: true;
-};
-
-/**
- * This type represents the config for a CLI.
- * The last positional arg can be marked `variadic: true` to collect all remaining positional args into a string[].
- */
-type CLIConfig = NonEmptyObject<{
-    /**
-     * Record of named flags that are fully characterized by their presence or absence (present=true,absent=false).
-     * @example `--verbose`
-     */
-    flags?: Record<string, BooleanArg>;
-
-    /**
-     * Record of named arguments that are represented by a key and a value.
-     * @example `--threads=8`
-     * @example `--name Rory`
-     */
-    namedArgs?: Record<string, StringArg>;
-
-    /**
-     * Tuple of positional args.
-     * @example `myScript.ts arg1 arg2 arg3`
-     */
-    positionalArgs?: NonEmptyTuple<PositionalArg>;
-}>;
-
-/**
- * Record of flags to boolean after parsing.
- */
-type ParsedFlags<Flags extends CLIConfig['flags']> = {
-    [K in keyof NonNullable<Flags>]: boolean;
-};
-
-/**
- * Utility type to infer the final value of a string param. Either:
- * - it's a plain string, or
- * - it has a parse function and the final value is inferred from the return type of that function
- */
-type InferStringArgParsedValue<T extends StringArg> = T extends {
-    parse: (val: string) => infer R;
-}
-    ? R
-    : string;
-
-/**
- * Record of named args after parsing.
- */
-type ParsedNamedArgs<NamedArgs extends CLIConfig['namedArgs']> = {
-    [K in keyof NonNullable<NamedArgs>]: InferStringArgParsedValue<NonNullable<NamedArgs>[K]>;
-};
-
-/**
- * Record of positional args after parsing.
- * Variadic args are parsed as string[]; all others use InferStringArgParsedValue.
- */
-type ParsedPositionalArgs<PositionalArgs extends CLIConfig['positionalArgs']> = {
-    [K in NonNullable<PositionalArgs>[number] as K['name']]: K extends {
-        variadic: true;
-    }
-        ? string[]
-        : InferStringArgParsedValue<K>;
-};
-
-/**
- * Utility to parse command-line arguments to a script.
- *
- * @example
- * ```
- * const cli = new CLI({
- *     flags: {
- *         verbose: {
- *             description: 'Enable verbose logging',
- *         },
- *     },
- *     namedArgs: {
- *         time: {
- *             description: 'Time of day to greet (morning or evening)',
- *             default: 'morning',
- *             parse: (val) => {
- *                 if (val !== 'morning' && val !== 'evening') {
- *                     throw new Error('Must be "morning" or "evening"');
- *                 }
- *                 return val as 'morning' | 'evening';
- *             },
- *         },
- *     },
- *     positionalArgs: [
- *         {
- *             name: 'firstName'
- *             description: 'First name to greet',
- *         },
- *         {
- *             name: 'lastName',
- *             description: 'Last name to greet',
- *             default: '',
- *         },
- *     ],
- * });
- *
- * let fullName = cli.positionalArgs.firstName;
- * if (cli.flags.verbose) {
- *     fullName += cli.positionalArgs.lastName;
- * }
- * console.log(fullName);
- * console.log(cli.namedArgs.time);
- * ```
- */
-/**
- * Built-in flags that are always available on any CLI.
- */
-type BuiltInFlags = {
-    yes: boolean;
-    no: boolean;
-    help: boolean;
-};
-
-class CLI<TConfig extends CLIConfig> {
-    /**
-     * Flags after parsing (includes built-in flags like --yes, --no, and --help).
-     */
-    public readonly flags: ParsedFlags<TConfig['flags']> & BuiltInFlags;
-
-    /**
-     * Named args after parsing.
-     */
-    public readonly namedArgs: ParsedNamedArgs<TConfig['namedArgs']>;
-
-    /**
-     * Positional args after parsing, collected into a record keyed by the name of each arg.
-     */
-    public readonly positionalArgs: ParsedPositionalArgs<TConfig['positionalArgs']>;
-
-    constructor(private readonly config: TConfig) {
+import SafeString from './SafeString.js';
+class CLI {
+    constructor(config) {
+        this.config = config;
         const rawArgs = process.argv.slice(2);
-
         // Initialize all flags to false by default (including built-in flags)
         this.flags = {
             ...Object.fromEntries(Object.keys(config.flags ?? {}).map((key) => [key, false])),
             yes: false,
             no: false,
             help: false,
-        } as typeof this.flags;
-
+        };
         try {
-            const parsedNamedArgs: Partial<Writable<typeof this.namedArgs>> = {};
-            const parsedPositionalArgs: Partial<Writable<typeof this.positionalArgs>> = {};
-            const providedNamedArgs = new Set<string>();
-
+            const parsedNamedArgs = {};
+            const parsedPositionalArgs = {};
+            const providedNamedArgs = new Set();
             let positionalIndex = 0;
             for (let i = 0; i < rawArgs.length; i++) {
                 const rawArg = rawArgs.at(i);
                 if (rawArg === undefined) {
                     continue;
                 }
-
                 if (rawArg.startsWith('--')) {
                     // Either a flag or a named param
                     const [rawArgName, rawArgValue] = rawArg.slice(2).split('=');
                     if (rawArgName in this.flags) {
                         // Arg is a flag
-                        (this.flags as Record<string, boolean>)[rawArgName] = true;
-                    } else if (config.namedArgs && rawArgName in config.namedArgs) {
+                        this.flags[rawArgName] = true;
+                    }
+                    else if (config.namedArgs && rawArgName in config.namedArgs) {
                         // Arg is a named arg
                         providedNamedArgs.add(rawArgName);
-
                         // Grab the value from the split token, otherwise go for the next token
                         let argValueBeforeParse = '';
                         if (rawArgValue) {
                             argValueBeforeParse = rawArgValue;
-                        } else {
+                        }
+                        else {
                             argValueBeforeParse = rawArgs.at(++i) ?? '';
                             if (!argValueBeforeParse || argValueBeforeParse.startsWith('--')) {
                                 throw new Error(`Missing value for --${rawArgName}`);
                             }
                         }
-
                         const spec = config.namedArgs[rawArgName];
-                        parsedNamedArgs[rawArgName as keyof typeof parsedNamedArgs] = CLI.parseStringArg(argValueBeforeParse, rawArgName, spec) as ValueOf<typeof parsedNamedArgs>;
-                    } else {
+                        parsedNamedArgs[rawArgName] = CLI.parseStringArg(argValueBeforeParse, rawArgName, spec);
+                    }
+                    else {
                         console.error(`Unknown flag: --${rawArgName}`);
                         process.exit(1);
                     }
-                } else {
+                }
+                else {
                     // Arg is a positional arg
                     const spec = config.positionalArgs?.at(positionalIndex);
                     if (spec === undefined) {
@@ -230,7 +62,7 @@ class CLI<TConfig extends CLIConfig> {
                     }
                     if (spec.variadic) {
                         // Variadic: collect this and all remaining non-flag args into an array
-                        const collected: string[] = [];
+                        const collected = [];
                         for (let j = i; j < rawArgs.length; j++) {
                             const remaining = rawArgs.at(j);
                             if (remaining === undefined || remaining.startsWith('--')) {
@@ -238,22 +70,20 @@ class CLI<TConfig extends CLIConfig> {
                             }
                             collected.push(remaining);
                         }
-                        parsedPositionalArgs[spec.name as keyof typeof parsedPositionalArgs] = collected as ValueOf<typeof parsedPositionalArgs>;
+                        parsedPositionalArgs[spec.name] = collected;
                         break;
                     }
-                    parsedPositionalArgs[spec.name as keyof typeof parsedPositionalArgs] = CLI.parseStringArg(rawArg, spec.name, spec) as ValueOf<typeof parsedPositionalArgs>;
+                    parsedPositionalArgs[spec.name] = CLI.parseStringArg(rawArg, spec.name, spec);
                     positionalIndex++;
                 }
             }
-
             // Handle help command
             if (this.flags.help) {
                 this.printHelp();
                 process.exit(0);
             }
-
             // Handle supersession logic
-            const supersededArgs = new Set<string>();
+            const supersededArgs = new Set();
             for (const [name, spec] of Object.entries(config.namedArgs ?? {})) {
                 if (providedNamedArgs.has(name) && spec.supersedes) {
                     for (const supersededArg of spec.supersedes) {
@@ -264,42 +94,46 @@ class CLI<TConfig extends CLIConfig> {
                     }
                 }
             }
-
             // Validate that all required args are present, assign defaults where values are not parsed
             for (const [name, spec] of Object.entries(config.namedArgs ?? {})) {
                 if (name in parsedNamedArgs) {
                     if (supersededArgs.has(name)) {
-                        parsedNamedArgs[name as keyof typeof parsedNamedArgs] = undefined as ValueOf<typeof parsedNamedArgs>;
+                        parsedNamedArgs[name] = undefined;
                     }
-                } else if (supersededArgs.has(name)) {
+                }
+                else if (supersededArgs.has(name)) {
                     // This arg was superseded, so don't require it and don't assign a default
                     continue;
-                } else if (spec.default !== undefined) {
-                    parsedNamedArgs[name as keyof typeof parsedNamedArgs] = spec.default as ValueOf<typeof parsedNamedArgs>;
-                } else if (spec.required === false) {
+                }
+                else if (spec.default !== undefined) {
+                    parsedNamedArgs[name] = spec.default;
+                }
+                else if (spec.required === false) {
                     // Explicitly marked as optional, leave undefined
                     continue;
-                } else {
+                }
+                else {
                     // Arguments without defaults are required by default (unless explicitly marked as optional)
                     throw new Error(`Missing required named argument --${name}`);
                 }
             }
-
             for (const spec of config.positionalArgs ?? []) {
                 if (!(spec.name in parsedPositionalArgs)) {
                     if (spec.default !== undefined) {
-                        parsedPositionalArgs[spec.name as keyof typeof parsedPositionalArgs] = spec.default as ValueOf<typeof parsedPositionalArgs>;
-                    } else if (spec.variadic) {
-                        parsedPositionalArgs[spec.name as keyof typeof parsedPositionalArgs] = [] as ValueOf<typeof parsedPositionalArgs>;
-                    } else {
+                        parsedPositionalArgs[spec.name] = spec.default;
+                    }
+                    else if (spec.variadic) {
+                        parsedPositionalArgs[spec.name] = [];
+                    }
+                    else {
                         throw new Error(`Missing required positional argument --${spec.name}`);
                     }
                 }
             }
-
-            this.namedArgs = parsedNamedArgs as typeof this.namedArgs;
-            this.positionalArgs = parsedPositionalArgs as unknown as typeof this.positionalArgs;
-        } catch (err) {
+            this.namedArgs = parsedNamedArgs;
+            this.positionalArgs = parsedPositionalArgs;
+        }
+        catch (err) {
             // If help flag was set, the error is from process.exit(0) in tests (where it's mocked to throw) - just rethrow it
             if (this.flags.help) {
                 throw err;
@@ -307,29 +141,27 @@ class CLI<TConfig extends CLIConfig> {
             if (err instanceof Error) {
                 console.error(err.message);
                 this.printHelp();
-            } else {
+            }
+            else {
                 console.error('An unexpected error occurred initializing the CLI.');
             }
             process.exit(1);
         }
     }
-
-    private printHelp(): void {
-        const {flags = {}, namedArgs = {}, positionalArgs = []} = this.config;
+    printHelp() {
+        const { flags = {}, namedArgs = {}, positionalArgs = [] } = this.config;
         const scriptName = process.argv.at(1) ?? 'script.ts';
         const positionalUsage = positionalArgs
             .map((arg) => {
-                const label = arg.variadic ? `${arg.name}...` : arg.name;
-                return arg.default === undefined ? `<${label}>` : `[${label}]`;
-            })
+            const label = arg.variadic ? `${arg.name}...` : arg.name;
+            return arg.default === undefined ? `<${label}>` : `[${label}]`;
+        })
             .join(' ');
         const namedArgUsage = Object.keys(namedArgs)
             .map((key) => `[--${key} <value>]`)
             .join(' ');
         const flagUsage = [...Object.keys(flags), '--yes', '--no', '--help'].map((key) => `[${key.startsWith('--') ? key : `--${key}`}]`).join(' ');
-
         console.log(`\nUsage: npx ts-node ${scriptName} ${flagUsage} ${namedArgUsage} ${positionalUsage}\n`);
-
         console.log('Flags:');
         for (const [name, spec] of Object.entries(flags)) {
             console.log(`  --${name.padEnd(20)} ${spec.description}`);
@@ -339,7 +171,6 @@ class CLI<TConfig extends CLIConfig> {
         console.log(`  --${'no'.padEnd(20)} Automatically answer "no" to all confirmation prompts.`);
         console.log(`  --${'help'.padEnd(20)} Show this help message.`);
         console.log('');
-
         if (Object.keys(namedArgs).length > 0) {
             console.log('Named Arguments:');
             for (const [name, spec] of Object.entries(namedArgs)) {
@@ -349,7 +180,6 @@ class CLI<TConfig extends CLIConfig> {
             }
             console.log('');
         }
-
         if (positionalArgs.length > 0) {
             console.log('Positional Arguments:');
             for (const arg of positionalArgs) {
@@ -359,12 +189,12 @@ class CLI<TConfig extends CLIConfig> {
             console.log('');
         }
     }
-
-    private static parseStringArg<T extends StringArg>(rawString: string, paramName: string, spec: T): InferStringArgParsedValue<T> {
+    static parseStringArg(rawString, paramName, spec) {
         if ('parse' in spec && !!spec.parse) {
             try {
-                return spec.parse(rawString) as InferStringArgParsedValue<T>;
-            } catch (error) {
+                return spec.parse(rawString);
+            }
+            catch (error) {
                 let errorMessage = '';
                 if (error instanceof Error) {
                     errorMessage = error.message;
@@ -372,17 +202,17 @@ class CLI<TConfig extends CLIConfig> {
                 console.error(`Invalid value for --${paramName}: ${errorMessage}`);
                 process.exit(1);
             }
-        } else {
-            return rawString as InferStringArgParsedValue<T>;
+        }
+        else {
+            return rawString;
         }
     }
-
     /**
      * Prompts the user for confirmation and returns true if they confirm (y/yes), false otherwise.
      * If --yes flag was passed, returns true immediately without prompting.
      * If --no flag was passed, returns false immediately without prompting.
      */
-    async promptUserConfirmation(message: string): Promise<boolean> {
+    async promptUserConfirmation(message) {
         // Check for built-in flags first
         if (this.flags.yes) {
             return true;
@@ -390,12 +220,10 @@ class CLI<TConfig extends CLIConfig> {
         if (this.flags.no) {
             return false;
         }
-
         const rl = readline.createInterface({
             input: process.stdin,
             output: process.stdout,
         });
-
         return new Promise((resolve) => {
             rl.question(message, (answer) => {
                 rl.close();
@@ -405,5 +233,4 @@ class CLI<TConfig extends CLIConfig> {
         });
     }
 }
-
 export default CLI;

package/dist/esm/SafeString.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SafeString is a utility function that converts a value to a string.
+ * It handles the problematic case of plain objects by converting them to JSON.
+ * It helps with eslint rule https://typescript-eslint.io/rules/no-base-to-string
+ * @param value - The value to convert to a string.
+ * @returns The string representation of the value.
+ */
+export default function SafeString(value: unknown): string;

package/{lib/SafeString.ts → dist/esm/SafeString.js}

@@ -5,50 +5,45 @@
  * @param value - The value to convert to a string.
  * @returns The string representation of the value.
  */
-export default function SafeString(value: unknown): string {
+export default function SafeString(value) {
     if (value === undefined || value === null) {
         return '';
     }
-
     // Handle primitives explicitly so the final fallback never receives an object.
     const valueType = typeof value;
     if (valueType === 'string') {
-        return value as string;
+        return value;
     }
     if (valueType === 'number' || valueType === 'boolean' || valueType === 'function' || valueType === 'bigint' || valueType === 'symbol') {
-        const primitive = value as number | boolean | Function | bigint | symbol;
+        const primitive = value;
         return String(primitive);
     }
-
     if (valueType === 'object') {
         if (Array.isArray(value)) {
             try {
                 return JSON.stringify(value);
-            } catch {
+            }
+            catch {
                 return '[object Array]';
             }
         }
-
-        const obj = value as {toString: () => string};
+        const obj = value;
         const hasCustomToString = obj.toString && obj.toString !== Object.prototype.toString;
         if (hasCustomToString) {
             return obj.toString();
         }
-
         if (value instanceof Map) {
             return '[object Map]';
         }
-
         if (value instanceof Set) {
             return '[object Set]';
         }
-
         try {
             return JSON.stringify(obj);
-        } catch {
+        }
+        catch {
             return '[object Object]';
         }
     }
-
     return '';
 }

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "module"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expensify-common",
-  "version": "2.0.187",
+  "version": "2.0.188",
   "author": "Expensify, Inc.",
   "description": "Expensify libraries and components shared across different repos",
   "homepage": "https://expensify.com",
@@ -14,14 +14,14 @@
       "default": "./dist/index.js"
     },
     "./CLI": {
-      "types": "./lib/CLI.ts",
-      "default": "./lib/CLI.ts"
+      "types": "./dist/CLI.d.ts",
+      "import": "./dist/esm/CLI.js",
+      "require": "./dist/CLI.js",
+      "default": "./dist/esm/CLI.js"
     }
   },
   "files": [
     "dist/**/*",
-    "lib/CLI.ts",
-    "lib/SafeString.ts",
     "API.md",
     "README.md",
     "LICENSE.md"
@@ -29,7 +29,7 @@
   "scripts": {
     "grunt": "grunt",
     "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.build.json && cp ./lib/*.d.ts ./dist",
+    "build": "tsc -p tsconfig.build.json && cp ./lib/*.d.ts ./dist && tsc -p tsconfig.cli.cjs.json && tsc -p tsconfig.cli.esm.json && cp ./lib/esm-package.json ./dist/esm/package.json",
     "test": "jest",
     "lint": "eslint lib/ __tests__/",
     "prettier": "prettier --write lib/ __tests__/",
@@ -101,6 +101,9 @@
     ]
   },
   "jest": {
-    "testEnvironment": "jsdom"
+    "testEnvironment": "jsdom",
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    }
   }
 }