Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
typeFlag
✓ import typeFlag from 'type-flag'
✗ import { typeFlag } from 'type-flag'
The main parsing function is a default export. Since v5.0.0-beta.4, type-flag is ESM-only.
flagNameToKebab
✓ import { flagNameToKebab } from 'type-flag'
Utility function for converting camelCase to kebab-case, exported since v5.0.0-beta.6.
TypeFlag
✓ import type { TypeFlag } from 'type-flag'
Import the type for the return value of `typeFlag` for advanced type manipulation.
Demonstrates parsing various typed command-line flags including numbers, booleans, strings, arrays, and union types, using `type-flag` with a defined interface.
import typeFlag from 'type-flag';
interface MyCliArgs {
port: number;
host?: string;
verbose: boolean;
files: string[];
user: string | undefined;
'log-level': 'debug' | 'info' | 'warn' | 'error';
}
const argv = typeFlag<MyCliArgs>({
port: { type: Number, alias: 'p', default: 3000 },
host: { type: String, default: 'localhost' },
verbose: { type: Boolean, default: false },
files: { type: [String], alias: 'f', default: [] },
user: { type: String, optional: true },
'log-level': { type: String, default: 'info' as 'info' }
}, process.argv.slice(2));
console.log(`CLI Arguments Parsed:`);
console.log(`Port: ${argv.port} (Type: ${typeof argv.port})`);
console.log(`Host: ${argv.host ?? 'N/A'} (Type: ${typeof argv.host})`);
console.log(`Verbose: ${argv.verbose} (Type: ${typeof argv.verbose})`);
console.log(`Files: ${argv.files.join(', ')} (Type: ${typeof argv.files})`);
console.log(`User: ${argv.user ?? 'N/A'} (Type: ${typeof argv.user})`);
console.log(`Log Level: ${argv['log-level']} (Type: ${typeof argv['log-level']})`);
// Example usage with a placeholder for environment variables or direct values
// To run: `node your-script.ts --port 8080 -f file1.txt -f file2.ts --verbose --user 'dev' --log-level debug`
// Or: `ts-node your-script.ts --port 8080 -f file1.txt -f file2.ts --verbose --user 'dev' --log-level debug`
Debug
Known issues
breakingVersion 5.0.0-beta.4 and above drop CommonJS distribution and require Node.js 22.22.2 or higher. Users on older Node.js versions or those requiring CommonJS must stick to v4.x.fixMigrate your project to use ECMAScript Modules (ESM) and upgrade your Node.js environment to version 22.22.2 or later. Alternatively, remain on `type-flag@4.x` for CommonJS support.
affects: >=5.0.0-beta.4
breakingIn v5.0.0-beta.2, custom type parser errors are now wrapped in a TypeError, changing error messages from just `<message>` to `Flag "--<name>": <message>`. The original error is available via the `.cause` property.fixUpdate error handling logic for custom parsers to expect a `TypeError` wrapper. Access the original error message through `error.cause` if specific error types or messages are being checked.
affects: >=5.0.0-beta.2
breakingVersion 5.0.0-beta.1 introduced a change in how flag names with consecutive capitals are converted from camelCase to kebab-case. For instance, `getID` now maps to `--get-id` instead of `--get-i-d`.fixReview and update CLI argument calls if your application relies on specific kebab-case conversions for flags containing acronyms or consecutive uppercase characters. Adjust command-line invocations accordingly.
affects: >=5.0.0-beta.1
gotchaBoolean flags support the `--no-` prefix for negation (e.g., `--no-verbose` sets `verbose` to `false`). This behavior was introduced in v4.1.0 and v5.0.0-beta.3.fixBe aware of the `--no-` prefix for boolean flags. If you have custom logic expecting a different negation pattern or need to treat `--no-flag` as a distinct flag, adjust your schema or parsing logic.
affects: >=4.1.0, >=5.0.0-beta.3
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to `require()` type-flag v5.x, which is an ESM-only package.
fixChange your import statement to `import typeFlag from 'type-flag';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
TypeError: Cannot read properties of undefined (reading 'split')
Parsing arguments with `process.argv` but forgetting to slice off the first two elements (`node` executable and script path).
fixAlways pass `process.argv.slice(2)` to `typeFlag` to ensure only the actual command-line arguments are parsed.
Error: Flag "--my-flag": Value must be of type number.
Providing a non-numeric value for a flag explicitly typed as `Number` in the schema.
fixEnsure that the value provided for the flag matches the expected type defined in your `typeFlag` schema. For example, use `--port 8080` instead of `--port 'eighty'`. For custom types, verify your parser function.
Audit
Dependencies
No dependency data recorded yet.