unacy 0.5.0 → 0.7.0

package/README.md

@@ -11,6 +11,7 @@ Type-safe unit and format conversion library with automatic multi-hop compositio
 - 🛡️ **Cycle detection** - Prevents infinite conversion loops
 - 📦 **Tree-shakeable** - Only bundle converters you use
 - ✨ **Fluent API** - Clean, readable conversion syntax
+- 🎯 **Typed Metadata** - Native support for `number`, `string`, `boolean`, and `bigint` units
 
 ## Installation
 
@@ -21,15 +22,27 @@ pnpm add @unacy/core
 ## Quick Start
 
 ```typescript
-import { createRegistry, type WithUnits } from '@unacy/core';
+import { createRegistry } from '@unacy/core';
+import type { WithTypedUnits } from '@unacy/core';
 
-// Define your unit types
-type Celsius = WithUnits<number, 'Celsius'>;
-type Fahrenheit = WithUnits<number, 'Fahrenheit'>;
+// Define metadata for your units (name + type)
+const CelsiusMetadata = {
+  name: 'Celsius' as const,
+  type: 'number' as const
+};
+
+const FahrenheitMetadata = {
+  name: 'Fahrenheit' as const,
+  type: 'number' as const
+};
 
-// Create a registry
+// Define your unit types with metadata
+type Celsius = WithTypedUnits<typeof CelsiusMetadata>;
+type Fahrenheit = WithTypedUnits<typeof FahrenheitMetadata>;
+
+// Create a registry and register converters
 const tempRegistry = createRegistry()
-  .register('Celsius', 'Fahrenheit', (c) => ((c * 9/5) + 32) as Fahrenheit);
+  .register(CelsiusMetadata, FahrenheitMetadata, (c) => ((c * 9/5) + 32));
 
 // Create branded values using callable accessors (NEW!)
 const temp = tempRegistry.Celsius(25); // Returns Celsius type
@@ -57,8 +70,8 @@ Unit accessors are now callable functions that create branded values:
 
 ```typescript
 // Create branded values without manual type casting
-const temp = registry.Celsius(25);        // Returns WithUnits<number, 'Celsius'>
-const distance = registry.meters(100);    // Returns WithUnits<number, 'meters'>
+const temp = registry.Celsius(25);        // Returns WithTypedUnits<typeof CelsiusMetadata>
+const distance = registry.meters(100);    // Returns WithTypedUnits<typeof MetersMetadata>
 
 // Fluent workflow
 const fahrenheit = registry.Celsius.to.Fahrenheit(registry.Celsius(20));
@@ -73,6 +86,27 @@ const tempOld: Celsius = 25 as Celsius;
 // - Works seamlessly with conversions
 ```
 
+### Typed Metadata
+
+Define metadata with minimal required fields (name + type):
+
+```typescript
+const CelsiusMetadata = {
+  name: 'Celsius' as const,
+  type: 'number' as const
+};
+
+const EtherMetadata = {
+  name: 'ether' as const,
+  type: 'bigint' as const
+};
+
+const FlagMetadata = {
+  name: 'enabled' as const,
+  type: 'boolean' as const
+};
+```
+
 ### Basic Unit Conversions
 
 ```typescript
@@ -94,16 +128,26 @@ console.log(meters); // 10
 ### Bidirectional Converters
 
 ```typescript
-import { createRegistry, type WithUnits } from '@unacy/core';
+import { createRegistry } from '@unacy/core';
+import type { WithTypedUnits } from '@unacy/core';
 
-type Meters = WithUnits<number, 'meters'>;
-type Kilometers = WithUnits<number, 'kilometers'>;
+const MetersMetadata = {
+  name: 'meters' as const,
+  type: 'number' as const
+};
 
-const registry = createRegistry<'meters' | 'kilometers'>()
-  .registerBidirectional('meters', 'kilometers', {
-    to: (m) => (m / 1000) as Kilometers,
-    from: (km) => (km * 1000) as Meters
-  });
+const KilometersMetadata = {
+  name: 'kilometers' as const,
+  type: 'number' as const
+};
+
+type Meters = WithTypedUnits<typeof MetersMetadata>;
+type Kilometers = WithTypedUnits<typeof KilometersMetadata>;
+
+const registry = createRegistry()
+  .register(MetersMetadata, KilometersMetadata, {
+    to: (m: number) => (m / 1000),
+    from: (km: number) => (km * 1000)
   });
 
 // Both directions work automatically
@@ -116,18 +160,22 @@ const m = registry.convert(5 as Kilometers, 'kilometers').to('meters'); // 5000
 The registry automatically composes converters via shortest path:
 
 ```typescript
