first release, v1.1.0

Author: webdiscus

CHANGELOG.md

@@ -1,17 +1,22 @@
 # Changelog
 
-## 0.1.0-alpha.0 (2025-07-03)
+## 1.1.0 (2025-07-04)
 
-- feat: optimize npm package for smaller size: 12kB -> 5kB
+- first stable release
+- feat: rename options for compatibility to yargs-parser options
+- feat: optimize npm package for smaller size: 12kB -> ~5kB
 - feat: add d.ts file
 - refactor: refactor code, add more comments
 - chore: add rollup to build clean npm package
+- test: add CI workflow via GitHub actions
 - docs: improve readme
 
+## 1.0.0 (2025-07-04) UNPUBLISHED as not ready for release
+
 ## 0.0.2 (2025-07-02)
 
 - fix: resolving files in package.json for CommonJS
 
-## 0.0.1 (2025-07-01)
+## 0.0.1 (2025-07-01) UNPUBLISHED as experimental not working version
 
-- feat: create small and fast CLI flag parser with supports of all base formats
+- chore(experimental): create small and fast CLI flag parser as lightweight alternative to yargs-parser

README.md

@@ -19,8 +19,8 @@ Supports all standard CLI flag formats.
 - Long boolean flag: `--flag`
 - Long flag with value: `--key=value` or `--key value`
 - Dashed long flag: `--foo-bar` (available as both `flags['foo-bar']` and `flags.fooBar`)
-- Multi-value keys: `--files a.js b.js`
-- Short-to-long aliases: `-f` = `--files`
+- Multi-values: `--files a.js b.js`
+- Short-to-long alias: `-f` = `--files`
 - Positional arguments and `--` terminator: `cmd -a --key=foo file1.txt -- file2.txt`
 - Default values for flags
 
@@ -53,9 +53,9 @@ console.log(flags);
 ```js
 const flags = getFlags({
   // argv: process.argv.slice(2), // parses by default
-  aliases: { f: 'files', l: 'limit' }, // -f = --files, -l = --limit
-  arrays: ['files'], // collect multiple values for --files and -f
-  defaults: { type: 'yaml', verbose: false } // default values if not set in CLI
+  alias: { f: 'files', l: 'limit' }, // -f = --files, -l = --limit
+  array: ['files'], // collect multiple values for --files and -f
+  default: { type: 'yaml', verbose: false } // default values if not set in CLI
 });
 
 console.log(flags);
@@ -90,19 +90,19 @@ Result:
 
 ## Options
 
-| Option     | Type       | Default                  | Description                                                   |
-|------------|------------| ------------------------ |---------------------------------------------------------------|
-| `argv`     | string[]   | `process.argv.slice(2)`  | Array of CLI arguments to parse                               |
-| `aliases`  | Object     | `{}`                     | Map of short keys to long keys.<br>Example: `{ f: 'files' }`  |
-| `arrays`   | string[]   | `[]`                     | Keys that should collect multiple values as arrays            |
-| `defaults` | Object     | `{}`                     | Default values for flags, if not set on the CLI               |
+| Option     | Type       | Default                  | Description                                                  |
+|------------|------------| ------------------------ |--------------------------------------------------------------|
+| `argv`     | string[]   | `process.argv.slice(2)`  | Array of CLI arguments to parse                              |
+| `alias`    | Object     | `{}`                     | Map of short keys to long keys.<br>Example: `{ f: 'files' }` |
+| `array`    | string[]   | `[]`                     | Keys that should collect multiple values as array            |
+| `default`  | Object     | `{}`                     | Default values for flags, if not set on the CLI              |
 
 **Notes**
 
 - All dashed keys are also available as camelCase (e.g. `--foo-bar` sets both `foo-bar` and `fooBar`).
-- Use the `aliases` option to map short flags to long names.
-- Specify keys in `arrays` to collect an array of multi-values.
-- Use the `defaults` option for fallback values.
+- Use the `alias` option to map short flags to long names.
+- Specify keys in `array` to collect an array of multi-values.
+- Use the `default` option for fallback values.
 
 
 ## Examples

README.npm.md

@@ -2,7 +2,7 @@
   <img width="400" src="docs/logo.png" alt="Flaget">
 </h1>
 
-Minimal, fast CLI flag parser for Node.js.
+Small and fast CLI flag parser for Node.js.
 Supports all standard CLI flag formats.
 
 ## Features
@@ -13,8 +13,8 @@ Supports all standard CLI flag formats.
 - Long boolean flag: `--flag`
 - Long flag with value: `--key=value` or `--key value`
 - Dashed long flag: `--foo-bar` (available as both `flags['foo-bar']` and `flags.fooBar`)
-- Multi-value keys: `--files a.js b.js`
-- Short-to-long aliases: `-f` = `--files`
+- Multi-values: `--files a.js b.js`
+- Short-to-long alias: `-f` = `--files`
 - Positional arguments and `--` terminator: `cmd -a --key=foo file1.txt -- file2.txt`
 - Default values for flags
 

index.d.ts

@@ -2,17 +2,17 @@
  * Parses CLI arguments into a flags object.
  *
  * @param options
- * @param options.argv The arguments to parse (defaults to process.argv.slice(2)).
- * @param options.aliases Map of short keys to long keys, e.g. { f: 'files' }.
- * @param options.arrays Keys that should collect multiple values.
- * @param options.defaults Map of default values.
+ * @param options.argv The arguments to parse (defaults is process.argv.slice(2)).
+ * @param options.alias Map of short keys to long keys, e.g. { f: 'files' }.
+ * @param options.array Keys that should collect multiple values.
+ * @param options.default Map of default values.
  * @returns Parsed flags object.
  */
 declare function getFlags(options?: {
   argv?: string[];
-  aliases?: Record<string, string>;
-  arrays?: string[];
-  defaults?: Record<string, unknown>;
+  alias?: Record<string, string>;
+  array?: string[];
+  default?: Record<string, unknown>;
 }): {
   [key: string]: string | number | boolean | Array<string | number | boolean> | undefined;
   _: string[];

package.json

@@ -1,12 +1,13 @@
 {
   "name": "flaget",
-  "version": "0.1.0-alpha.0",
-  "description": "Small, fast CLI flag parser for Node.js, supported all standard CLI flag formats.",
+  "version": "1.1.0",
+  "description": "Small CLI flag parser for Node.js supporting all standard flag formats.",
   "keywords": [
     "cli",
-    "flags",
+    "flag",
     "parser",
-    "command-line",
+    "argument",
+    "argv",
     "args"
   ],
   "license": "ISC",

package.npm.json

@@ -1,12 +1,13 @@
 {
   "name": "flaget",
-  "version": "0.1.0-alpha.0",
-  "description": "Small, fast CLI flag parser",
+  "version": "1.1.0",
+  "description": "Small CLI flag parser supporting all standard formats.",
   "keywords": [
     "cli",
-    "flags",
+    "flag",
     "parser",
-    "command-line",
+    "argument",
+    "argv",
     "args"
   ],
   "license": "ISC",

rollup.config.js

@@ -39,12 +39,13 @@ const terserMinifyOptions = (ecma) => ({
 });
 
 const terserPrettyOptions = (ecma) => ({
-  compress: false, // disables code compression/minification
-  mangle: false, // disables name mangling (shortening)
+  compress: false,
+  mangle: false, // disables name shortening
   format: {
+    comments: false,
     beautify: true, // pretty output (optional, for better readability)
     indent_level: 2, // force 2-space indentation
-  }
+  },
 });
 
 /**
@@ -79,18 +80,17 @@ function removeEmptyLines(input, replacement = '') {
 }
 
 /**
- * Rollup plugin to replace space indents to tabs.
- *
- * @param {number} spacesPerTab Number of spaces per tab (default 2).
- * @return {{name: string, generateBundle(*, *): void}}
+ * Rollup plugin that applies a user transform function to code.
+ * @param {(code: string, file: object) => string} transform A function to transform code.
+ * @returns {import('rollup').Plugin}
  */
-function spacesToTabsPlugin(spacesPerTab = 2) {
+function transform(transform) {
   return {
-    name: 'spaces-to-tabs',
+    name: 'plugin-transform',
     generateBundle(options, bundle) {
       for (const file of Object.values(bundle)) {
-        if (file.type === 'chunk') {
-          file.code = indentSpacesToTabs(file.code, spacesPerTab);
+        if (file.type === 'chunk' && typeof transform === 'function') {
+          file.code = transform(file.code, file);
         }
       }
     }
@@ -125,7 +125,15 @@ function buildConfig({ output, ecma }) {
     plugins: [
       ...(ecma < 2020 ? [babel(babelOptions)] : []),
       terser(terserPrettyOptions(ecma)),
-      spacesToTabsPlugin(),
+      transform((code) => {
+        return indentSpacesToTabs(code, 2)
+          // remove needles destructed variables after terser
+          .replaceAll('argv: argv', 'argv')
+          .replaceAll('alias: alias', 'alias')
+          .replaceAll('array: array', 'array')
+          .replaceAll('flags: flags', 'flags')
+          .replaceAll('argOffset: argOffset', 'argOffset');
+      }),
       copy({
         targets: [
           {

src/getFlags.js

@@ -48,11 +48,11 @@ const setFlag = (flags, key, value) => {
 /**
  * Map an alias to its full key name if defined.
  * @param {string} key The key or alias to resolve.
- * @param {object} aliases The aliases mapping object.
+ * @param {object} alias The alias mapping object.
  * @returns {string} The resolved key.
  */
-const getKey = (key, aliases) => (
-  aliases[key] || key
+const getKey = (key, alias) => (
+  alias[key] || key
 );
 
 /**
@@ -82,17 +82,17 @@ const readMultiValues = (argv, startIndex, rawVal) => {
  * Parse a long flag argument (e.g., --key or --key=value).
  * @param {string} arg The argument to parse.
  * @param {number} index The current argv index.
- * @param {object} context Parsing context (argv, aliases, arrays, flags).
+ * @param {object} context Parsing context (argv, alias, array, flags).
  * @returns {number} The updated index.
  */
 const parseLongFlag = (arg, index, context) => {
-  const { argv, aliases, arrays, flags } = context;
+  const { argv, alias, array, flags } = context;
   const [rawKey, rawVal] = arg.includes('=')
     ? arg.slice(2).split('=')
     : [arg.slice(2)];
-  const key = getKey(rawKey, aliases);
+  const key = getKey(rawKey, alias);
 
-  if (arrays.includes(key)) {
+  if (array.includes(key)) {
     const { values, argOffset } = readMultiValues(argv, index, rawVal);
     setFlag(flags, key, (flags[key] || []).concat(values));
     return index + argOffset;
@@ -114,12 +114,12 @@ const parseLongFlag = (arg, index, context) => {
 /**
  * Parse grouped short flags (e.g., -abc -> -a -b -c).
  * @param {string} arg The argument to parse.
- * @param {object} context Parsing context (aliases, flags).
+ * @param {object} context Parsing context (alias, flags).
  */
 const parseShortGroup = (arg, context) => {
-  const { aliases, flags } = context;
+  const { alias, flags } = context;
   for (const char of arg.slice(1)) {
-    const key = getKey(char, aliases);
+    const key = getKey(char, alias);
     setFlag(flags, key, true);
   }
 };
@@ -128,17 +128,17 @@ const parseShortGroup = (arg, context) => {
  * Parse a single short flag (e.g., -f or -f value).
  * @param {string} arg The argument to parse.
  * @param {number} index The current argv index.
- * @param {object} context Parsing context (argv, aliases, arrays, flags).
+ * @param {object} context Parsing context (argv, alias, array, flags).
  * @returns {number} The updated index.
  */
 const parseShortFlag = (arg, index, context) => {
-  const { argv, aliases, arrays, flags } = context;
+  const { argv, alias, array, flags } = context;
   const short = arg[1];
-  const key = getKey(short, aliases);
+  const key = getKey(short, alias);
   const next = argv[index + 1];
   const isNextValue = next && !isFlag(next);
 
-  if (arrays.includes(key)) {
+  if (array.includes(key)) {
     const values = [];
     let i = index;
     while (argv[i + 1] && !isFlag(argv[i + 1])) {
@@ -159,19 +159,15 @@ const parseShortFlag = (arg, index, context) => {
  *
  * @param {object} [options] Parsing options.
  * @param {Array} [options.argv=process.argv.slice(2)] The argv array to parse.
- * @param {object} [options.aliases={}] Mapping of flag aliases.
- * @param {Array} [options.arrays=[]] Keys that should always produce arrays.
- * @param {object} [options.defaults={}] Default values for missing flags.
+ * @param {object} [options.alias={}] Mapping of flag alias.
+ * @param {Array} [options.array=[]] Keys that should always produce array.
+ * @param {object} [options.default={}] Default values for missing flags.
  * @returns {object} Parsed flags object.
  */
-const getFlags = ({
-  argv = process.argv.slice(2),
-  aliases = {},
-  arrays = [],
-  defaults = {},
-} = {}) => {
+const getFlags = (options = {}) => {
+  const { argv= process.argv.slice(2), alias= {}, array = []} = options;
   const flags = { _: [] };
-  const context = { argv, aliases, arrays, flags };
+  const context = { argv, alias, array, flags };
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -202,7 +198,7 @@ const getFlags = ({
   }
 
   // apply default values for missing flags
-  for (const [key, val] of Object.entries(defaults)) {
+  for (const [key, val] of Object.entries(options.default || {})) {
     if (!(key in flags)) {
       setFlag(flags, key, val);
     }

test/getFlags.test.js

@@ -79,7 +79,7 @@ describe('getFlags', () => {
     // example: cmd --tag a b --tag=c
     const result = getFlags({
       argv: ['--tag', 'a', 'b', '--tag=c'],
-      arrays: ['tag'],
+      array: ['tag'],
     });
     expect(result).toEqual({ tag: ['a', 'b', 'c'], _: [] });
   });
@@ -107,7 +107,7 @@ describe('getFlags', () => {
     // example: cmd --f val  (alias: f => foo)
     const result = getFlags({
       argv: ['--f', 'val'],
-      aliases: { f: 'foo' },
+      alias: { f: 'foo' },
     });
     expect(result).toEqual({ foo: 'val', _: [] });
   });
@@ -124,7 +124,7 @@ describe('getFlags', () => {
     // example: cmd --f a.js --file b.js  (alias: f => file), will be parsed latest value
     const result = getFlags({
       argv: ['-f', 'a.js', '--file', 'b.js'],
-      aliases: { f: 'file' },
+      alias: { f: 'file' },
     });
     expect(result).toEqual({ 'file': 'b.js', _: [] });
   });
@@ -133,8 +133,8 @@ describe('getFlags', () => {
     // example: cmd --f a.js --files b.js  (alias: f => files), collects all values
     const result = getFlags({
       argv: ['-f', 'a.js', '--files', 'b.js'],
-      aliases: { f: 'files' },
-      arrays: ['files'],
+      alias: { f: 'files' },
+      array: ['files'],
     });
     expect(result).toEqual({ 'files': ['a.js', 'b.js'], _: [] });
   });
@@ -143,9 +143,9 @@ describe('getFlags', () => {
     // example: cmd --f a.js --file b.js  (alias: f => file), will be parsed latest value
     const result = getFlags({
       argv: ['report', '-abc', '--type=json', '--dash-flag', 'value', '--force', '--cached=false', '-l', '20', '-f', 'a.js', 'b.js', '--files', 'c.js', 'd.js', '--', 'out.json'],
-      aliases: { f: 'files', l: 'limit' },
-      arrays: ['files'],
-      defaults: { type: 'yaml', verbose: false },
+      alias: { f: 'files', l: 'limit' },
+      array: ['files'],
+      default: { type: 'yaml', verbose: false },
     });
     expect(result).toEqual({
       'a': true,
@@ -171,11 +171,11 @@ describe('getFlags', () => {
     });
   });
 
-  test('apply defaults', () => {
+  test('apply default', () => {
     // example: cmd  (env=production by default)
     const result = getFlags({
       argv: [],
-      defaults: { env: 'production' },
+      default: { env: 'production' },
     });
     expect(result).toEqual({ env: 'production', _: [] });
   });