unacy / WithFormat

Type Alias: WithFormat<T, F>

type WithFormat<T, F> = Tagged<T, typeof UNITS, F>;

Defined in: packages/core/src/types.ts:364

Brand a value with a format identifier for compile-time format safety.

Analogous to WithUnits<T, M> but for format tags rather than unit metadata. Ensures a formatted string, Date, or number cannot be passed to a formatter/parser expecting a different format.

Type Parameters

Type Parameter	Description
T	Base type (e.g., Date, number, string)
F extends string	Format identifier string literal (e.g., 'ISO8601', 'UnixTimestamp')

Example

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

const parseISO: Parser<ISO8601Date> = (s) => new Date(s) as ISO8601Date;
const formatISO: Formatter<ISO8601Date> = (d) => d.toISOString();

Use When

You need compile-time guarantees that a value has been validated and tagged with a specific serialisation format before it can be formatted or passed into format-aware APIs.

Avoid When

The value is plain and needs no format guarantee — use the bare base type (Date, number, string) directly.

Pitfalls

NEVER cast an unvalidated value to WithFormat<T, F> — use a Parser that validates the input string first and only then tags the result.

NEVER assume that round-tripping through format then parse is lossless for all inputs — floating-point serialisation and timezone handling can introduce discrepancies.

See

• Formatter
• Parser
• FormatterParser