unacy

Unacy Core - Type-safe unit and format conversion library

Branding

Type Alias	Description
Relax	Relax a branded unit type to accept either the branded form or its raw unwrapped value. Useful for APIs that should accept both WithUnits<T, M> and plain T interchangeably.
WithFormat	Brand a value with a format identifier for compile-time format safety.
WithTypedUnits	Resolve a branded unit type from a TypedMetadata object.
WithUnits	Brand a value with a unit identifier for compile-time unit safety.

Converters

Type Alias	Description
BidirectionalConverter	Bidirectional converter with forward and reverse transformations.
Converter	Unidirectional converter from one unit to another.
RelaxedBidirectionalConverter	A bidirectional converter with relaxed (unwrapped) output types. Input remains branded for full autocompletion and type safety; return values are plain base types without branding.
RelaxedConverter	A converter that accepts the branded input type but returns unwrapped (plain) output. This eliminates the need to cast return values to branded types inside converter functions, while preserving full autocompletion on the input parameter.

Errors

Class	Description
ConversionError	Error thrown when a conversion cannot be performed.
CycleError	Error thrown when a cycle is detected during BFS path-finding.
MaxDepthError	Error thrown when BFS path-finding exceeds the maximum conversion depth.
ParseError	Error thrown when parsing a string into a format-tagged value fails.
UnacyError	Base error class for all unacy errors.

Formatters

Type Alias	Description
Formatter	Formatter converts a format-tagged value to a string representation.
FormatterParser	Paired formatter/parser for round-trip format transformations.
Parser	Parser converts a plain string into a format-tagged value with validation.

Metadata

Name	Description
UnitMetadata	Display and descriptive metadata that can be attached to units in the registry.
BaseMetadata	Base metadata type that all unit metadata must extend. Requires a name property and allows arbitrary additional properties.
TypedMetadata	Metadata type for units with explicit type information.

Other

Type Alias	Description
InferFromRecordSchema	Infer TypeScript type from a RecordSchema. Recursively processes nested schemas.
InferFromTupleSchema	Infer TypeScript type from a TupleSchema. Handles optional (?) and rest (...) elements.
PrimitiveTypeFromName	Map type name strings to TypeScript primitive types.
ToPrimitiveTypeName	Map a primitive TypeScript type to its corresponding type name string. For example, number → 'number', string → 'string', boolean → 'boolean', bigint → 'bigint'. Returns never for non-primitive types.

Registry

Name	Description
UnitRegistry	Registry for managing and composing unit converters.
UnitAccessor	Callable accessor object returned per unit from the registry.
UnitMap	A map of unit name → UnitAccessor for all registered source units.
createRegistry	Create a new, empty converter registry.

Types

Type Alias	Description
ClassType	A class constructor (including abstract classes) that can serve as a unit's type identity. At runtime, the constructor itself is stored in the metadata type field.
EnumType	A TypeScript enum object at runtime — an object whose values are all strings (string enum) or all numbers (numeric enum). Mixed enums (both string and number values) are rejected at validation.
PrimitiveType	Primitive JavaScript types that can be used as unit base types.
RecordSchema	A schema describing an object shape. Keys are property names; values are primitive type name strings ('number', 'string', etc.) or nested RecordSchema objects.
SupportedType	Union of all types that can be used as a unit's base type. Includes primitives and non-primitive categories (enum, class, record, tuple).
TupleSchema	A schema describing a tuple as an array of primitive type name strings. Supports optional ('number?') and rest ('...number') modifiers.

Validation

Function	Description
createParserWithSchema	Create a Parser<WithFormat<T, F>> backed by a Zod-compatible schema.
detectMetadataKind	Detect the kind of a metadata object by inspecting its type field.
isClassMetadata	Type guard: returns true when meta.type is a class constructor.
isEnumMetadata	Type guard: returns true when meta.type is an enum object.
isRecordMetadata	Type guard: returns true when meta.type is a record schema object.
isTupleMetadata	Type guard: returns true when meta.type is a tuple schema array.
validateClass	Validate that a runtime value is a valid class constructor.
validateEnum	Validate that a runtime value is a valid TypeScript enum object.
validateRecordSchema	Validate that a runtime value is a valid record schema.
validateTupleSchema	Validate that a runtime value is a valid tuple schema.