unacy 0.8.1 → 0.8.2

package/dist/converters.d.ts

@@ -6,22 +6,46 @@ import type { PrimitiveType, Relax as BaseRelax, Unwrap } from './types.js';
 /**
  * Unidirectional converter from one unit to another.
  *
- * @template TInput - Source unit-tagged type
- * @template TOutput - Destination unit-tagged type
+ * A pure function that takes a value tagged with a source unit and returns a
+ * value tagged with a destination unit. Converters are registered in the
+ * `UnitRegistry` and composed automatically via BFS when no direct edge exists.
+ *
+ * @template TInput - Source unit-tagged type (e.g., `Celsius`)
+ * @template TOutput - Destination unit-tagged type (e.g., `Fahrenheit`)
  *
  * @param input - Value tagged with source unit
  * @returns Value tagged with destination unit
  *
  * @remarks
- * - Must be a pure function (no side effects)
- * - Should be deterministic (same input → same output)
- * - Document precision loss if applicable
+ * - Must be a pure function (no side effects, no external state reads)
+ * - Must be deterministic (same input always produces the same output)
+ * - Float arithmetic on chained conversions accumulates rounding error;
+ *   document precision characteristics in the function's JSDoc
  *
  * @example
  * ```typescript
- * const c2f: Converter<Celsius, Fahrenheit> = (c) =>
- *   ((c * 9/5) + 32) as Fahrenheit;
+ * const c2f: Converter<Celsius, Fahrenheit> = (c) => (c * 9/5) + 32;
+ * const f2k: Converter<Fahrenheit, Kelvin> = (f) => ((f - 32) * 5/9) + 273.15;
  * ```
+ *
+ * @useWhen You need a named, reusable conversion function to pass to
+ * `registry.register(from, to, converter)`.
+ *
+ * @avoidWhen You need both forward and reverse directions — use
+ * `BidirectionalConverter<A, B>` to register both in a single call.
+ *
+ * @pitfalls
+ * NEVER mutate the input value inside a converter — because values are
+ * primitives or phantom-typed plain objects, mutation is silent and will
+ * corrupt the original branded value at the call site.
+ *
+ * NEVER rely on closure state inside a converter for caching — the registry
+ * caches composed converters by path key, so stateful closures can lead to
+ * incorrect results on subsequent calls.
+ *
+ * @category Converters
+ * @see BidirectionalConverter
+ * @see RelaxedConverter
  */
 export type Converter<TInput, TOutput> = (input: TInput) => TOutput;
 export type RelaxConverter<ConverterType> = ConverterType extends Converter<infer A extends PrimitiveType, infer B extends PrimitiveType> ? (input: BaseRelax<A>) => BaseRelax<B> : (input: PrimitiveType) => PrimitiveType;
