unacy / FormatterParser

Type Alias: FormatterParser<T>

type FormatterParser<T> = {
  format: Formatter<T>;
  parse: Parser<T>;
};

Defined in: packages/core/src/formatters.ts:146

Paired formatter/parser for round-trip format transformations.

Encapsulates both directions of a format contract in a single object: format converts a branded value to a string; parse validates and re-brands a string back to the same type.

Remarks

Round-trip invariant: for all valid inputs x, parse(format(x)) should equal x (or be equivalent within the format's precision). Verify this invariant in tests — floating-point or timezone edge cases can break it.

Example

type ISO8601Date = WithFormat<Date, 'ISO8601'>;

const iso8601: FormatterParser<ISO8601Date> = {
  format: (date) => date.toISOString(),
  parse: (str) => {
    const d = new Date(str);
    if (isNaN(d.getTime())) throw new ParseError('ISO8601', str, 'Invalid date');
    return d as ISO8601Date;
  }
};

Use When

You need a self-contained codec that can be passed as a single dependency to functions that need both formatting and parsing.

Avoid When

Only one direction is needed — pass a plain Formatter<T> or Parser<T> to avoid carrying unused code.

Pitfalls

NEVER assume round-trip losslessness without testing — date precision, floating-point rounding, and locale-sensitive serialisers can all produce values where parse(format(x)) !== x in subtle cases.

See

• Formatter
• Parser

Type Parameters

Type Parameter	Description
T extends WithFormat<unknown, string>	Format-tagged type (must extend WithFormat<unknown, string>) - format — Converts tagged value → plain string - parse — Converts plain string → validated tagged value

Properties

Property	Type	Defined in
format	Formatter<T>	packages/core/src/formatters.ts:147
parse	Parser<T>	packages/core/src/formatters.ts:148