Skip to content

Parse duration string

parseDurationString parses duration literals of the form <number><unit> into structured duration objects.

It accepts only strict, unambiguous formats and rejects any partial, spaced, or compound forms. If the value is not a string, does not match the duration pattern, or contains an unsupported unit, the rule emits no parse result.

Signature

Through the API:

.parse('duration');

And internally:

export const parseDurationString: ParseRule<unknown>
(value: unknown, path: FieldPath) => ParseResult<unknown>[]

Events

Event code Description
string.now.duration Parsed string into a duration object.

Design rationale

  • Accepts only canonical duration literals:
  • Integer amount (positive or negative).
  • Exactly one unit: s, m, h, or d.
  • No whitespace, separators, decimals, or compound units,
  • Rejects ambiguous formats such as "10 ms", "1h30m", "1.5h", " 5s ", or "5 S".
  • Produces a structured duration object with a single key (seconds, minutes, hours, or days).
  • Emits a single parse step containing the parsed object and one parseEvent.
  • Never guesses or normalizes — parsing is explicit and opt‑in.

Invoke

parseDurationString runs only when explicitly included in a boundary or pipeline. It is not affected by normalization mode and does not run automatically.

The rule activates when:

  • The value is a string.
  • The string matches the strict duration pattern: /^(-?\d+)([smhd])$/.
  • The unit maps cleanly to a duration field.

Examples

Valid duration strings

parseDurationString("10s", "$");
// → [
//     {
//       path: "$",
//       nextValue: { seconds: 10 },
//       events: [
//         JaneEvent{ kind: "info", code: "string.now.duration", ... }
//       ]
//     }
//   ]

parseDurationString("-3h", "$");
// → [
//     {
//       path: "$",
//       nextValue: { hours: -3 },
//       events: [ JaneEvent{ code: "string.now.duration", ... } ]
//     }
//   ]

Invalid formats — no parse

parseDurationString("1h30m", "$");   // → []
parseDurationString("10 ms", "$");   // → []
parseDurationString("1.5h", "$");    // → []
parseDurationString("5 S", "$");     // → []
parseDurationString("days", "$");    // → []

Non‑string value

parseDurationString(42, "$"); // → []