Parser catalog¶

Parsers are opt‑in, manual, and explicit rules that convert a normalized value into a meaningful, typed value. Parsing is the stage where semantics enter the pipeline.

Parsers:

never run automatically
never guess or coerce
never validate
never normalize
emit events describing success or failure
run in the order you specify
produce the value that validators operate on

Parsing answers the question: Given this raw value, what does it mean?

Parsers are the bridge between structural cleanup (normalization) and semantic enforcement (validation).

How Parsing Works¶

Normalization produces a clean structural value: Parsers always receive the normalized value.
Parsers run in the order you specify: Each call to .parse(...) adds a parser to the pipeline:

ts jane.value(" 42 ") .parse("numericString") .parse("port") // hypothetical second parser .run();

While it is technically possible to chain parsers, this approach is not recommended and may lead to untested behavior.
Each parser returns either:
- A new typed value.
- A parse failure event.
Policy interprets parse events

Policy decides whether parse failures:
- Reject the pipeline
- Downgrade to warnings
- Trigger review
Parsers never decide acceptance on their own.

Parser Categories¶

Parsers are grouped by the type of value they produce.

Each section includes:

A description of the parser category.
The parsers in that category.
Cross‑links to related normalization and validation rules.

This helps developers understand how parsing fits into the full pipeline.

String‑to‑Number Parsers¶

parseNumericString:

.parse("numeric")

Converts a numeric string into a JavaScript number.
Rejects malformed or ambiguous numeric strings.

String‑to‑Boolean Parsers¶

parseBooleanString:

.parse("boolean")

Converts "true" and "false" into booleans.
Rejects anything else.

String‑to‑Bigint Parsers¶

These parsers convert string representations of integers into JavaScript BigInt values.

paresBigintString:

.parse("bigint")

Parses canonical decimal BigInt strings.

parseHexString:

.parse("hex")

Parses hexadecimal BigInt strings.

parseBinary:

.parse("binary")

Parses binary BigInt strings.

parseOctal:

.parse("octal")

Parses octal BigInt strings.

String‑to‑Date Parsers¶

parseIsoDate:

.parse("date")

Parses ISO‑8601 date strings into Date objects.
Rejects invalid or ambiguous formats.

String‑to‑JSON Parsers¶

parseJson:

.parse("json")

Safely parses JSON strings into objects or arrays.
Never throws — always emits structured events.

String‑to‑Array Parsers¶

parseArray:

.parse("array")

String‑to‑Object Parsers¶

parseObject:

.parse("object")

Parses a string representation of an object (for example, "{"a":1}") into a JavaScript object.

String‑to‑URL Parsers¶

parseUrl

.parse("url")

Parses a string into a URL instance.
Rejects invalid URLs.

Example: Numeric String Parser¶

export const parseNumericString: ParseRule<string, number> = (value, path) => {
    if (typeof value !== "string") return [];

    const trimmed = value.trim();
    if (!/^-?\d+(\.\d+)?$/.test(trimmed)) {
        return [
            parseEvent(
                'error',
                'parse.numericString.invalid',
                path,
                'Expected a numeric string.',
                'Please enter a valid number.',
                { received: value }
            )
        ];
    }

    return [
        {
            path,
            nextValue: Number(trimmed),
            events: [
                parseEvent(
                    'info',
                    'parse.numericString.success',
                    path,
                    'Parsed numeric string.',
                    'Value was interpreted as a number.',
                    { before: value, after: Number(trimmed) }
                )
            ]
        }
    ];
};

This illustrates the parser contract:

Check applicability.
Validate the string format.
Produce a typed value.
Emit structured events.
Never mutate the original value.

Summary¶

Parsers are the semantic interpretation stage of the Jane pipeline. They convert normalized values into typed values that validators can operate on. Parsers are:

Opt‑in: Nothing runs unless you call .parse()
Manual: You choose the parser and its order
Pure: No mutation, no coercion
Event‑emitting: Every success or failure is recorded
Policy‑interpreted: Parsers never reject on their own

Parsing is the moment where raw input becomes meaningful data — explicitly, predictably, and transparently.