#typescript/src/values

#typescript/src/values

Value engine: strict scalar parsing (bool/int/float), choices matching, error-message value formatting, and compound (list/dict) parsing.

Behavior is pinned to the siblings (go/strictcli/parse.go and Python __init__.py); where they diverge, the conformance suite is the oracle, and where the oracle is silent, dict parsing follows Python (the captured ground truth for divergences -- see conformance/check_error_parity.py exclusions) while numeric acceptance follows Go (the stricter side).

All message templates come from the errors.ts catalog, including the Python-wording dict and positional-arg templates (their dedicated "values.ts" sections there carry the divergence notes).

#parseBoolStrict

export function parseBoolStrict(s: string): boolean

Strict boolean parse: 1|true|yes -> true, 0|false|no -> false (case-insensitive). Everything else is a ParseError.

#parseIntStrict

export function parseIntStrict(s: string): bigint

Strict integer parse to bigint with signed-64-bit bounds.

#parseFloatStrictValue

export function parseFloatStrictValue(s: string): number

Strict float parse: rejects surrounding whitespace, NaN, +/-Inf (by name and by overflow -- Go rejects "1e400" as out of range; Python lets it become inf, violating the cross-language "floats reject Inf" rule, so the Go behavior wins).

#parseFloatStrictFlag

export function parseFloatStrictFlag(flagName: string, raw: string): number

Float parse with flag-contextualized messages: NaN/Inf messages pass through under the "--flag: " prefix; every other failure becomes "--flag: expected float, got ''".

#coerceToScalar

export function coerceToScalar(

Coerces a raw string to a scalar schema with "--flag: " error context. For str, resolves the @-prefix when a stdin tracker is provided (CLI and env values resolve it; config values and args do not).

#coerceArgValue

export function coerceArgValue(

Coerces a raw positional-arg string with "argument '': " error context. No @-prefix resolution on args, matching the siblings.

#formatValueForError

export function formatValueForError(value: unknown): string

Formats a value for error messages (without quotes): bools lowercase, floats in SCF (always a decimal point), dicts as sorted key=value pairs.

#formatDictForDisplay

export function formatDictForDisplay(m: ReadonlyMap<string, unknown>): string

Renders a dict value as canonical deterministic text: keys sorted ascending, "key=value" pairs joined by ", " (mirroring the CLI input syntax), values via formatValueForError.

#formatChoices

export function formatChoices(choices: readonly unknown[]): string

#validateChoices

export function validateChoices(

Validates a resolved value against declared choices. A missing value (undefined/null) is exempt: it only arises from an explicitly-optional flag or an unset mutex flag, never from a CLI-supplied value. Repeatable values validate element-wise.

#findDuplicate

export function findDuplicate(values: readonly unknown[]): unknown

Returns the first duplicate value, or undefined if all elements are unique. SameValueZero semantics match the siblings' equality for the scalar element types (str/int/float; -0 equals 0, NaN cannot occur).

#appendListValue

export function appendListValue(

Appends a coerced element to a list flag's accumulated values, enforcing unique semantics after the append (the duplicate check sees the whole accumulated list, matching Go's storeValue closure).

#splitEscaped

export function splitEscaped(value: string, sep: string): string[]

Splits value on sep, treating backslash as escape character. Escaped sep becomes literal sep. All other backslash sequences (escaped backslash, backslash before any other char, trailing backslash) are preserved exactly as the siblings preserve them.

#parseDictValue

export function parseDictValue(

Parses one dict flag occurrence from the CLI: either "key=value" (split on the first "="), or a JSON object when the raw value starts with "{" (no leading-whitespace tolerance, matching Python). Returns the parsed entries in input order; duplicate keys within one JSON object are last-wins (JSON.parse semantics, same as Python's json.loads).

#storeDictEntries

export function storeDictEntries(

Merges parsed entries into a dict flag's accumulated value. A key already present from an earlier occurrence is a hard error (Python semantics; check_error_parity.py records Go's silent-overwrite as the excluded side).

#parseDictEnvValue

export function parseDictEnvValue(

Parses a dict flag's env var value, which must be a whole JSON object. Coercion errors carry the same messages as the CLI JSON path (no env suffix), matching Python.