unacy 0.8.0 → 0.8.2

package/dist/types.d.ts

@@ -9,7 +9,21 @@ import type { GetTagMetadata, Simplify, Tagged, UnwrapTagged } from 'type-fest';
  * giving us the `Tag` constraint without importing the internal `Tag` type.
  */
 type AnyTaggedUnit = Tagged<unknown, typeof UNITS, any>;
+/**
+ * Internal phantom-type brand key used to tag values with unit metadata.
+ * Consumers should not use this symbol directly — use `WithUnits<T, M>` instead.
+ *
+ * @category Branding
+ * @internal
+ */
 export declare const UNITS: unique symbol;
+/**
+ * Reserved symbol for future definition attachment on unit metadata.
+ * Not used in the current public API.
+ *
+ * @category Branding
+ * @internal
+ */
 export declare const DEFINITION: unique symbol;
 /**
  * Resolve a schema/constructor/enum type to its runtime value type.
@@ -19,6 +33,8 @@ export declare const DEFINITION: unique symbol;
  * - **Record schemas** → `InferFromRecordSchema` (`{ x: 'number' }` → `{ x: number }`)
  * - **Enum objects** → `T[keyof T]` (enum value type)
  * - **Primitives** → passed through unchanged
+ *
+ * @category Type Utilities
  */
 export type ResolveValueType<T> = T extends readonly string[] ? InferFromTupleSchema<T> : T extends ClassType ? InstanceType<T> : T extends RecordSchema ? T[keyof T] extends keyof PrimitiveTypeMap | RecordSchema ? InferFromRecordSchema<T> : T[keyof T] : T extends EnumType ? T[keyof T] : T;
 /**
@@ -37,6 +53,18 @@ export type ResolveValueType<T> = T extends readonly string[] ? InferFromTupleSc
  * type Celsius = WithTypedUnits<typeof CelsiusMeta>;
  * // Celsius = Tagged<number, UNITS, typeof CelsiusMeta>
  * ```
+ *
+ * @useWhen You have a metadata object with an explicit `type` field and want
+ * the branded type to reflect the correct base type automatically.
+ *
+ * @avoidWhen You only have a `BaseMetadata` object without a `type` field — use
+ * `WithUnits<T, M>` directly, specifying the base type explicitly.
+ *
+ * @pitfalls
+ * NEVER pass `any` as the type parameter — `WithTypedUnits<any>` widens to
+ * `WithUnits<any, any>`, bypassing all type checks.
+ *
+ * @category Branding
  */
 export type WithTypedUnits<M extends TypedMetadata<any>> = unknown extends M ? WithUnits<any, any> : M extends {
     name: string;
@@ -45,29 +73,89 @@ export type WithTypedUnits<M extends TypedMetadata<any>> = unknown extends M ? W
 /**
  * Brand a value with a unit identifier for compile-time unit safety.
  *
+ * The branding is purely a compile-time phantom — at runtime, values are plain
+ * `T` (number, string, etc.) with zero overhead. Branded values extend their
+ * base type, so they are assignable to plain `T` but not vice versa.
+ *
  * @template T - Base type (e.g., number, bigint, record, tuple, class instance)
  * @template M - Metadata type (must extend BaseMetadata with required name property)
  *
  * @example
  * ```typescript
- * const Celsius = { name: 'Celsius' as const, symbol: '°C' } satisfies BaseMetadata;
- * type Celsius = WithUnits<number, typeof Celsius>;
+ * const CelsiusMeta = { name: 'Celsius' as const, symbol: '°C' } satisfies BaseMetadata;
+ * type Celsius = WithUnits<number, typeof CelsiusMeta>;
  * const temp: Celsius = 25 as Celsius;
+ *
+ * // Celsius is assignable to number, but number is not assignable to Celsius
+ * const raw: number = temp; // OK
+ * const invalid: Celsius = raw; // TS error
  * ```
+ *
+ * @useWhen You need a branded unit type and your metadata does not have a `type`
+ * field (or you want to specify the base type explicitly).
+ *
+ * @avoidWhen Your metadata already carries a `type` field — prefer `WithTypedUnits<M>`
+ * to let the compiler infer the correct base type automatically.
+ *
+ * @pitfalls
+ * NEVER use `as` to cast a plain `number` to `WithUnits<number, M>` in
+ * application code without validating the value first — the cast bypasses
+ * every compile-time guarantee that `WithUnits` provides.
+ *
+ * NEVER assign a value of `WithUnits<number, CelsiusMetadata>` to a variable
+ * typed `WithUnits<number, FahrenheitMetadata>` via `as` — the phantom types
+ * become meaningless if the brand is forged at assignment sites.
+ *
+ * @category Branding
+ * @see WithTypedUnits
  */
 export type WithUnits<T, M extends BaseMetadata = BaseMetadata> = Tagged<T, typeof UNITS, M>;
-/** Primitive JavaScript types that can be used as unit base types. */
+/**
+ * Primitive JavaScript types that can be used as unit base types.
+ *
+ * @remarks
+ * Covers the four scalar primitive types that unacy supports as direct base
+ * types for `WithUnits<T, M>`. Non-primitive base types (classes, enums,
+ * records, tuples) are handled via `SupportedType`.
+ *
+ * @category Types
+ */
 export type PrimitiveType = number | string | boolean | bigint;
 /**
  * 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.
+ *
+ * @remarks
+ * TypeScript numeric enums produce reverse-mapped keys at runtime
+ * (e.g., `{ DEBUG: 0, 0: 'DEBUG' }`). `validateEnum` filters those out
+ * automatically — you do not need to handle them yourself.
+ *
+ * @pitfalls
+ * NEVER use an empty object (`{}`) as an enum type — `validateEnum` rejects
+ * it, and the registry will throw at registration time.
+ *
+ * NEVER mix numeric and string values in a single enum — unacy rejects mixed
+ * enums at validation time because the value type would be ambiguous.
+ *
+ * @category Types
  */
 export type EnumType = Record<string, string | number>;
 /**
  * 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.
+ *
+ * @remarks
+ * When the registry detects a class-typed unit (via `isClassMetadata`), the
+ * unit accessor's brand function calls `new Constructor(...args)` so that
+ * `registry.MyUnit(arg1, arg2)` returns a properly constructed instance.
+ *
+ * @pitfalls
+ * NEVER pass an arrow function or a bound function as a `ClassType` — they
+ * lack a `prototype` property and will fail `validateClass` at registration.
+ *
+ * @category Types
  */
 export type ClassType = abstract new (...args: any[]) => any;
 /** A record schema value — either a primitive type name or a nested schema. */
@@ -80,7 +168,17 @@ export type RecordSchemaValue = string | RecordSchema;
  * @example
  * ```typescript
  * const PointSchema = { x: 'number', y: 'number' } satisfies RecordSchema;
+ * const NestedSchema = { pos: { x: 'number', y: 'number' }, label: 'string' } satisfies RecordSchema;
  * ```
+ *
+ * @pitfalls
+ * NEVER use a circular schema object — `validateRecordSchema` detects circular
+ * references and throws, so the registry will refuse to register such a unit.
+ *
+ * NEVER use non-primitive type names as leaf values (e.g., `'Date'`) — only
+ * `'number'`, `'string'`, `'boolean'`, and `'bigint'` are accepted.
+ *
+ * @category Types
  */
 export type RecordSchema = {
     [key: string]: RecordSchemaValue;
@@ -92,12 +190,33 @@ export type RecordSchema = {
  * @example
  * ```typescript
  * const RGBSchema = ['number', 'number', 'number'] as const satisfies TupleSchema;
+ * const FlexSchema = ['string', 'number?', '...boolean'] as const satisfies TupleSchema;
  * ```
+ *
+ * @remarks
+ * When the registry detects a tuple-typed unit (via `isTupleMetadata`), the
+ * brand function collects spread arguments into an array. Pass each tuple
+ * member as a separate argument: `registry.RGB(255, 128, 0)` instead of
+ * `registry.RGB([255, 128, 0])`.
+ *
+ * @pitfalls
+ * NEVER declare a rest element (`'...type'`) in a non-terminal position —
+ * `validateTupleSchema` accepts it syntactically, but `InferFromTupleSchema`
+ * only handles rest at the last position and returns `never` otherwise.
+ *
+ * @category Types
  */
 export type TupleSchema = readonly string[];
 /**
  * Union of all types that can be used as a unit's base type.
  * Includes primitives and non-primitive categories (enum, class, record, tuple).
+ *
+ * @remarks
+ * `SupportedType` is the constraint on the `T` parameter of `WithUnits<T, M>`
+ * and on the `type` field of `TypedMetadata<T>`. The registry uses
+ * `detectMetadataKind` to dispatch on which member of the union is present.
+ *
+ * @category Types
  */
 export type SupportedType = PrimitiveType | EnumType | ClassType | RecordSchema | TupleSchema;
 export type PrimitiveTypeMap = {
@@ -106,6 +225,11 @@ export type PrimitiveTypeMap = {
     boolean: boolean;
     bigint: bigint;
 };
+/**
+ * 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.
+ */
 export type ToPrimitiveTypeName<T> = T extends PrimitiveTypeMap[infer U extends keyof PrimitiveTypeMap] ? U : never;
 export type OptionalWithUnits<T, M extends BaseMetadata = BaseMetadata> = T | WithUnits<T, M>;
 export type Unwrap<T> = T extends AnyTaggedUnit ? UnwrapTagged<T> : T;
@@ -123,18 +247,71 @@ export type Unwrap<T> = T extends AnyTaggedUnit ? UnwrapTagged<T> : T;
 export type InferCallableArgs<From> = From extends AnyTaggedUnit ? GetTagMetadata<From, typeof UNITS> extends {
     type: infer TypeField;
 } ? TypeField extends readonly string[] ? InferFromTupleSchema<TypeField> : TypeField extends ClassType ? ConstructorParameters<TypeField> : TypeField extends RecordSchema ? TypeField[keyof TypeField] extends keyof PrimitiveTypeMap | RecordSchema ? [InferFromRecordSchema<TypeField>] : [TypeField[keyof TypeField]] : TypeField extends EnumType ? [TypeField[keyof TypeField]] : [Unwrap<From>] : [Unwrap<From>] : [Unwrap<From>];
+/**
+ * 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.
+ *
+ * @remarks
+ * Use `Relax<T>` in converter or utility signatures where callers may hold a
+ * plain value (e.g., coming from a JSON payload) alongside properly branded
+ * values. The type still communicates intent while remaining ergonomic.
+ *
+ * @example
+ * ```typescript
+ * function display(temp: Relax<Celsius>): string {
+ *   return `${temp}°C`; // accepts both: Celsius brand or plain number
+ * }
+ * display(25);           // OK — plain number
+ * display(25 as Celsius); // OK — branded
+ * ```
+ *
+ * @useWhen Writing utility functions that wrap or log branded values and
+ * should remain usable before the caller has set up a full registry.
+ *
+ * @avoidWhen Writing converter functions that must enforce the source brand —
+ * use the explicit branded type (`Celsius`) to preserve the safety guarantee.
+ *
+ * @category Branding
+ */
 export type Relax<T> = T | Unwrap<T>;
 /**
  * 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.
+ *
  * @template T - Base type (e.g., Date, number, string)
- * @template F - Format identifier (e.g., 'ISO8601', 'UnixTimestamp')
+ * @template F - Format identifier string literal (e.g., `'ISO8601'`, `'UnixTimestamp'`)
  *
  * @example
  * ```typescript
- * type ISO8601 = WithFormat<Date, 'ISO8601'>;
- * const date: ISO8601 = new Date() as ISO8601;
+ * 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();
  * ```
+ *
+ * @useWhen 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.
+ *
+ * @avoidWhen 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.
+ *
+ * @category Branding
+ * @see Formatter
+ * @see Parser
+ * @see FormatterParser
  */
 export type WithFormat<T, F extends string> = Tagged<T, typeof UNITS, F>;
 export type UnitsOf<T> = T extends AnyTaggedUnit ? GetTagMetadata<T, typeof UNITS> : never;
@@ -149,21 +326,45 @@ export type MetadataOf<T> = T extends AnyTaggedUnit ? GetTagMetadata<T, typeof U
  * Base metadata type that all unit metadata must extend.
  * Requires a `name` property and allows arbitrary additional properties.
  *
+ * @remarks
+ * `name` is the registry key — it must be a string literal (`as const`) so
+ * that the type-level accessor map (`UnitMap`) can index by it. At runtime it
+ * is also the adjacency-map key used for BFS path finding, so names must be
+ * unique within a registry.
+ *
  * @example
  * ```typescript
- * const Celsius = {
- *   name: 'Celsius' as const,
+ * const CelsiusMeta = {
+ *   name: 'Celsius' as const,    // must be a literal
  *   symbol: '°C',
  *   description: 'Temperature in Celsius'
  * } satisfies BaseMetadata;
  * ```
+ *
+ * @useWhen Defining metadata for a unit that only needs a name and optional
+ * display fields (symbol, abbreviation, description). For units where the
+ * base type matters in conversions, use `TypedMetadata<T>`.
+ *
+ * @pitfalls
+ * NEVER use a non-literal string for `name` (e.g., `name: string` instead of
+ * `name: 'Celsius' as const`) — the registry key becomes `string` and the
+ * compile-time accessor `registry.Celsius.to.Fahrenheit` stops resolving.
+ *
+ * NEVER reuse the same `name` value across two different unit objects in the
+ * same registry — the second registration silently overwrites the first.
+ *
+ * @config
+ * Additional properties (e.g., `symbol`, `abbreviation`, `description`) are
+ * accessible as `registry.<UnitName>.<property>` after registration.
+ *
+ * @category Metadata
  */
 export type BaseMetadata = {
     /** Unique identifier for the unit (replaces tag) */
     name: string;
 };
 /**
- * Metadata type for units with type information.
+ * Metadata type for units with explicit type information.
  *
  * For primitive types, `type` is the type name string (e.g., `'number'`).
  * For non-primitive types, `type` IS the actual value:
@@ -171,15 +372,77 @@ export type BaseMetadata = {
  * - Class: the class constructor
  * - Record: the schema object `{ x: 'number', y: 'string' }`
  * - Tuple: the tuple schema array `['number', 'string']`
+ *
+ * @template T - The `SupportedType` that this metadata describes
+ *
+ * @example
+ * ```typescript
+ * // Primitive
+ * const CelsiusMeta = { name: 'Celsius' as const, type: 'number' as const } satisfies TypedMetadata<number>;
+ *
+ * // Enum
+ * enum Direction { North, South, East, West }
+ * const DirectionMeta = { name: 'Direction' as const, type: Direction } satisfies TypedMetadata<typeof Direction>;
+ *
+ * // Record schema
+ * const PointMeta = { name: 'Point' as const, type: { x: 'number', y: 'number' } as const } satisfies TypedMetadata<{ x: number; y: number }>;
+ * ```
+ *
+ * @useWhen You want `WithTypedUnits<M>` to automatically resolve the correct
+ * base type from the metadata, avoiding the need to specify it manually.
+ *
+ * @pitfalls
+ * NEVER widen the `type` field to a general `string` or `object` — the type
+ * inference chain from `TypedMetadata` → `WithTypedUnits` → `UnitAccessor`
+ * depends on the literal or structural type being preserved at compile time.
+ *
+ * @config
+ * Additional fields beyond `name` and `type` (e.g., `symbol`, `description`)
+ * are permitted and accessible via the registry accessor.
+ *
+ * @category Metadata
+ * @see WithTypedUnits
  */
 export type TypedMetadata<T extends SupportedType> = Simplify<{
     name: string;
     type: T extends PrimitiveType ? ToPrimitiveTypeName<T> : T;
 }>;
 /**
- * Metadata that can be attached to units in the registry
- * Supports common properties like abbreviation, format, description,
- * and allows arbitrary custom properties via index signature
+ * Display and descriptive metadata that can be attached to units in the registry.
+ *
+ * Supports common properties like abbreviation, format template, description,
+ * and symbol, plus an index signature for arbitrary custom fields.
+ *
+ * @remarks
+ * `UnitMetadata` is the internal store type used by `ConverterRegistryImpl`.
+ * Access registered metadata via the unit accessor:
+ * `registry.Celsius.symbol`, `registry.Celsius.abbreviation`, etc.
+ *
+ * @example
+ * ```typescript
+ * const registry = createRegistry()
+ *   .register({
+ *     name: 'Celsius' as const,
+ *     symbol: '°C',
+ *     abbreviation: '°C',
+ *     description: 'Degrees Celsius',
+ *   });
+ *
+ * registry.Celsius.symbol;       // '°C'
+ * registry.Celsius.description;  // 'Degrees Celsius'
+ * ```
+ *
+ * @config
+ * - `symbol` — SI / conventional symbol (e.g., `'°C'`, `'m'`, `'kg'`)
+ * - `abbreviation` — short display abbreviation
+ * - `format` — optional format template string
+ * - `description` — human-readable description
+ * - `[key: string]` — any additional custom fields
+ *
+ * @useWhen You want to attach human-readable labels or display hints to a
+ * unit so consumers can render values without hard-coding strings.
+ *
+ * @category Metadata
  */
 export interface UnitMetadata {
     /** Short abbreviation for the unit (e.g., "°C", "m", "kg") */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEhF;;;;GAIG;AACH,KAAK,aAAa,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,KAAK,EAAE,GAAG,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,OAAO,MAAwB,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,MAA6B,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,MAAM,EAAE,GACzD,oBAAoB,CAAC,CAAC,CAAC,GACvB,CAAC,SAAS,SAAS,GACjB,YAAY,CAAC,CAAC,CAAC,GACf,CAAC,SAAS,YAAY,GACpB,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,gBAAgB,GAAG,YAAY,GACtD,qBAAqB,CAAC,CAAC,CAAC,GACxB,CAAC,CAAC,MAAM,CAAC,CAAC,GACZ,CAAC,SAAS,QAAQ,GAChB,CAAC,CAAC,MAAM,CAAC,CAAC,GACV,CAAC,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,aAAa,CAAC,GAAG,CAAC,IAAI,OAAO,SAAS,CAAC,GACxE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,GACnB,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,SAAS,CAAA;CAAE,GAC/C,SAAS,SAAS,MAAM,gBAAgB,GACtC,SAAS,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,GACzC,SAAS,SAAS,aAAa,GAC7B,SAAS,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,GACzC,KAAK,GACT,KAAK,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC;AAE7F;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAE7D,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,YAAY,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,MAAM,EAAE,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;AAE9F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,SACrE,MAAM,gBAAgB,CAAC,GACrB,CAAC,GACD,KAAK,CAAC;AAEV,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE9F,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,IAAI,IAAI,SAAS,aAAa,GAC5D,cAAc,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,SAAS,CAAA;CAAE,GAClE,SAAS,SAAS,SAAS,MAAM,EAAE,GACjC,oBAAoB,CAAC,SAAS,CAAC,GAC/B,SAAS,SAAS,SAAS,GACzB,qBAAqB,CAAC,SAAS,CAAC,GAChC,SAAS,SAAS,YAAY,GAC5B,SAAS,CAAC,MAAM,SAAS,CAAC,SAAS,MAAM,gBAAgB,GAAG,YAAY,GACtE,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,GAClC,CAAC,SAAS,CAAC,MAAM,SAAS,CAAC,CAAC,GAC9B,SAAS,SAAS,QAAQ,GACxB,CAAC,SAAS,CAAC,MAAM,SAAS,CAAC,CAAC,GAC5B,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GACtB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAChB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;AACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC;AAEzE,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,GAAG,cAAc,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,GAC5C,cAAc,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC,SAAS,MAAM,CAAA;CAAE,GACtE,CAAC,GACD,MAAM,GACR,MAAM,CAAC;AAEX,qDAAqD;AACrD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;AAErC,6CAA6C;AAC7C,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,GAC/C,cAAc,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,SAAS,MAAM,CAAC,GAC7C,CAAC,GACD,YAAY,GACd,YAAY,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,IAAI,QAAQ,CAAC;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,SAAS,aAAa,GAAG,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CAC5D,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAMD;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,QAAQ,GACpE,MAAM,GACN,CAAC,SAAS,QAAQ,GAChB,MAAM,GACN,CAAC,SAAS,SAAS,GACjB,OAAO,GACP,CAAC,SAAS,QAAQ,GAChB,MAAM,GACN,KAAK,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,YAAY,IAAI,QAAQ,CAAC;KAClE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAC/B,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3B,CAAC,CAAC,CAAC,CAAC,SAAS,YAAY,GACvB,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3B,KAAK;CACZ,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,IAAI,CAAC,SAAS,SAAS,EAAE,GACjF,EAAE,GACF,CAAC,SAAS,SAAS,CAAC,MAAM,IAAI,SAAS,MAAM,EAAE,GAAG,MAAM,IAAI,SAAS,SAAS,MAAM,EAAE,CAAC,GACrF,IAAI,SAAS,MAAM,MAAM,IAAI,EAAE,GAC7B,IAAI,SAAS,SAAS,EAAE,GACtB,CAAC,GAAG,KAAK,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,GACvC,KAAK,GACP,IAAI,SAAS,GAAG,MAAM,IAAI,GAAG,GAC3B,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAC7D,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAChE,KAAK,CAAC"}

package/dist/types.js

@@ -2,6 +2,20 @@
  * Core type branding utilities for unit and format safety
  * @packageDocumentation
  */
+/**
+ * Internal phantom-type brand key used to tag values with unit metadata.
+ * Consumers should not use this symbol directly — use `WithUnits<T, M>` instead.
+ *
+ * @category Branding
+ * @internal
+ */
 export const UNITS = Symbol('UNITS');
+/**
+ * Reserved symbol for future definition attachment on unit metadata.
+ * Not used in the current public API.
+ *
+ * @category Branding
+ * @internal
+ */
 export const DEFINITION = Symbol('DEFINITION');
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,CAAC,MAAM,KAAK,GAAkB,MAAM,CAAC,OAAO,CAAC,CAAC;AAEpD,MAAM,CAAC,MAAM,UAAU,GAAkB,MAAM,CAAC,YAAY,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAkB,MAAM,CAAC,OAAO,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAkB,MAAM,CAAC,YAAY,CAAC,CAAC"}

package/dist/utils/graph.d.ts

@@ -6,21 +6,83 @@ import type { Converter } from '../converters.js';
 /**
  * Find the shortest path between two nodes using BFS.
  *
- * @param from - Starting node
- * @param to - Target node
- * @param adjacencyMap - Graph represented as adjacency list
- * @returns Array of nodes representing the shortest path, or null if no path exists
- * @throws {CycleError} If a cycle is detected during traversal
- * @throws {MaxDepthError} If path depth exceeds MAX_DEPTH
+ * Traverses the unit conversion graph breadth-first to find the minimum-hop
+ * path from `from` to `to`. The result is used by `composeConverters` to build
+ * a composed converter function for multi-hop conversions.
+ *
+ * @param from - Starting node (unit name key)
+ * @param to - Target node (unit name key)
+ * @param adjacencyMap - Graph represented as a nested adjacency list
+ * @returns Array of nodes representing the shortest path (including `from` and `to`),
+ *   or `null` if no path exists
+ *
+ * @throws {CycleError} If `from === to` (self-conversion cycle)
+ * @throws {MaxDepthError} If any discovered path would exceed `MAX_DEPTH` (5) edges
+ *
+ * @remarks
+ * The BFS visits each node at most once (`visited` set). Self-loops are detected
+ * eagerly (`from === to` check) rather than during traversal.
+ *
+ * The maximum depth limit (`MAX_DEPTH = 5`) guards against sparse but deeply
+ * connected graphs. If you regularly need 5+ hop chains, redesign the graph by
+ * registering intermediate direct edges or using `allow()` to pre-compose paths.
+ *
+ * @example
+ * ```typescript
+ * // Internal usage in ConverterRegistryImpl.getConverter():
+ * const path = findShortestPath('Celsius', 'Fahrenheit', graph);
+ * // path = ['Celsius', 'Kelvin', 'Fahrenheit'] if only C→K and K→F are registered
+ * ```
+ *
+ * @pitfalls
+ * NEVER call this function directly from application code — use
+ * `registry.convert(value, from).to(to)` or `registry.getConverter(from, to)`,
+ * which add BFS caching and handle error propagation correctly.
+ *
+ * @category Graph
+ * @see composeConverters
  */
 export declare function findShortestPath(from: PropertyKey, to: PropertyKey, adjacencyMap: Map<PropertyKey, Map<PropertyKey, unknown>>): PropertyKey[] | null;
 /**
  * Compose multiple converters along a path into a single converter.
  *
- * @param path - Array of nodes representing the conversion path
- * @param registry - Map of converters keyed by [from, to]
- * @returns Composed converter function
- * @throws {Error} If any converter in the path is missing
+ * Given a path `[A, B, C]` and a registry containing `A→B` and `B→C`
+ * converters, produces a single `Converter<A, C>` that applies them left-to-right.
+ *
+ * @param path - Array of unit-name nodes representing the conversion path
+ *   (at least 2 elements required: `[from, ..., to]`)
+ * @param registry - Adjacency map of converters keyed by source unit name
+ * @returns Composed converter function that applies each step in sequence
+ *
+ * @throws {Error} If the path has fewer than 2 nodes
+ * @throws {Error} If any converter along the path is missing from the registry
+ *
+ * @remarks
+ * The composition is a simple `reduce` — values pass through each converter in
+ * order. Each intermediate result is an unbranded `any` at runtime; the type
+ * safety is enforced at the call site by the registry's type signature.
+ *
+ * Floating-point precision accumulates with each hop. For chains where precision
+ * matters, prefer registering a direct edge over relying on BFS composition.
+ *
+ * @example
+ * ```typescript
+ * // Internal usage: path found by findShortestPath
+ * const composed = composeConverters(['Celsius', 'Kelvin', 'Fahrenheit'], graph);
+ * composed(0); // applies C→K then K→F, returning 32
+ * ```
+ *
+ * @pitfalls
+ * NEVER call this function with a path containing a unit that has no outgoing
+ * edge in the registry — it throws immediately with a non-descriptive `Error`.
+ * Always confirm paths with `findShortestPath` first.
+ *
+ * NEVER rely on composed-converter precision for high-accuracy domains (e.g.,
+ * financial or scientific calculations) — each hop introduces floating-point
+ * rounding error. Register a direct converter instead.
+ *
+ * @category Graph
+ * @see findShortestPath
  */
 export declare function composeConverters(path: PropertyKey[], registry: Map<PropertyKey, Map<PropertyKey, Converter<any, any>>>): Converter<any, any>;
 //# sourceMappingURL=graph.d.ts.map

package/dist/utils/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/utils/graph.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAOlD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,WAAW,EACf,YAAY,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,GACxD,WAAW,EAAE,GAAG,IAAI,CA8CtB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EAAE,EACnB,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAChE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CA4BrB"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/utils/graph.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAOlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,WAAW,EACf,YAAY,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,GACxD,WAAW,EAAE,GAAG,IAAI,CA8CtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EAAE,EACnB,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAChE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CA4BrB"}

package/dist/utils/graph.js

@@ -10,12 +10,41 @@ const MAX_DEPTH = 5;
 /**
  * Find the shortest path between two nodes using BFS.
  *
- * @param from - Starting node
- * @param to - Target node
- * @param adjacencyMap - Graph represented as adjacency list
- * @returns Array of nodes representing the shortest path, or null if no path exists
- * @throws {CycleError} If a cycle is detected during traversal
- * @throws {MaxDepthError} If path depth exceeds MAX_DEPTH
+ * Traverses the unit conversion graph breadth-first to find the minimum-hop
+ * path from `from` to `to`. The result is used by `composeConverters` to build
+ * a composed converter function for multi-hop conversions.
+ *
+ * @param from - Starting node (unit name key)
+ * @param to - Target node (unit name key)
+ * @param adjacencyMap - Graph represented as a nested adjacency list
+ * @returns Array of nodes representing the shortest path (including `from` and `to`),
+ *   or `null` if no path exists
+ *
+ * @throws {CycleError} If `from === to` (self-conversion cycle)
+ * @throws {MaxDepthError} If any discovered path would exceed `MAX_DEPTH` (5) edges
+ *
+ * @remarks
+ * The BFS visits each node at most once (`visited` set). Self-loops are detected
+ * eagerly (`from === to` check) rather than during traversal.
+ *
+ * The maximum depth limit (`MAX_DEPTH = 5`) guards against sparse but deeply
+ * connected graphs. If you regularly need 5+ hop chains, redesign the graph by
+ * registering intermediate direct edges or using `allow()` to pre-compose paths.
+ *
+ * @example
+ * ```typescript
+ * // Internal usage in ConverterRegistryImpl.getConverter():
+ * const path = findShortestPath('Celsius', 'Fahrenheit', graph);
+ * // path = ['Celsius', 'Kelvin', 'Fahrenheit'] if only C→K and K→F are registered
+ * ```
+ *
+ * @pitfalls
+ * NEVER call this function directly from application code — use
+ * `registry.convert(value, from).to(to)` or `registry.getConverter(from, to)`,
+ * which add BFS caching and handle error propagation correctly.
+ *
+ * @category Graph
+ * @see composeConverters
  */
 export function findShortestPath(from, to, adjacencyMap) {
     // Handle self-conversion (cycle detection)
@@ -59,10 +88,43 @@ export function findShortestPath(from, to, adjacencyMap) {
 /**
  * Compose multiple converters along a path into a single converter.
  *
- * @param path - Array of nodes representing the conversion path
- * @param registry - Map of converters keyed by [from, to]
- * @returns Composed converter function
- * @throws {Error} If any converter in the path is missing
+ * Given a path `[A, B, C]` and a registry containing `A→B` and `B→C`
+ * converters, produces a single `Converter<A, C>` that applies them left-to-right.
+ *
+ * @param path - Array of unit-name nodes representing the conversion path
+ *   (at least 2 elements required: `[from, ..., to]`)
+ * @param registry - Adjacency map of converters keyed by source unit name
+ * @returns Composed converter function that applies each step in sequence
+ *
+ * @throws {Error} If the path has fewer than 2 nodes
+ * @throws {Error} If any converter along the path is missing from the registry
+ *
+ * @remarks
+ * The composition is a simple `reduce` — values pass through each converter in
+ * order. Each intermediate result is an unbranded `any` at runtime; the type
+ * safety is enforced at the call site by the registry's type signature.
+ *
+ * Floating-point precision accumulates with each hop. For chains where precision
+ * matters, prefer registering a direct edge over relying on BFS composition.
+ *
+ * @example
+ * ```typescript
+ * // Internal usage: path found by findShortestPath
+ * const composed = composeConverters(['Celsius', 'Kelvin', 'Fahrenheit'], graph);
+ * composed(0); // applies C→K then K→F, returning 32
+ * ```
+ *
+ * @pitfalls
+ * NEVER call this function with a path containing a unit that has no outgoing
+ * edge in the registry — it throws immediately with a non-descriptive `Error`.
+ * Always confirm paths with `findShortestPath` first.
+ *
+ * NEVER rely on composed-converter precision for high-accuracy domains (e.g.,
+ * financial or scientific calculations) — each hop introduces floating-point
+ * rounding error. Register a direct converter instead.
+ *
+ * @category Graph
+ * @see findShortestPath
  */
 export function composeConverters(path, registry) {
     if (path.length < 2) {