-type Meters = WithUnits<number, 'meters'>;
-type Kilometers = WithUnits<number, 'kilometers'>;
-type Miles = WithUnits<number, 'miles'>;
-
-const registry = createRegistry<'meters' | 'kilometers' | 'miles'>()
-  .registerBidirectional('meters', 'kilometers', {
-    to: (m) => (m / 1000) as Kilometers,
-    from: (km) => (km * 1000) as Meters
+const MetersMetadata = { name: 'meters' as const, type: 'number' as const };
+const KilometersMetadata = { name: 'kilometers' as const, type: 'number' as const };
+const MilesMetadata = { name: 'miles' as const, type: 'number' as const };
+
+type Meters = WithTypedUnits<typeof MetersMetadata>;
+type Kilometers = WithTypedUnits<typeof KilometersMetadata>;
+type Miles = WithTypedUnits<typeof MilesMetadata>;
+
+const registry = createRegistry()
+  .register(MetersMetadata, KilometersMetadata, {
+    to: (m: number) => (m / 1000),
+    from: (km: number) => (km * 1000)
   })
-  .registerBidirectional('kilometers', 'miles', {
-    to: (km) => (km * 0.621371) as Miles,
-    from: (mi) => (mi / 0.621371) as Kilometers
+  .register(KilometersMetadata, MilesMetadata, {
+    to: (km: number) => (km * 0.621371),
+    from: (mi: number) => (mi / 0.621371)
   });
 
 // No direct meters→miles converter registered!
@@ -169,14 +217,34 @@ const date = iso8601.parse('2026-01-06T12:00:00.000Z');
 
 ### Types
 
+#### `WithTypedUnits<M extends TypedMetadata<T>>`
+Brand a value with strongly-typed metadata for compile-time unit safety.
+
+```typescript
+const CelsiusMetadata = { name: 'Celsius' as const, type: 'number' as const };
+type Celsius = WithTypedUnits<typeof CelsiusMetadata>;
+const temp: Celsius = tempRegistry.Celsius(25);
+```
+
 #### `WithUnits<T, U>`
-Brand a value with a unit identifier for compile-time safety.
+Legacy: Brand a value with a unit identifier for compile-time safety.
 
 ```typescript
 type Celsius = WithUnits<number, 'Celsius'>;
 const temp: Celsius = 25 as Celsius;
 ```
 
+#### `TypedMetadata<T>`
+Minimal metadata type with name and type information.
+
+```typescript
+type NumericMetadata = TypedMetadata<number>;
+// { name: string; type: 'number' }
+
+type StringMetadata = TypedMetadata<string>;
+// { name: string; type: 'string' }
+```
+
 #### `WithFormat<T, F>`
 Brand a value with a format identifier for serialization safety.
 
@@ -198,8 +266,8 @@ Pair of converters for two-way transformations.
 
 ```typescript
 const meterKm: BidirectionalConverter<Meters, Kilometers> = {
-  to: (m) => (m / 1000) as Kilometers,
-  from: (km) => (km * 1000) as Meters
+  to: (m: number) => (m / 1000),
+  from: (km: number) => (km * 1000)
 };
 ```
 
@@ -216,14 +284,14 @@ const registry = createRegistry<'A' | 'B' | 'C'>();
 Register a unidirectional converter.
 
 ```typescript
-registry.register('Celsius', 'Fahrenheit', celsiusToFahrenheit);
+registry.register(CelsiusMetadata, FahrenheitMetadata, celsiusToFahrenheit);
 ```
 
-#### `registerBidirectional(from, to, converter)`
+#### `register(from, to, converter)` (bidirectional)
 Register both directions at once.
 
 ```typescript
-registry.registerBidirectional('meters', 'kilometers', meterKm);
+registry.register(MetersMetadata, KilometersMetadata, meterKm);
 ```
 
 #### `convert(value, fromUnit).to(toUnit)`
@@ -243,11 +311,12 @@ const result = registry.convert(value, 'Celsius').to('Fahrenheit');
 
 ## Best Practices
 
-1. **Define unit types at module boundaries** for consistency
+1. **Define metadata as const at module boundaries** for consistency
 2. **Use bidirectional converters** when both directions are needed
 3. **Document precision loss** in converters
 4. **Cache registries** for performance
-5. **Validate with Zod** in parsers
+5. **Use `WithTypedUnits`** for brand-new code; leverage type inference
+6. **Validate with Zod** in parsers
 
 ## Performance
 

package/dist/converters.d.ts

@@ -2,7 +2,7 @@
  * Type-safe converter function signatures
  * @packageDocumentation
  */
-import type { PrimitiveType, Unwrap, WithUnits, Relax as BaseRelax } from './types.js';
+import type { PrimitiveType, Relax as BaseRelax } from './types.js';
 /**
  * Unidirectional converter from one unit to another.
  *
@@ -23,9 +23,9 @@ import type { PrimitiveType, Unwrap, WithUnits, Relax as BaseRelax } from './typ
  *   ((c * 9/5) + 32) as Fahrenheit;
  * ```
  */
-export type Converter<TInput extends WithUnits<PrimitiveType, string>, TOutput extends WithUnits<PrimitiveType, string>> = (input: TInput) => TOutput;
-export type RelaxConverter<ConverterType> = ConverterType extends Converter<infer A, infer B> ? (input: BaseRelax<A>) => BaseRelax<B> : (input: PrimitiveType) => PrimitiveType;
-export type Relax<T extends PrimitiveType | Converter<any, any> | BidirectionalConverter<any, any>> = T extends PrimitiveType ? BaseRelax<T> : T extends Converter<infer A, infer B> ? RelaxConverter<T> : RelaxBidirectionalConverter<T>;
+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;
+export type Relax<T extends PrimitiveType | Converter<any, any> | BidirectionalConverter<any, any>> = T extends PrimitiveType ? BaseRelax<T> : T extends Converter<unknown, unknown> ? RelaxConverter<T> : RelaxBidirectionalConverter<T>;
 /**
  * Bidirectional converter with forward and reverse transformations.
  *
@@ -48,13 +48,13 @@ export type Relax<T extends PrimitiveType | Converter<any, any> | BidirectionalC
  * };
  * ```
  */
-export type BidirectionalConverter<TInput extends WithUnits<PrimitiveType, string>, TOutput extends WithUnits<PrimitiveType, string>> = {
+export type BidirectionalConverter<TInput, TOutput> = {
     to: Converter<TInput, TOutput>;
     from: Converter<TOutput, TInput>;
 };
-export type RelaxBidirectionalConverter<ConverterType> = ConverterType extends BidirectionalConverter<infer A, infer B> ? {
-    to: (input: Unwrap<A> | A) => Unwrap<B> | B;
-    from: (input: Unwrap<B> | B) => Unwrap<A> | A;
+export type RelaxBidirectionalConverter<ConverterType> = ConverterType extends BidirectionalConverter<infer A extends PrimitiveType, infer B extends PrimitiveType> ? {
+    to: (input: BaseRelax<A>) => B;
+    from: (input: BaseRelax<B>) => A;
 } : {
     to: (input: PrimitiveType) => PrimitiveType;
     from: (input: PrimitiveType) => PrimitiveType;

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,MAAM,EAAE,SAAS,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,SAAS,CACnB,MAAM,SAAS,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,EAC/C,OAAO,SAAS,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,IAC9C,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE/B,MAAM,MAAM,cAAc,CAAC,aAAa,IACtC,aAAa,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC7C,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,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,GACjB,2BAA2B,CAAC,CAAC,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,sBAAsB,CAChC,MAAM,SAAS,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,EAC/C,OAAO,SAAS,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,IAC9C;IACF,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,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC1D;IACE,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CAC/C,GACD;IACE,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;IAC5C,IAAI,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,aAAa,CAAC;CAC/C,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,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;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"}

package/dist/index.d.ts

@@ -2,10 +2,10 @@
  * Unacy Core - Type-safe unit and format conversion library
  * @packageDocumentation
  */
-export type { WithUnits, WithFormat, UnitMetadata } from './types.js';
+export type { WithUnits, WithTypedUnits, WithFormat, BaseMetadata, TypedMetadata, UnitMetadata, Relax, PrimitiveType, ToPrimitiveType, ToPrimitiveTypeName } from './types.js';
 export type { Converter, BidirectionalConverter } from './converters.js';
 export type { Formatter, Parser, FormatterParser } from './formatters.js';
-export type { ConverterRegistry } from './registry.js';
+export type { UnitRegistry, UnitMap, UnitAccessor } from './registry.js';
 export { createRegistry } from './registry.js';
 export { UnacyError, CycleError, MaxDepthError, ConversionError, ParseError } from './errors.js';
 export { createParserWithSchema } from './utils/validation.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGtE,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGzE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAG1E,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGjG,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,SAAS,EACT,cAAc,EACd,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,KAAK,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGzE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAG1E,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGjG,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjG,YAAY;AACZ,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwBH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjG,YAAY;AACZ,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/registry.d.ts

@@ -3,11 +3,13 @@
  * @packageDocumentation
  */
 import type { Converter, BidirectionalConverter, Relax } from './converters.js';
-import type { OptionalWithUnits, UnitsFor, WithUnits, UnitMetadata } from './types.js';
+import type { UnitsFor, WithUnits, TypedMetadata, NameFor, WithTypedUnits, UnitsOf, BaseMetadata, PrimitiveType, Relax as RelaxUnits } from './types.js';
 /**
  * Represents a conversion edge from one unit to another
+ * Edges store the unit names as strings, but the type system ensures
+ * they correspond to valid WithUnits types
  */
-type Edge<From extends string = string, To extends string = string> = readonly [From, To];
+type Edge<From extends WithTypedUnits<any> = WithTypedUnits<TypedMetadata<PrimitiveType>>, To extends WithTypedUnits<any> = WithTypedUnits<TypedMetadata<PrimitiveType>>> = readonly [From, To];
 /**
  * Extract all unique 'from' units from a list of edges
  */
@@ -15,83 +17,75 @@ type FromUnits<Edges extends readonly Edge[]> = Edges[number][0];
 /**
  * Extract all 'to' units for a specific 'from' unit string
  */
-type ToUnitsFor<Edges extends readonly Edge[], FromUnit extends string> = Extract<Edges[number], readonly [FromUnit, any]>[1];
+type ToUnitsFor<Edges extends readonly Edge[], FromUnit extends WithTypedUnits<any>> = Extract<Edges[number], readonly [FromUnit, any]>[1];
+/**
+ * Extract metadata type from a WithUnits type
+ */
 /**
  * Type for unit accessor with metadata and conversion methods
  * Can be called as a function to create branded unit values
  */
-export type UnitAccessor<From extends string, Edges extends readonly Edge[]> = {
+export type UnitAccessor<From extends WithTypedUnits<TypedMetadata>, Edges extends readonly Edge[]> = {
     /**
      * Create a branded value with this unit
      * @param value - The numeric value to brand
      * @returns The value branded with this unit type
      */
-    (value: number): WithUnits<number, From>;
+    (value: number): From;
     to: {
-        [To in ToUnitsFor<Edges, From>]: (value: OptionalWithUnits<number, From>) => WithUnits<number, To>;
+        [To in ToUnitsFor<Edges, From> as UnitsFor<To>]: (value: RelaxUnits<From>) => To;
     };
     /**
      * Add metadata to this unit
      */
-    addMetadata(metadata: UnitMetadata): ConverterRegistry<Edges extends readonly (infer E)[] ? E[] : never> & ConverterMap<Edges>;
+    addMetadata<NewM extends Record<string, unknown>>(metadata: NewM): UnitRegistry<Edges extends readonly (infer E)[] ? E[] : never> & UnitMap<Edges>;
     /**
      * Register a converter from this unit to another unit
      */
-    register<To extends string>(to: To, converter: Relax<Converter<WithUnits<number, From>, WithUnits<number, To>>>): ConverterRegistry<[...Edges, Edge<From, To>]> & ConverterMap<[...Edges, Edge<From, To>]>;
-    register<To extends string>(to: To, converter: Relax<BidirectionalConverter<WithUnits<number, From>, WithUnits<number, To>>>): ConverterRegistry<[...Edges, Edge<From, To>, Edge<To, From>]> & ConverterMap<[...Edges, Edge<From, To>, Edge<To, From>]>;
-} & {
-    [K: string]: unknown;
-};
+    register<To extends WithTypedUnits<ToMeta>, ToMeta extends TypedMetadata<PrimitiveType>>(to: UnitsFor<To> | ToMeta, converter: Relax<Converter<From, To>>): UnitRegistry<[...Edges, Edge<From, To>]> & UnitMap<[...Edges, Edge<From, To>]>;
+    register<To extends WithTypedUnits<ToMeta>, ToMeta extends TypedMetadata<PrimitiveType>>(to: UnitsFor<To> | ToMeta, converter: Relax<BidirectionalConverter<From, To>>): UnitRegistry<[...Edges, Edge<From, To>, Edge<To, From>]> & UnitMap<[...Edges, Edge<From, To>, Edge<To, From>]>;
+} & UnitsOf<From>;
 /**
  * Type for unit-based conversion accessors
  * Provides the shape: registry.Celsius.to.Fahrenheit(value)
  * Only allows conversions that have been registered
  */
-export type ConverterMap<Edges extends readonly Edge[]> = {
-    [From in FromUnits<Edges>]: UnitAccessor<From, Edges>;
+export type UnitMap<Edges extends readonly Edge[]> = {
+    [FU in FromUnits<Edges> as UnitsFor<FU>]: UnitAccessor<FU, Edges>;
 };
 /**
  * Registry for managing and composing unit converters
  */
-export interface ConverterRegistry<Edges extends Edge[] = []> {
+export interface UnitRegistry<Edges extends Edge[] = []> {
+    register<From extends WithTypedUnits<FromMeta>, FromMeta extends TypedMetadata<PrimitiveType>>(unit: FromMeta): this & {
+        [K in NameFor<From>]: UnitAccessor<From, Edges>;
+    };
     /**
      * Register a unidirectional converter
      *
-     * @param from - Source unit
-     * @param to - Destination unit
+     * @param from - Source unit (string name or metadata object)
+     * @param to - Destination unit (string name or metadata object)
      * @param converter - Converter function
      * @returns New registry instance with the converter registered
      */
-    register<From extends WithUnits<number, UF>, To extends WithUnits<number, UY>, UF extends string, UY extends string>(from: UF, to: UY, converter: Relax<Converter<From, To>>): ConverterRegistry<[...Edges, Edge<UnitsFor<From>, UnitsFor<To>>]> & ConverterMap<[...Edges, Edge<UnitsFor<From>, UnitsFor<To>>]>;
+    register<From extends WithTypedUnits<FromMeta>, To extends WithTypedUnits<ToMeta>, FromMeta extends TypedMetadata<PrimitiveType>, ToMeta extends TypedMetadata<PrimitiveType>>(from: UnitsFor<From> | FromMeta, to: UnitsFor<To> | ToMeta, converter: Converter<From, RelaxUnits<To>>): UnitRegistry<[...Edges, Edge<From, To>]> & UnitMap<[...Edges, Edge<From, To>]>;
     /**
      * Register a bidirectional converter (both directions)
      *
-     * @param from - First unit
-     * @param to - Second unit
+     * @param from - First unit (string name or metadata object)
+     * @param to - Second unit (string name or metadata object)
      * @param converter - Bidirectional converter object
      * @returns New registry instance with both converters registered
      */
-    register<From extends WithUnits<number, string>, To extends WithUnits<number, string>>(from: UnitsFor<From> | {
-        name: UnitsFor<From>;
-    }, to: UnitsFor<To> | {
-        name: UnitsFor<To>;
-    }, converter: Relax<BidirectionalConverter<From, To>>): ConverterRegistry<[
-        ...Edges,
-        Edge<UnitsFor<From>, UnitsFor<To>>,
-        Edge<UnitsFor<To>, UnitsFor<From>>
-    ]> & ConverterMap<[
-        ...Edges,
-        Edge<UnitsFor<From>, UnitsFor<To>>,
-        Edge<UnitsFor<To>, UnitsFor<From>>
-    ]>;
+    register<From extends WithTypedUnits<FromMeta>, To extends WithTypedUnits<ToMeta>, FromMeta extends TypedMetadata<PrimitiveType>, ToMeta extends TypedMetadata<PrimitiveType>>(from: UnitsFor<From> | FromMeta, to: UnitsFor<To> | ToMeta, converter: BidirectionalConverter<RelaxUnits<From>, RelaxUnits<To>>): UnitRegistry<[...Edges, Edge<From, To>, Edge<To, From>]> & UnitMap<[...Edges, Edge<From, To>, Edge<To, From>]>;
     /**
      * Explicitly allow a conversion path in the type system (for multi-hop conversions)
      *
      * This method verifies that a conversion path exists at runtime (via BFS) and adds it
      * to the type system so it can be used with type-safe accessor syntax.
      *
-     * @param from - Source unit string
-     * @param to - Destination unit string
+     * @param from - Source unit (string name or metadata object)
+     * @param to - Destination unit (string name or metadata object)
      * @returns New registry instance with the conversion path enabled in types
      * @throws ConversionError if no path exists between the units
      *
@@ -106,7 +100,7 @@ export interface ConverterRegistry<Edges extends Edge[] = []> {
      * const f = registry.Celsius.to.Fahrenheit(temp);
      * ```
      */
-    allow<From extends string, To extends string>(from: From, to: To): ConverterRegistry<[...Edges, Edge<From, To>]> & ConverterMap<[...Edges, Edge<From, To>]>;
+    allow<From extends WithTypedUnits<FromMeta>, To extends WithTypedUnits<ToMeta>, FromMeta extends TypedMetadata<PrimitiveType>, ToMeta extends TypedMetadata<PrimitiveType>>(from: UnitsFor<From> | FromMeta, to: UnitsFor<To> | ToMeta): UnitRegistry<[...Edges, Edge<From, To>]> & UnitMap<[...Edges, Edge<From, To>]>;
     /**
      * Get a converter (direct or composed via BFS)
      *
@@ -114,7 +108,7 @@ export interface ConverterRegistry<Edges extends Edge[] = []> {
      * @param to - Destination unit
      * @returns Converter function, or undefined if no path exists
      */
-    getConverter<From extends WithUnits<number, string>, To extends WithUnits<number, string>>(from: UnitsFor<From>, to: UnitsFor<To>): Converter<From, To> | undefined;
+    getConverter<From extends WithUnits<PrimitiveType, BaseMetadata>, To extends WithUnits<PrimitiveType, BaseMetadata>>(from: UnitsFor<From>, to: UnitsFor<To>): Converter<From, To> | undefined;
     /**
      * Convert a value using fluent API
      *
@@ -122,8 +116,8 @@ export interface ConverterRegistry<Edges extends Edge[] = []> {
      * @param fromUnit - Source unit
      * @returns Object with to() method for conversion
      */
-    convert<From extends WithUnits<number, string>>(value: From, fromUnit: UnitsFor<From>): {
-        to<To extends WithUnits<number, string>>(unit: UnitsFor<To>): To;
+    convert<From extends WithUnits<PrimitiveType, BaseMetadata>>(value: From, fromUnit: UnitsFor<From>): {
+        to<To extends WithUnits<PrimitiveType, BaseMetadata>>(unit: UnitsFor<To>): To;
     };
 }
 /**
@@ -134,10 +128,10 @@ export interface ConverterRegistry<Edges extends Edge[] = []> {
  *
  * @example
  * ```typescript
- * type Celsius = WithUnits<number, 'Celsius'>;
- * type Fahrenheit = WithUnits<number, 'Fahrenheit'>;
- * type Meters = WithUnits<number, 'meters'>;
- * type Kilometers = WithUnits<number, 'kilometers'>;
+ * type Celsius = WithUnits<PrimitiveType, 'Celsius'>;
+ * type Fahrenheit = WithUnits<PrimitiveType, 'Fahrenheit'>;
+ * type Meters = WithUnits<PrimitiveType, 'meters'>;
+ * type Kilometers = WithUnits<PrimitiveType, 'kilometers'>;
  *
  * // Without pre-declared units
  * const registry = createRegistry()
@@ -152,6 +146,6 @@ export interface ConverterRegistry<Edges extends Edge[] = []> {
  * console.log(fahrenheit); // 77
  * ```
  */
-export declare function createRegistry<Edges extends readonly Edge[] = []>(): ConverterRegistry<Edges extends readonly (infer E)[] ? E[] : never> & ConverterMap<Edges>;
+export declare function createRegistry<Edges extends readonly Edge[] = []>(): UnitRegistry<Edges extends readonly (infer E)[] ? E[] : never> & UnitMap<Edges>;
 export {};
 //# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAIvF;;GAEG;AACH,KAAK,IAAI,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAE1F;;GAEG;AACH,KAAK,SAAS,CAAC,KAAK,SAAS,SAAS,IAAI,EAAE,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE;;GAEG;AACH,KAAK,UAAU,CAAC,KAAK,SAAS,SAAS,IAAI,EAAE,EAAE,QAAQ,SAAS,MAAM,IAAI,OAAO,CAC/E,KAAK,CAAC,MAAM,CAAC,EACb,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,CACzB,CAAC,CAAC,CAAC,CAAC;AAEL;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,SAAS,SAAS,IAAI,EAAE,IAAI;IAC7E;;;;OAIG;IACH,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzC,EAAE,EAAE;SACD,EAAE,IAAI,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAC/B,KAAK,EAAE,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,KACP,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;KACvD,CAAC;IACF;;OAEG;IACH,WAAW,CACT,QAAQ,EAAE,YAAY,GACrB,iBAAiB,CAAC,KAAK,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7F;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EACxB,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,GAC1E,iBAAiB,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5F,QAAQ,CAAC,EAAE,SAAS,MAAM,EACxB,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,KAAK,CAAC,sBAAsB,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,GACvF,iBAAiB,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,GAC9D,YAAY,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;CAC5D,GAAG;IAEF,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,SAAS,IAAI,EAAE,IAAI;KACvD,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE;IAC1D;;;;;;;OAOG;IACH,QAAQ,CACN,IAAI,SAAS,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,EAClC,EAAE,SAAS,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,EAChC,EAAE,SAAS,MAAM,EACjB,EAAE,SAAS,MAAM,EAEjB,IAAI,EAAE,EAAE,EACR,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GACpC,iBAAiB,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAClE,YAAY,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,SAAS,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,SAAS,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACnF,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG;QAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAA;KAAE,EAC/C,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG;QAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAA;KAAE,EACzC,SAAS,EAAE,KAAK,CAAC,sBAAsB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GACjD,iBAAiB,CAClB;QAAC,GAAG,KAAK;QAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;KAAC,CACnF,GACC,YAAY,CACV;QAAC,GAAG,KAAK;QAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;KAAC,CACnF,CAAC;IAIJ;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,EAC1C,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,EAAE,GACL,iBAAiB,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5F;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,SAAS,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,SAAS,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACvF,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,EACpB,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,GACf,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,SAAS,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5C,KAAK,EAAE,IAAI,EACX,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,GACvB;QACD,EAAE,CAAC,EAAE,SAAS,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC;KAClE,CAAC;CACH;AAgRD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,SAAS,IAAI,EAAE,GAAG,EAAE,KAAK,iBAAiB,CACrF,KAAK,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,KAAK,CACjD,GACC,YAAY,CAAC,KAAK,CAAC,CAEpB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/registry.js

@@ -112,38 +112,68 @@ class ConverterRegistryImpl {
             this.unitAccessors.set(fromUnit, accessorProxy);
         }
     }
+    // Implementation
     register(from, to, converter) {
+        // Handle single unit registration (overload 1)
+        if (to === undefined && converter === undefined) {
+            const unitMetadata = from;
+            const newMetadata = new Map(this.metadata);
+            const unitName = unitMetadata.name;
+            const existingMetadata = newMetadata.get(unitName) || {};
+            newMetadata.set(unitName, { ...existingMetadata, ...unitMetadata });
+            return createRegistryFromGraph(this.graph, this.pathCache, newMetadata);
+        }
+        // Extract metadata if provided and store unit names
+        let fromName;
+        let toName;
+        const newMetadata = new Map(this.metadata);
         if (typeof from === 'object' && 'name' in from) {
-            from = from.name;
+            fromName = from.name;
+            // Store metadata for the from unit
+            const existingFromMetadata = newMetadata.get(fromName) || {};
+            newMetadata.set(fromName, { ...existingFromMetadata, ...from });
+        }
+        else {
+            fromName = from;
         }
         if (typeof to === 'object' && 'name' in to) {
-            to = to.name;
+            toName = to.name;
+            // Store metadata for the to unit
+            const existingToMetadata = newMetadata.get(toName) || {};
+            newMetadata.set(toName, { ...existingToMetadata, ...to });
+        }
+        else {
+            toName = to;
         }
         // Check if it's a bidirectional converter
         if (typeof converter === 'object' && 'to' in converter && 'from' in converter) {
             // Handle bidirectional converter
             const biConverter = converter;
+            // Pass the original metadata objects (not just names) to preserve metadata
             return this.register(from, to, biConverter.to).register(to, from, biConverter.from);
         }
         // Handle unidirectional converter
         const newGraph = new Map(this.graph);
-        if (!newGraph.has(from)) {
-            newGraph.set(from, new Map());
+        if (!newGraph.has(fromName)) {
+            newGraph.set(fromName, new Map());
         }
-        const fromMap = new Map(newGraph.get(from));
-        fromMap.set(to, converter);
-        newGraph.set(from, fromMap);
+        const fromMap = new Map(newGraph.get(fromName));
+        fromMap.set(toName, converter);
+        newGraph.set(fromName, fromMap);
         // Return new registry instance (immutable) with proxy
-        return createRegistryFromGraph(newGraph, new Map(), this.metadata);
+        return createRegistryFromGraph(newGraph, new Map(), newMetadata);
     }
     registerBidirectional(from, to, converter) {
         return this.register(from, to, converter.to).register(to, from, converter.from);
     }
     allow(from, to) {
+        // Extract unit names from metadata objects if provided
+        const fromName = typeof from === 'object' && 'name' in from ? from.name : from;
+        const toName = typeof to === 'object' && 'name' in to ? to.name : to;
         // Verify that a conversion path exists at runtime
-        const converter = this.getConverter(from, to);
+        const converter = this.getConverter(fromName, toName);
         if (!converter) {
-            throw new ConversionError(from, to, 'No conversion path exists');
+            throw new ConversionError(fromName, toName, 'No conversion path exists');
         }
         // Return the same registry instance with updated type information
         // The actual conversion already works via BFS, we just need to expose it in types
@@ -208,10 +238,10 @@ class ConverterRegistryImpl {
  *
  * @example
  * ```typescript
- * type Celsius = WithUnits<number, 'Celsius'>;
- * type Fahrenheit = WithUnits<number, 'Fahrenheit'>;
- * type Meters = WithUnits<number, 'meters'>;
- * type Kilometers = WithUnits<number, 'kilometers'>;
+ * type Celsius = WithUnits<PrimitiveType, 'Celsius'>;
+ * type Fahrenheit = WithUnits<PrimitiveType, 'Fahrenheit'>;
+ * type Meters = WithUnits<PrimitiveType, 'meters'>;
+ * type Kilometers = WithUnits<PrimitiveType, 'kilometers'>;
  *
  * // Without pre-declared units
  * const registry = createRegistry()