util: parseArgs instead of string and boolean should handle all primitive data types

What is the problem this feature will solve?

In today's @nodejs/tooling WG meeting, we're discussing the parseArgs that the config supports only either boolean or string for parsing args.

nodejs/tooling#155

What is the feature you are proposing to solve the problem?

I'd like to open for discussion on whether we should support other primitive types such as numbers and complex types such as Streams.

There're some concerns about it but I think it will be worth it to hear what other people think about it

What alternatives have you considered?

No response

Just regarding numbers.

I assume when you say support for "numbers" you are thinking of it as as explicit type specified by the author, rather than auto-detection? (Both minimist and yargs have reported issues about automatic detection going wrong, some false positives of IDs, some due to overflow.)

Negative numbers clash with the ability to use a digit as an option, like ls -1. This means some compromises are needed to support negative numbers. There is some prior discussion in a PR that proposed one form of negative number support in pkgjs/parseargs#62

I'm comfortable with parseArgs staying simple and not supporting type conversions. (But I am also very comfortable reaching for a library when I need more!)

I don't think we should support streams or any other complex types. That's best left to userland.

type: "number" would have been a welcomed addition.
meow supports it.

Honestly, I don't understand the reasoning behind omitting the number type. It's every bit as commonly used as string and boolean. Without it, instead of just specifying a type, you have to manually convert all the values, which is extremely inconvenient.
I'd really like to hear the official rationale for why the number type was left out.

I'd really like to hear the official rationale for why the number type was left out.

Not official, but I helped implement parseArgs and turn the concept into a library.

Basically, "number type" is not necessary for a basic argument parser. We were focused on solid and safe. The core concepts are options which are used alone (aka type: 'boolean'), options which have an option-argument (aka type: 'string'), and arguments which are not options (allowPositionals: true).

"number type" sounds simple, and it is simple to (say) call parseFloat() and call it done. But what might you care about when you convert a number strictly?

integer vs float
partial non-numbers (e.g. 12foo)
non-numbers (e.g. bar)
numbers larger than can be represented in JavaScript number
floating point representation (e.g. 1e3)
positive only numbers (especially integers, like port number)
number ranges (0-100)
hex formats

@shadowspawn

Hi @shadowspawn, thanks for the clarification.
If this problem has already been solved in the neighboring ecosystem and in every well-known library, why not use them as a reference?

Here are my examples:

import argparse

# 1. Negative number as an OPTION VALUE: -a -42
parser = argparse.ArgumentParser()
parser.add_argument('-a', type=int)
args = parser.parse_args(['-a', '-42'])
print(args.a)  # -42

import argparse

# 2. Negative number as a POSITIONAL argument: -1
parser = argparse.ArgumentParser()
parser.add_argument('number', type=int)
args = parser.parse_args(['-1'])
print(args.number)  # -1

import argparse

# 3. Digit short option TAKES PRECEDENCE: -1 X
parser = argparse.ArgumentParser()
parser.add_argument('-1', dest='one')
parser.add_argument('foo', nargs='?')
args = parser.parse_args(['-1', 'X'])
print(args.one)  # X   (option -1 consumed X as its value)
print(args.foo)  # None (no positional left)

import argparse

# 4. POSIX '--' terminator: everything after -- is positional
parser = argparse.ArgumentParser()
parser.add_argument('-1', dest='one')
parser.add_argument('foo', nargs='?')
args = parser.parse_args(['--', '-1'])
print(args.foo)  # -1  (forced positional)
print(args.one)  # None (option -1 was not triggered)

import argparse

# 5. FLOAT vs INT: the caller CHOOSES the type explicitly
parser = argparse.ArgumentParser()
parser.add_argument('--scale', type=float)
args = parser.parse_args(['--scale', '1e3'])
print(args.scale)  # 1000.0

import argparse

# 6. PARTIAL non-numbers ('12foo') 
# FAIL with clear ValueError
parser = argparse.ArgumentParser()
parser.add_argument('--id', type=int)
try:
    args = parser.parse_args(['--id', '12foo'])
except SystemExit:
    pass
# Error: argument --id: invalid int value: '12foo'

import argparse

# 7. Pure non-numbers ('bar')
parser = argparse.ArgumentParser()
parser.add_argument('--id', type=int)
try:
    args = parser.parse_args(['--id', 'bar'])
except SystemExit:
    pass
# Error: --id: invalid int value: 'bar'

import argparse

# 8. ARBITRARY PRECISION integers — no overflow
parser = argparse.ArgumentParser()
parser.add_argument('--big', type=int)
args = parser.parse_args(['--big', '999999999999999999999'])
print(args.big)  # 999999999999999999999

import argparse

# 9. HEX / OCT / BIN formats
# custom transform via lambda
parser = argparse.ArgumentParser()
parser.add_argument('--addr', type=lambda x: int(x, 0))
args = parser.parse_args(['--addr', '0xFF'])
print(args.addr)  # 255

import argparse

# 10. POSITIVE-ONLY numbers (e.g., port)
# choices constrains the domain
parser = argparse.ArgumentParser()
parser.add_argument('--port', type=int, choices=range(1, 65536))
args = parser.parse_args(['--port', '8080'])
print(args.port)  # 8080

import argparse

# 11. STRICT RANGE (0-100)
# choices works for discrete integer ranges
parser = argparse.ArgumentParser()
parser.add_argument('--percent', type=int, choices=range(0, 101))
args = parser.parse_args(['--percent', '42'])
print(args.percent)  # 42

