parseTimeWithPattern

Signature

parseTimeWithPattern(value: string, pattern: string, locale?: string): string

import { parseTimeWithPattern } from "@northguild/gmt/plain/parse";

Parse a time string against a caller-supplied token pattern (e.g.

• "HH:mm:ss", "h:mm a") and return it as an ISO PlainTime string.
• Decoding, not display. This is for consuming a known, fixed producer format — a CSV column, a legacy API field, a partially-typed form value — not for generating locale-correct output. For display, use formatTime/formatDateToParts, which order fields per locale instead of hard-coding a field order (see roadmap Decision 1 — a token formatter, the inverse of this function, is deliberately out of scope for GMT).
• pattern accepts only time-shaped tokens. A pattern containing a date-only token (y M d E G) is malformed for this function and returns "" — use parseDateTimeWithPattern for combined input. ### Token table | Token | Field | Width | Range | Notes | |—|—|—|—|—| | HH | hour (24h) | 2 digits | 00–23 | | | H | hour (24h) | 1-2 digits | 0–23 | | | hh | hour (12h) | 2 digits | 01–12 | needs a to resolve to 24h — see below | | h | hour (12h) | 1-2 digits | 1–12 | same | | mm | minute | 2 digits | 00–59 | | | m | minute | 1-2 digits | 0–59 | | | ss | second | 2 digits | 00–59 | | | s | second | 1-2 digits | 0–59 | | | SSS | millisecond | 3 digits | 000–999 | | | a | meridiem | locale | — | getLocaleMeridiems(locale) → [AM-label, PM-label] |
• Text in 'single quotes' is a literal; a doubled '' inside a quoted segment is a literal '. Any other character (: , space, literal digits, etc.) outside a quote/letter-run is automatically a literal — no explicit quoting required.
• a is locale-aware. If locale is omitted and the pattern uses a, GMT defaults to "en-US" rather than returning "" for every caller who didn’t have another locale in mind.
• h/hh resolve to 24-hour using a matched a token: if the label is the PM label and hour !== 12, add 12; if the AM label and hour === 12, set hour to 0. With no a token in the pattern at all, the pattern is still valid but the hour stays ambiguous — GMT resolves it as if AM had matched (12 → 0, otherwise unchanged).
• A shape-valid match does not by itself prove a real time: extracted fields are always handed to Temporal.PlainTime.from(fields, { overflow: "reject" }) — the regex only proves the shape, Temporal proves the time is real.

Parameters

Parameter	Type	Description
value	string	The string to decode (e.g. “02:30:45 PM”)
pattern	string	The token pattern describing value’s shape (e.g. “hh:mm:ss a”)
locale	string	Optional BCP 47 locale for the meridiem token (default “en-US”)

Returns

ISO PlainTime string, or “” on no match, malformed pattern, or invalid input

Examples

parseTimeWithPattern("14:30:45", "HH:mm:ss") // "14:30:45"
parseTimeWithPattern("02:30:45 PM", "hh:mm:ss a") // "14:30:45"
parseTimeWithPattern("25:00", "HH:mm") // "" (shape-valid, not a real time)
parseTimeWithPattern("2024-03-15", "yyyy-MM-dd") // "" (date token in a time-only pattern)

Source

plain/parse/parseTimeWithPattern.ts