@@ -29,24 +53,51 @@ export type Relax<T extends PrimitiveType | Converter<any, any> | BidirectionalC
 /**
  * Bidirectional converter with forward and reverse transformations.
  *
- * @template TInput - First unit type
- * @template TOutput - Second unit type
+ * Registers both directions in a single `registry.register(A, B, converter)` call.
+ * Under the hood, the registry splits `{ to, from }` into two unidirectional
+ * edges in the adjacency map.
+ *
+ * @template TInput - First unit type (the "from" direction)
+ * @template TOutput - Second unit type (the "to" direction)
  *
  * @property to - Forward converter (TInput → TOutput)
  * @property from - Reverse converter (TOutput → TInput)
  *
  * @remarks
- * - Round-trip conversions should preserve value within acceptable tolerance
- * - Both converters must be deterministic
- * - Use when both conversion directions are commonly needed
+ * - Round-trip conversions should preserve value within acceptable floating-point
+ *   tolerance; test with `Math.abs(parse(format(x)) - x) < epsilon`
+ * - Both converters must be deterministic pure functions
  *
  * @example
  * ```typescript
- * const meterKilometer: BidirectionalConverter<Meters, Kilometers> = {
- *   to: (m) => (m / 1000) as Kilometers,
- *   from: (km) => (km * 1000) as Meters
+ * const celsiusFahrenheit: BidirectionalConverter<Celsius, Fahrenheit> = {
+ *   to: (c) => (c * 9/5) + 32,
+ *   from: (f) => (f - 32) * 5/9
  * };
+ *
+ * const registry = createRegistry().register(CelsiusMeta, FahrenheitMeta, celsiusFahrenheit);
+ * registry.Celsius.to.Fahrenheit(0 as Celsius); // 32
+ * registry.Fahrenheit.to.Celsius(32 as Fahrenheit); // 0
  * ```
+ *
+ * @useWhen Both conversion directions are commonly needed and you want to
+ * minimise the number of `register` calls.
+ *
+ * @avoidWhen Only one direction is needed — registering both wastes a graph
+ * edge and slightly enlarges the type-level union. Use a plain `Converter`
+ * and call `register` once.
+ *
+ * @pitfalls
+ * NEVER swap `to` and `from` in the object literal — the names are just
+ * conventions; the registry trusts the object structure, so a transposed
+ * pair silently registers the wrong direction for each edge.
+ *
+ * NEVER assume chained round-trips are exact — floating-point rounding means
+ * `from(to(x))` may differ from `x` by epsilon; use toleranced comparisons.
+ *
+ * @category Converters
+ * @see Converter
+ * @see RelaxedBidirectionalConverter
  */
 export type BidirectionalConverter<TInput, TOutput> = {
     to: Converter<TInput, TOutput>;
@@ -61,7 +112,7 @@ export type RelaxBidirectionalConverter<ConverterType> = ConverterType extends B
 };
 /**
  * A converter that accepts the branded input type but returns
- * unwrapped output. This eliminates the need to cast return values
+ * 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.
  *
@@ -70,14 +121,52 @@ export type RelaxBidirectionalConverter<ConverterType> = ConverterType extends B
  *
  * @template TInput - Source unit-tagged type
  * @template TOutput - Destination unit-tagged type
+ *
+ * @example
+ * ```typescript
+ * // No cast needed on the return value
+ * const c2f: RelaxedConverter<Celsius, Fahrenheit> = (c) => (c * 9/5) + 32;
+ *                                                            // returns number, not Fahrenheit
+ * ```
+ *
+ * @useWhen Writing converter implementations where casting the return value
+ * to a branded type is inconvenient. The registry handles branding internally.
+ *
+ * @avoidWhen The converter is used outside the registry — callers of a
+ * standalone `RelaxedConverter` receive an unwrapped value with no unit brand.
+ *
+ * @pitfalls
+ * NEVER pass a `RelaxedConverter` result directly to another function that
+ * expects a branded type without going through the registry — the unbranded
+ * return value defeats the type safety guarantee at the call site.
+ *
+ * @category Converters
+ * @see Converter
+ * @see RelaxedBidirectionalConverter
  */
 export type RelaxedConverter<TInput, TOutput> = (input: TInput) => Unwrap<TOutput>;
 /**
  * A bidirectional converter with relaxed (unwrapped) output types.
- * Input remains branded for full autocompletion.
+ * Input remains branded for full autocompletion and type safety;
+ * return values are plain base types without branding.
  *
  * @template TInput - First unit-tagged type
  * @template TOutput - Second unit-tagged type
+ *
+ * @example
+ * ```typescript
+ * const celsiusFahrenheit: RelaxedBidirectionalConverter<Celsius, Fahrenheit> = {
+ *   to: (c) => (c * 9/5) + 32,   // returns number, not Fahrenheit
+ *   from: (f) => (f - 32) * 5/9  // returns number, not Celsius
+ * };
+ * ```
+ *
+ * @useWhen You want the ergonomics of `RelaxedConverter` (no return-value cast)
+ * for both directions in a single object, typically for `registry.register()`.
+ *
+ * @category Converters
+ * @see BidirectionalConverter
+ * @see RelaxedConverter
  */
 export type RelaxedBidirectionalConverter<TInput, TOutput> = {
     to: RelaxedConverter<TInput, TOutput>;

package/dist/converters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../src/converters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,SAAS,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAEpE,MAAM,MAAM,cAAc,CAAC,aAAa,IACtC,aAAa,SAAS,SAAS,CAAC,MAAM,CAAC,SAAS,aAAa,EAAE,MAAM,CAAC,SAAS,aAAa,CAAC,GACzF,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GACrC,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;AAE9C,MAAM,MAAM,KAAK,CACf,CAAC,SAAS,aAAa,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,IAC9E,CAAC,SAAS,aAAa,GACvB,SAAS,CAAC,CAAC,CAAC,GACZ,CAAC,SAAS,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,GACjB,2BAA2B,CAAC,CAAC,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,sBAAsB,CAAC,MAAM,EAAE,OAAO,IAAI;IACpD,EAAE,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,aAAa,IACnD,aAAa,SAAS,sBAAsB,CAC1C,MAAM,CAAC,SAAS,aAAa,EAC7B,MAAM,CAAC,SAAS,aAAa,CAC9B,GACG;IACE,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;CAClC,GACD;IACE,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;IAC5C,IAAI,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;CAC/C,CAAC;AAER;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,MAAM,6BAA6B,CAAC,MAAM,EAAE,OAAO,IAAI;IAC3D,EAAE,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CACzC,CAAC"}
+{"version":3,"file":"converters.d.ts","sourceRoot":"","sources":["../src/converters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,MAAM,SAAS,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAEpE,MAAM,MAAM,cAAc,CAAC,aAAa,IACtC,aAAa,SAAS,SAAS,CAAC,MAAM,CAAC,SAAS,aAAa,EAAE,MAAM,CAAC,SAAS,aAAa,CAAC,GACzF,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GACrC,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;AAE9C,MAAM,MAAM,KAAK,CACf,CAAC,SAAS,aAAa,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,IAC9E,CAAC,SAAS,aAAa,GACvB,SAAS,CAAC,CAAC,CAAC,GACZ,CAAC,SAAS,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,GACjB,2BAA2B,CAAC,CAAC,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,sBAAsB,CAAC,MAAM,EAAE,OAAO,IAAI;IACpD,EAAE,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,aAAa,IACnD,aAAa,SAAS,sBAAsB,CAC1C,MAAM,CAAC,SAAS,aAAa,EAC7B,MAAM,CAAC,SAAS,aAAa,CAC9B,GACG;IACE,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;CAClC,GACD;IACE,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;IAC5C,IAAI,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;CAC/C,CAAC;AAER;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,gBAAgB,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,6BAA6B,CAAC,MAAM,EAAE,OAAO,IAAI;IAC3D,EAAE,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,EAAE,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CACzC,CAAC"}

package/dist/errors.d.ts

@@ -1,18 +1,90 @@
 /**
- * Base error class for all Unacy errors
+ * Base error class for all unacy errors.
+ *
+ * @remarks
+ * All unacy-specific errors extend `UnacyError`, so callers can catch the
+ * entire error family with a single `catch (e) { if (e instanceof UnacyError) ... }`
+ * guard while still discriminating by subclass when needed.
+ *
+ * `Object.setPrototypeOf` is called in the constructor to maintain a correct
+ * prototype chain in environments that compile to ES5.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.convert(value, 'Celsius').to('Kelvin');
+ * } catch (e) {
+ *   if (e instanceof UnacyError) {
+ *     console.error('Unit conversion failed:', e.message);
+ *   }
+ * }
+ * ```
+ *
+ * @category Errors
  */
 export declare class UnacyError extends Error {
     constructor(message: string);
 }
 /**
- * Error thrown when a cycle is detected in the conversion graph
+ * Error thrown when a cycle is detected during BFS path-finding.
+ *
+ * @remarks
+ * This error is thrown by `findShortestPath` when `from === to` (a unit
+ * being converted to itself). The registry's `getConverter` method re-throws
+ * `CycleError` rather than silently returning `undefined`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.getConverter('Celsius', 'Celsius'); // same unit
+ * } catch (e) {
+ *   if (e instanceof CycleError) {
+ *     console.error('Cycle in path:', e.path.join(' → '));
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER call `registry.convert(value, 'X').to('X')` — converting a unit to
+ * itself triggers cycle detection and throws `CycleError` at runtime.
+ *
+ * @category Errors
  */
 export declare class CycleError extends UnacyError {
     readonly path: PropertyKey[];
     constructor(path: PropertyKey[]);
 }
 /**
- * Error thrown when maximum conversion depth is exceeded
+ * Error thrown when BFS path-finding exceeds the maximum conversion depth.
+ *
+ * @remarks
+ * The maximum depth is currently fixed at 5 hops. This prevents the BFS
+ * from exploring excessively large graphs and guards against near-cycles
+ * (long paths that would be impractical for production use anyway).
+ *
+ * If you hit this error, consider:
+ * 1. Using `allow(A, Z)` to cache the composed path once found, avoiding
+ *    repeated BFS traversal.
+ * 2. Splitting a long dimension chain into domain-specific sub-registries.
+ * 3. Registering a direct edge for the problematic pair.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.getConverter('A', 'F'); // requires 6-hop path
+ * } catch (e) {
+ *   if (e instanceof MaxDepthError) {
+ *     console.error(`Path A→F exceeds max depth of ${e.maxDepth}`);
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER design a conversion graph that relies on paths longer than 5 hops —
+ * `MaxDepthError` is thrown at runtime and cannot be caught as a type error.
+ * Register intermediate direct edges or use `allow()` to cap the chain.
+ *
+ * @category Errors
  */
 export declare class MaxDepthError extends UnacyError {
     readonly from: PropertyKey;
@@ -21,7 +93,36 @@ export declare class MaxDepthError extends UnacyError {
     constructor(from: PropertyKey, to: PropertyKey, maxDepth: number);
 }
 /**
- * Error thrown when a conversion cannot be performed
+ * Error thrown when a conversion cannot be performed.
+ *
+ * @remarks
+ * `ConversionError` is the most common error consumers encounter. It is thrown
+ * when no direct edge and no BFS-discoverable path exists between two units, or
+ * when `allow()` is called for a pair with no reachable path.
+ *
+ * Inspect `e.from` and `e.to` to determine which units are missing a path, then
+ * register the required converter with `registry.register(from, to, fn)`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.convert(temp, 'Celsius').to('Miles'); // no path
+ * } catch (e) {
+ *   if (e instanceof ConversionError) {
+ *     console.error(`No path from ${String(e.from)} to ${String(e.to)}`);
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER call `registry.convert(value, fromUnit).to(toUnit)` without handling
+ * `ConversionError` — the path may not exist even if both units are registered.
+ *
+ * NEVER confuse a missing converter with a wrong-direction converter — if
+ * `A → B` is registered but `B → A` is not, converting `B` to `A` throws
+ * `ConversionError`, not a type error.
+ *
+ * @category Errors
  */
 export declare class ConversionError extends UnacyError {
     readonly from: PropertyKey;
@@ -29,7 +130,33 @@ export declare class ConversionError extends UnacyError {
     constructor(from: PropertyKey, to: PropertyKey, reason?: string);
 }
 /**
- * Error thrown when parsing a string into a tagged format fails
+ * Error thrown when parsing a string into a format-tagged value fails.
+ *
+ * @remarks
+ * Thrown by `Parser<T>` implementations (and `createParserWithSchema`) when
+ * input validation fails. Carries the format name, original input, and a
+ * human-readable reason to help callers produce user-facing error messages.
+ *
+ * Input strings longer than 50 characters are truncated with `...` in the
+ * error message to keep logs readable.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   parseISO('not-a-date');
+ * } catch (e) {
+ *   if (e instanceof ParseError) {
+ *     console.error(`Failed to parse ${e.format}: ${e.reason}`);
+ *     console.error(`Input was: ${e.input}`);
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER catch `ParseError` silently and return a default value without logging —
+ * silent coercion hides data-integrity issues that may corrupt downstream state.
+ *
+ * @category Errors
  */
 export declare class ParseError extends UnacyError {
     readonly format: string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAO,EAAE,MAAM,EAM1B;CACF;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,UAAU;IACxC,SAAgB,IAAI,EAAE,WAAW,EAAE,CAAC;IAEpC,YAAY,IAAI,EAAE,WAAW,EAAE,EAK9B;CACF;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,SAAgB,IAAI,EAAE,WAAW,CAAC;IAClC,SAAgB,EAAE,EAAE,WAAW,CAAC;IAChC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,YAAY,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAQ/D;CACF;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,SAAgB,IAAI,EAAE,WAAW,CAAC;IAClC,SAAgB,EAAE,EAAE,WAAW,CAAC;IAEhC,YAAY,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,EAM9D;CACF;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,UAAU;IACxC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,YAAY,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EASxD;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAO,EAAE,MAAM,EAM1B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,UAAW,SAAQ,UAAU;IACxC,SAAgB,IAAI,EAAE,WAAW,EAAE,CAAC;IAEpC,YAAY,IAAI,EAAE,WAAW,EAAE,EAK9B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,SAAgB,IAAI,EAAE,WAAW,CAAC;IAClC,SAAgB,EAAE,EAAE,WAAW,CAAC;IAChC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,YAAY,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAQ/D;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,SAAgB,IAAI,EAAE,WAAW,CAAC;IAClC,SAAgB,EAAE,EAAE,WAAW,CAAC;IAEhC,YAAY,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,EAM9D;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,UAAW,SAAQ,UAAU;IACxC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,YAAY,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EASxD;CACF"}

package/dist/errors.js

@@ -1,5 +1,26 @@
 /**
- * Base error class for all Unacy errors
+ * Base error class for all unacy errors.
+ *
+ * @remarks
+ * All unacy-specific errors extend `UnacyError`, so callers can catch the
+ * entire error family with a single `catch (e) { if (e instanceof UnacyError) ... }`
+ * guard while still discriminating by subclass when needed.
+ *
+ * `Object.setPrototypeOf` is called in the constructor to maintain a correct
+ * prototype chain in environments that compile to ES5.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.convert(value, 'Celsius').to('Kelvin');
+ * } catch (e) {
+ *   if (e instanceof UnacyError) {
+ *     console.error('Unit conversion failed:', e.message);
+ *   }
+ * }
+ * ```
+ *
+ * @category Errors
  */
 export class UnacyError extends Error {
     constructor(message) {
@@ -10,7 +31,29 @@ export class UnacyError extends Error {
     }
 }
 /**
- * Error thrown when a cycle is detected in the conversion graph
+ * Error thrown when a cycle is detected during BFS path-finding.
+ *
+ * @remarks
+ * This error is thrown by `findShortestPath` when `from === to` (a unit
+ * being converted to itself). The registry's `getConverter` method re-throws
+ * `CycleError` rather than silently returning `undefined`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.getConverter('Celsius', 'Celsius'); // same unit
+ * } catch (e) {
+ *   if (e instanceof CycleError) {
+ *     console.error('Cycle in path:', e.path.join(' → '));
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER call `registry.convert(value, 'X').to('X')` — converting a unit to
+ * itself triggers cycle detection and throws `CycleError` at runtime.
+ *
+ * @category Errors
  */
 export class CycleError extends UnacyError {
     path;
@@ -22,7 +65,36 @@ export class CycleError extends UnacyError {
     }
 }
 /**
- * Error thrown when maximum conversion depth is exceeded
+ * Error thrown when BFS path-finding exceeds the maximum conversion depth.
+ *
+ * @remarks
+ * The maximum depth is currently fixed at 5 hops. This prevents the BFS
+ * from exploring excessively large graphs and guards against near-cycles
+ * (long paths that would be impractical for production use anyway).
+ *
+ * If you hit this error, consider:
+ * 1. Using `allow(A, Z)` to cache the composed path once found, avoiding
+ *    repeated BFS traversal.
+ * 2. Splitting a long dimension chain into domain-specific sub-registries.
+ * 3. Registering a direct edge for the problematic pair.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.getConverter('A', 'F'); // requires 6-hop path
+ * } catch (e) {
+ *   if (e instanceof MaxDepthError) {
+ *     console.error(`Path A→F exceeds max depth of ${e.maxDepth}`);
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER design a conversion graph that relies on paths longer than 5 hops —
+ * `MaxDepthError` is thrown at runtime and cannot be caught as a type error.
+ * Register intermediate direct edges or use `allow()` to cap the chain.
+ *
+ * @category Errors
  */
 export class MaxDepthError extends UnacyError {
     from;
@@ -37,7 +109,36 @@ export class MaxDepthError extends UnacyError {
     }
 }
 /**
- * Error thrown when a conversion cannot be performed
+ * Error thrown when a conversion cannot be performed.
+ *
+ * @remarks
+ * `ConversionError` is the most common error consumers encounter. It is thrown
+ * when no direct edge and no BFS-discoverable path exists between two units, or
+ * when `allow()` is called for a pair with no reachable path.
+ *
+ * Inspect `e.from` and `e.to` to determine which units are missing a path, then
+ * register the required converter with `registry.register(from, to, fn)`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.convert(temp, 'Celsius').to('Miles'); // no path
+ * } catch (e) {
+ *   if (e instanceof ConversionError) {
+ *     console.error(`No path from ${String(e.from)} to ${String(e.to)}`);
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER call `registry.convert(value, fromUnit).to(toUnit)` without handling
+ * `ConversionError` — the path may not exist even if both units are registered.
+ *
+ * NEVER confuse a missing converter with a wrong-direction converter — if
+ * `A → B` is registered but `B → A` is not, converting `B` to `A` throws
+ * `ConversionError`, not a type error.
+ *
+ * @category Errors
  */
 export class ConversionError extends UnacyError {
     from;
@@ -51,7 +152,33 @@ export class ConversionError extends UnacyError {
     }
 }
 /**
- * Error thrown when parsing a string into a tagged format fails
+ * Error thrown when parsing a string into a format-tagged value fails.
+ *
+ * @remarks
+ * Thrown by `Parser<T>` implementations (and `createParserWithSchema`) when
+ * input validation fails. Carries the format name, original input, and a
+ * human-readable reason to help callers produce user-facing error messages.
+ *
+ * Input strings longer than 50 characters are truncated with `...` in the
+ * error message to keep logs readable.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   parseISO('not-a-date');
+ * } catch (e) {
+ *   if (e instanceof ParseError) {
+ *     console.error(`Failed to parse ${e.format}: ${e.reason}`);
+ *     console.error(`Input was: ${e.input}`);
+ *   }
+ * }
+ * ```
+ *
+ * @pitfalls
+ * NEVER catch `ParseError` silently and return a default value without logging —
+ * silent coercion hides data-integrity issues that may corrupt downstream state.
+ *
+ * @category Errors
  */
 export class ParseError extends UnacyError {
     format;

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe,EAAE;QAC3B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QAEzB,wDAAwD;QACxD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC;IAAA,CACnD;CACF;AAED;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxB,IAAI,CAAgB;IAEpC,YAAY,IAAmB,EAAE;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,KAAK,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAAA,CAClB;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,UAAU;IAC3B,IAAI,CAAc;IAClB,EAAE,CAAc;IAChB,QAAQ,CAAS;IAEjC,YAAY,IAAiB,EAAE,EAAe,EAAE,QAAgB,EAAE;QAChE,KAAK,CACH,+BAA+B,QAAQ,kCAAkC,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,EAAE,CAAC,EAAE,CACzG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAAA,CAC1B;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAC7B,IAAI,CAAc;IAClB,EAAE,CAAc;IAEhC,YAAY,IAAiB,EAAE,EAAe,EAAE,MAAe,EAAE;QAC/D,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,KAAK,CAAC,uBAAuB,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IAAA,CACd;CACF;AAED;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxB,MAAM,CAAS;IACf,KAAK,CAAS;IACd,MAAM,CAAS;IAE/B,YAAY,MAAc,EAAE,KAAa,EAAE,MAAc,EAAE;QACzD,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAC9E,MAAM,YAAY,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC;QAE1D,KAAK,CAAC,iBAAiB,YAAY,QAAQ,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QAChE,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IAAA,CACtB;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QAEzB,wDAAwD;QACxD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxB,IAAI,CAAgB;IAEpC,YAAY,IAAmB;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,KAAK,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,aAAc,SAAQ,UAAU;IAC3B,IAAI,CAAc;IAClB,EAAE,CAAc;IAChB,QAAQ,CAAS;IAEjC,YAAY,IAAiB,EAAE,EAAe,EAAE,QAAgB;QAC9D,KAAK,CACH,+BAA+B,QAAQ,kCAAkC,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,EAAE,CAAC,EAAE,CACzG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAC7B,IAAI,CAAc;IAClB,EAAE,CAAc;IAEhC,YAAY,IAAiB,EAAE,EAAe,EAAE,MAAe;QAC7D,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,KAAK,CAAC,uBAAuB,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxB,MAAM,CAAS;IACf,KAAK,CAAS;IACd,MAAM,CAAS;IAE/B,YAAY,MAAc,EAAE,KAAa,EAAE,MAAc;QACvD,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAC9E,MAAM,YAAY,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC;QAE1D,KAAK,CAAC,iBAAiB,YAAY,QAAQ,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QAChE,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}