import argparse

# 12. CUSTOM TRANSFORM FUNCTION
def positive_int(value):
    ivalue = int(value)

    if ivalue <= 0:
        raise argparse.ArgumentTypeError(f"{value} must be positive")
    return ivalue

parser = argparse.ArgumentParser()
parser.add_argument('--workers', type=positive_int)
args = parser.parse_args(['--workers', '4'])
print(args.workers)  # 4

import {parseArgs} from 'util';

// 1. Negative number as an OPTION VALUE: -a -42
const example1 = parseArgs({
  options: {
    a: { type: 'number' }
  },
  args: ['-a', '-42']
});

console.log(example1.values); // { a: -42 }

// 2. Negative number as a POSITIONAL argument: -1
const example2 = parseArgs({
  allowPositionals: true,
  args: ['-1']
});

console.log(example2.positionals); // ['-1']

// 3. Digit short option TAKES PRECEDENCE: -1 X
const example3 = parseArgs({
  options: {
    1: { type: 'string' }
  },
  allowPositionals: true,
  args: ['-1', 'X']
});

console.log(example3.values); // { '1': 'X' }
console.log(example3.positionals); // []

// 4. POSIX '--' terminator: everything after -- is positional
const example4 = parseArgs({
  options: {
    1: { type: 'string' }
  },
  allowPositionals: true,
  args: ['--', '-1']
});

console.log(example4.positionals); // ['-1']
console.log(example4.values); // {}

// 5. FLOAT vs INT: the caller CHOOSES the type explicitly
const example5 = parseArgs({
  options: {
    scale: { type: (v) => parseFloat(v) }
  },
  args: ['--scale', '1e3']
});

console.log(example5.values); // { scale: 1000 }

// 6. PARTIAL non-numbers ('12foo') — FAIL
try {
  const example6 = parseArgs({
    options: {
      id: {
        type: (v) => {
          if (!/^\d+$/.test(v)) {
            throw new TypeError(`invalid number value: '${v}'`);
          }
          return parseInt(v, 10);
        }
      }
    },
    args: ['--id', '12foo']
  });
} catch (err) {
  console.log(err.message);  // invalid number value: '12foo'
}

// 7. Pure non-numbers ('bar') — failure

try {
  const example7 = parseArgs({
    options: {
      id: {
        type: (v) => {
          const n = parseInt(v, 10);
          if (isNaN(n)) {
            throw new TypeError(`invalid number value: '${v}'`);
          }
          return n;
        }
      }
    },
    args: ['--id', 'bar']
  });
} catch (err) {
  console.log(err.message);  // invalid number value: 'bar'
}

// 8. ARBITRARY PRECISION integers
const example8 = parseArgs({
  options: {
    big: { type: BigInt }
  },
  args: ['--big', '999999999999999999999']
});

console.log(example8.values); // { big: 999999999999999999999n }

// 9. HEX / OCT / BIN formats — custom transform via lambda
const example9 = parseArgs({
  options: {
    addr: { type: (v) => parseInt(v, 0) }
  },
  args: ['--addr', '0xFF']
});

console.log(example9.values); // { addr: 255 }


// 10. POSITIVE-ONLY numbers (e.g., port) — choices constrains the domain
// The parser rejects out-of-range values before your code runs.

const example10 = parseArgs({
  options: {
    port: {
      type: 'number',
      choices: Array.from({ length: 65535 }, (_, i) => i + 1)
    }
  },
  args: ['--port', '8080']
});

console.log(example10.values);
// { port: 8080 }


// 11. STRICT RANGE (0-100)
const example11 = parseArgs({
  options: {
    percent: {
      type: 'number',
      choices: Array.from({length: 101}, (_, i) => i)
    }
  },
  args: ['--percent', '42']
});

console.log(example11.values); // { percent: 42 }


// 12. CUSTOM TRANSFORM FUNCTION

function positiveInt(value) {
  const n = parseInt(value, 10);

  if (isNaN(n) || n <= 0) {
    throw new TypeError(`${value} must be positive`);
  }

  return n;
}

const example12 = parseArgs({
  options: {
    workers: { type: positiveInt }
  },
  args: ['--workers', '4']
});

console.log(example12.values); // { workers: 4 }

I may have missed something, but as of today util.parseArgs doesn't even expose choices or transform / custom type functions to work around the missing number type. Without those, users are left with zero built-in tools and forced to do raw string post-processing on every single call site.

https://npmjs.com/pargs is my parseArgs wrapper that adds enum, number, and integer types, along with some other handy things, if that's helpful.

Navigation Menu

Repository navigation

util: parseArgs instead of string and boolean should handle all primitive data types #44484

What is the problem this feature will solve?

What is the feature you are proposing to solve the problem?

What alternatives have you considered?

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

util: parseArgs instead of string and boolean should handle all primitive data types #44484

Description

What is the problem this feature will solve?

What is the feature you are proposing to solve the problem?

What alternatives have you considered?

Activity

shadowspawn commented on Sep 3, 2022

mcollina commented on Sep 4, 2022

Mouvedia commented on Oct 3, 2024

monolithed commented on Aug 28, 2026

shadowspawn commented on Aug 28, 2026

monolithed commented on Aug 28, 2026

ljharb commented on Aug 29, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions