@penner/smart-primitive 0.0.1 → 0.1.0

package/dist/SmartPrimitive.d.ts

@@ -1,7 +1,8 @@
 /**
- * 🔧 FEATURE FLAG: Toggle smart primitive type checking
- * When false (default): SmartPrimitive types provide type safety
- * When true: All SmartNumber, SmartString, etc. become plain primitives
+ * 🔧 CONFIGURATION: Toggle smart primitive type checking
+ *
+ * When `usePlainPrimitives` is false (default): SmartPrimitive types provide type safety
+ * When `usePlainPrimitives` is true: All SmartNumber, SmartString, etc. become plain primitives
  *
  * Use cases:
  * - Performance testing (eliminate type overhead)
@@ -9,26 +10,39 @@
  * - Gradual migration to/from smart primitives
  * - Bundle size optimization
  *
- * How to use:
- * 1. Change `false` to `true` below
- * 2. Your entire codebase now treats Pixels, URLs, etc. as plain primitives
- * 3. Cross-brand assignments that were errors become allowed
- * 4. All type extraction utilities become no-ops
- * 5. Change back to `false` to re-enable smart primitive type safety
+ * How to configure (module augmentation):
+ * ```ts
+ * // In a .d.ts file in your project (e.g., smart-primitive.d.ts):
+ * declare module '@penner/smart-primitive' {
+ *   interface SmartPrimitiveConfig {
+ *     usePlainPrimitives: true;
+ *   }
+ * }
+ * ```
+ *
+ * This uses TypeScript's declaration merging so consumers can override the
+ * default without modifying the library source.
  */
-export declare const USE_PLAIN_PRIMITIVES: false;
-export type USE_PLAIN_PRIMITIVES_TYPE = typeof USE_PLAIN_PRIMITIVES;
 /**
- * Clean type extraction using the brand pattern
- * Respects the USE_PLAIN_PRIMITIVES flag.
+ * Configuration interface for SmartPrimitive behavior.
+ * Empty by default — consumers augment this to add properties.
+ *
+ * To disable branded types, augment with `usePlainPrimitives: true`.
+ * The interface is intentionally empty so that declaration merging
+ * can add the property (TypeScript doesn't allow changing a property's type).
  */
-type BaseOf<T> = USE_PLAIN_PRIMITIVES_TYPE extends true ? T : T extends number & {
-    readonly __brand?: unknown;
-} ? number : T extends string & {
-    readonly __brand?: unknown;
-} ? string : T extends boolean & {
-    readonly __brand?: unknown;
-} ? boolean : T;
+export interface SmartPrimitiveConfig {
+}
+/**
+ * Resolves to `true` when SmartPrimitiveConfig has been augmented with
+ * `usePlainPrimitives: true`, otherwise defaults to `false`.
+ */
+export type UsePlainPrimitives = SmartPrimitiveConfig extends {
+    usePlainPrimitives: infer V;
+} ? V : false;
+interface Brand<BrandName extends string> {
+    readonly _brand?: BrandName;
+}
 /**
  * Generic smart primitive type that provides **opt-in type safety** while staying flexible.
  *
@@ -36,7 +50,7 @@ type BaseOf<T> = USE_PLAIN_PRIMITIVES_TYPE extends true ? T : T extends number &
  * - ✅ **Accepts plain values**: You can use regular numbers, strings, etc. directly
  * - ✅ **Prevents cross-domain mixing**: TypeScript stops you from using pixels where milliseconds are expected
  * - ✅ **Zero runtime cost**: No performance impact - it's just TypeScript magic
- * - ✅ **Easy to disable**: Toggle `USE_PLAIN_PRIMITIVES` to turn off all smart typing
+ * - ✅ **Easy to disable**: Augment `SmartPrimitiveConfig` to turn off all smart typing
  *
  * **Example:**
  * ```ts
@@ -51,9 +65,7 @@ type BaseOf<T> = USE_PLAIN_PRIMITIVES_TYPE extends true ? T : T extends number &
  * This prevents bugs like accidentally using milliseconds where pixels are expected,
  * while keeping your code simple and readable.
  */
-export type SmartPrimitive<Base extends string | number | boolean | bigint | symbol, BrandName extends string> = USE_PLAIN_PRIMITIVES_TYPE extends true ? Base : Base & {
-    readonly __brand?: BrandName;
-};
+export type SmartPrimitive<Base extends string | number | boolean | bigint | symbol, BrandName extends string> = UsePlainPrimitives extends true ? Base : Base & Brand<BrandName>;
 /**
  * A smart number type for domain-specific numeric values like pixels, milliseconds, etc.
  *
@@ -67,7 +79,7 @@ export type SmartPrimitive<Base extends string | number | boolean | bigint | sym
  * - ✅ Catches domain mix-ups: `let width: Pixels = duration` → TypeScript error
  * - ✅ Zero runtime cost: Just TypeScript checking, no JavaScript overhead
  *
- * Built on `SmartPrimitive` - respects the USE_PLAIN_PRIMITIVES flag for easy toggling.
+ * Built on `SmartPrimitive` - respects `SmartPrimitiveConfig` for easy toggling.
  *
  * **Example:**
  * ```ts
@@ -79,16 +91,16 @@ export type SmartPrimitive<Base extends string | number | boolean | bigint | sym
  * let badAssign: Pixels = delay;  // ❌ type error - caught the mistake!
  * ```
  *
- * When USE_PLAIN_PRIMITIVES = false (default):
+ * When `usePlainPrimitives` is false (default):
  * - Full smart number system with type safety between different units
  * - Plain numbers accepted seamlessly
  * - Clean tooltip display
  *
- * When USE_PLAIN_PRIMITIVES = true:
+ * When `usePlainPrimitives` is true:
  * - All smart number types collapse to plain `number`
  * - Zero runtime overhead, maximum performance
  *
- * Usage remains the same regardless of flag state:
+ * Usage remains the same regardless of config:
  * ```ts
  * let distance: Pixels = 300;           // ✅ always works
  * let branded: Pixels = 300 as Pixels;  // ✅ always works
@@ -125,20 +137,58 @@ export type SmartString<BrandName extends string> = SmartPrimitive<string, Brand
  * ```
  */
 export type SmartBoolean<BrandName extends string> = SmartPrimitive<boolean, BrandName>;
+/**
+ * A smart bigint type that accepts plain `bigint` values but maintains
+ * a distinct branded identity.
+ *
+ * Useful for domain-specific big integers such as IDs or counters where
+ * accidental mixing with other numeric types should be prevented.
+ *
+ * Usage:
+ * ```ts
+ * type EntityId = SmartBigInt<'EntityId'>;
+ * type UserId = SmartBigInt<'UserId'>;
+ * let id: EntityId = 123n;               // ✅ works
+ * let user: UserId = 456n;               // ✅ works
+ * let badAssign: EntityId = user;        // ❌ type error
+ * ```
+ */
+export type SmartBigInt<BrandName extends string> = SmartPrimitive<bigint, BrandName>;
+/**
+ * A smart symbol type that accepts plain `symbol` values but maintains
+ * a distinct branded identity.
+ *
+ * Useful for domain-specific symbol tokens (e.g. event types, internal
+ * keys) where mixing distinct tokens should be prevented by the type system.
+ *
+ * Usage:
+ * ```ts
+ * type EventType = SmartSymbol<'EventType'>;
+ * type Token = SmartSymbol<'Token'>;
+ * let e: EventType = Symbol('click');    // ✅ works
+ * let t: Token = Symbol('auth');         // ✅ works
+ * let badAssign: EventType = t;          // ❌ type error
+ * ```
+ */
+export type SmartSymbol<BrandName extends string> = SmartPrimitive<symbol, BrandName>;
 /**
  * Simplified Unbrand using the generic brand pattern.
- * Also respects the USE_PLAIN_PRIMITIVES flag.
+ * Also respects the `SmartPrimitiveConfig` toggle.
  *
- * When USE_PLAIN_PRIMITIVES = true: This becomes a no-op (types pass through unchanged)
- * When USE_PLAIN_PRIMITIVES = false: Full unbranding to base types
+ * When `usePlainPrimitives` is true: This becomes a no-op (types pass through unchanged)
+ * When `usePlainPrimitives` is false (default): Full unbranding to base types
  */
-export type Unbrand<T> = USE_PLAIN_PRIMITIVES_TYPE extends true ? T : T extends number & {
-    readonly __brand?: unknown;
+export type Unbrand<T> = UsePlainPrimitives extends true ? T : T extends number & {
+    readonly _brand?: unknown;
 } ? number : T extends string & {
-    readonly __brand?: unknown;
+    readonly _brand?: unknown;
 } ? string : T extends boolean & {
-    readonly __brand?: unknown;
-} ? boolean : T extends Record<string, unknown> ? {
+    readonly _brand?: unknown;
+} ? boolean : T extends bigint & {
+    readonly _brand?: unknown;
+} ? bigint : T extends symbol & {
+    readonly _brand?: unknown;
+} ? symbol : T extends Record<string, unknown> ? {
     [K in keyof T]: Unbrand<T[K]>;
 } : T;
 /**
@@ -149,5 +199,5 @@ export type Unbrand<T> = USE_PLAIN_PRIMITIVES_TYPE extends true ? T : T extends
 export type UnbrandFn<F, UnbrandReturn extends boolean = false> = F extends (...args: infer A) => infer R ? A extends readonly unknown[] ? (...args: {
     [K in keyof A]: Unbrand<A[K]>;
 }) => UnbrandReturn extends true ? Unbrand<R> : R : never : never;
-export type { BaseOf };
+export {};
 //# sourceMappingURL=SmartPrimitive.d.ts.map

package/dist/SmartPrimitive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SmartPrimitive.d.ts","sourceRoot":"","sources":["../src/SmartPrimitive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,eAAO,MAAM,oBAAoB,EAAG,KAAc,CAAC;AACnD,MAAM,MAAM,yBAAyB,GAAG,OAAO,oBAAoB,CAAC;AAEpE;;;GAGG;AACH,KAAK,MAAM,CAAC,CAAC,IAAI,yBAAyB,SAAS,IAAI,GACnD,CAAC,GACD,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,MAAM,GACN,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,MAAM,GACN,CAAC,SAAS,OAAO,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,GACP,CAAC,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,cAAc,CACxB,IAAI,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,EACxD,SAAS,SAAS,MAAM,IACtB,yBAAyB,SAAS,IAAI,GACtC,IAAI,GACJ,IAAI,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CACjE,OAAO,EACP,SAAS,CACV,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,yBAAyB,SAAS,IAAI,GAC3D,CAAC,GAGD,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,MAAM,GACN,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,MAAM,GACN,CAAC,SAAS,OAAO,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,GAEP,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAEjC,CAAC,CAAC;AAEd;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,aAAa,SAAS,OAAO,GAAG,KAAK,IAAI,CAAC,SAAS,CAC1E,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,MAAM,CAAC,GACR,CAAC,SAAS,SAAS,OAAO,EAAE,GAC1B,CACE,GAAG,IAAI,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,KACvC,aAAa,SAAS,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAChD,KAAK,GACP,KAAK,CAAC;AAGV,YAAY,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"SmartPrimitive.d.ts","sourceRoot":"","sources":["../src/SmartPrimitive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;GAOG;AAEH,MAAM,WAAW,oBAAoB;CAAG;AAExC;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,SAAS;IAC5D,kBAAkB,EAAE,MAAM,CAAC,CAAC;CAC7B,GACG,CAAC,GACD,KAAK,CAAC;AAGV,UAAU,KAAK,CAAC,SAAS,SAAS,MAAM;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,cAAc,CACxB,IAAI,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,EACxD,SAAS,SAAS,MAAM,IACtB,kBAAkB,SAAS,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CACjE,OAAO,EACP,SAAS,CACV,CAAC;AACF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,kBAAkB,SAAS,IAAI,GACpD,CAAC,GAGD,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,GACN,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,GACN,CAAC,SAAS,OAAO,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,OAAO,GACP,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,GACN,CAAC,SAAS,MAAM,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,GAEN,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAEjC,CAAC,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,aAAa,SAAS,OAAO,GAAG,KAAK,IAAI,CAAC,SAAS,CAC1E,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,MAAM,CAAC,GACR,CAAC,SAAS,SAAS,OAAO,EAAE,GAC1B,CACE,GAAG,IAAI,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,KACvC,aAAa,SAAS,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAChD,KAAK,GACP,KAAK,CAAC"}

package/dist/SmartPrimitive.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmartPrimitive.test-d.d.ts","sourceRoot":"","sources":["../src/SmartPrimitive.test-d.ts"],"names":[],"mappings":""}

package/dist/SmartPrimitiveConfig.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=SmartPrimitiveConfig.test-d.d.ts.map

package/dist/SmartPrimitiveConfig.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmartPrimitiveConfig.test-d.d.ts","sourceRoot":"","sources":["../src/SmartPrimitiveConfig.test-d.ts"],"names":[],"mappings":""}

package/dist/convert.cjs.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function n(e){return(r=>e(r))}function i(e,r){return{to:n(e),from:n(r)}}function c(e){return i(r=>r*e,r=>r/e)}function s(e){return(r=>(e&&e(r),r))}function u(e,r){return(t=>r(e(t)))}function v(){return(e=>e)}class a{constructor(){this.converters=new Map}register(r,t){return this.converters.set(r,t),this}convert(r,t){const o=this.converters.get(t);if(!o)throw new Error(`No converter registered for target: ${t}`);return o(r)}has(r){return this.converters.has(r)}}exports.ConverterRegistry=a;exports.chain=u;exports.createBiConverter=i;exports.createConverter=n;exports.createLinearConverter=c;exports.createStringConverter=s;exports.identity=v;
+//# sourceMappingURL=convert.cjs.js.map

package/dist/convert.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.cjs.js","sources":["../src/convert.ts"],"sourcesContent":["/**\n * 🔄 Conversion Utilities for Smart Primitives\n *\n * Type-safe conversion functions between branded types with a clean factory pattern.\n * Supports both one-way and bidirectional conversions.\n */\n\nimport type { SmartNumber, SmartString } from './SmartPrimitive';\n\n/* ═══════════════════════════════════════════════════════════════\n   CORE CONVERSION TYPES\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * A type-safe conversion function from one branded type to another.\n *\n * @example\n * ```ts\n * const degreesToRadians: Converter<Degrees, Radians> = (deg) => (deg * Math.PI / 180) as Radians;\n * ```\n */\nexport type Converter<From, To> = (value: From) => To;\n\n/**\n * A bidirectional converter with forward and reverse operations.\n *\n * @example\n * ```ts\n * const degreesRadians: BiConverter<Degrees, Radians> = {\n *   to: (deg) => (deg * Math.PI / 180) as Radians,\n *   from: (rad) => (rad * 180 / Math.PI) as Degrees,\n * };\n * ```\n */\nexport interface BiConverter<A, B> {\n  /** Convert from A to B */\n  to: Converter<A, B>;\n  /** Convert from B to A */\n  from: Converter<B, A>;\n}\n\n/* ═══════════════════════════════════════════════════════════════\n   CONVERSION FACTORY\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Create a type-safe converter between two branded number types.\n *\n * @param transform - The mathematical transformation function\n * @returns A typed converter function\n *\n * @example\n * ```ts\n * type Celsius = SmartNumber<'Celsius'>;\n * type Fahrenheit = SmartNumber<'Fahrenheit'>;\n *\n * const celsiusToFahrenheit = createConverter<Celsius, Fahrenheit>(c => c * 9/5 + 32);\n * const temp: Fahrenheit = celsiusToFahrenheit(100 as Celsius); // 212\n * ```\n */\nexport function createConverter<\n  From extends SmartNumber<string>,\n  To extends SmartNumber<string>,\n>(transform: (value: number) => number): Converter<From, To> {\n  return ((value: From) => transform(value) as To) as Converter<From, To>;\n}\n\n/**\n * Create a bidirectional converter between two branded number types.\n *\n * @param toTransform - Transform from A to B\n * @param fromTransform - Transform from B to A\n * @returns A BiConverter with both directions\n *\n * @example\n * ```ts\n * const celsiusFahrenheit = createBiConverter<Celsius, Fahrenheit>(\n *   c => c * 9/5 + 32,\n *   f => (f - 32) * 5/9\n * );\n *\n * celsiusFahrenheit.to(0 as Celsius);     // 32 as Fahrenheit\n * celsiusFahrenheit.from(32 as Fahrenheit); // 0 as Celsius\n * ```\n */\nexport function createBiConverter<\n  A extends SmartNumber<string>,\n  B extends SmartNumber<string>,\n>(\n  toTransform: (value: number) => number,\n  fromTransform: (value: number) => number,\n): BiConverter<A, B> {\n  return {\n    to: createConverter<A, B>(toTransform),\n    from: createConverter<B, A>(fromTransform),\n  };\n}\n\n/**\n * Create a linear converter (multiply by factor).\n * Useful for unit conversions with simple ratios.\n *\n * @param factor - The multiplication factor (A * factor = B)\n * @returns A BiConverter using the linear relationship\n *\n * @example\n * ```ts\n * // 1 meter = 100 centimeters\n * const metersCentimeters = createLinearConverter<Meters, Centimeters>(100);\n *\n * metersCentimeters.to(2 as Meters);       // 200 as Centimeters\n * metersCentimeters.from(50 as Centimeters); // 0.5 as Meters\n * ```\n */\nexport function createLinearConverter<\n  A extends SmartNumber<string>,\n  B extends SmartNumber<string>,\n>(factor: number): BiConverter<A, B> {\n  return createBiConverter<A, B>(\n    a => a * factor,\n    b => b / factor,\n  );\n}\n\n/**\n * Create a converter for string types with validation.\n *\n * @param validate - Optional validation function (throws on invalid input)\n * @returns A converter that casts strings to the target type\n *\n * @example\n * ```ts\n * type URL = SmartString<'URL'>;\n *\n * const toURL = createStringConverter<string, URL>((s) => {\n *   if (!s.startsWith('http')) throw new Error('Invalid URL');\n * });\n *\n * const url: URL = toURL('https://example.com'); // ✅\n * const bad: URL = toURL('not-a-url');           // ❌ throws\n * ```\n */\nexport function createStringConverter<\n  From extends string,\n  To extends SmartString<string>,\n>(validate?: (value: From) => void): Converter<From, To> {\n  return ((value: From) => {\n    if (validate) validate(value);\n    return value as unknown as To;\n  }) as Converter<From, To>;\n}\n\n/* ═══════════════════════════════════════════════════════════════\n   CHAINING & COMPOSITION\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Chain two converters together: A → B → C\n *\n * @example\n * ```ts\n * const turnsToRadians = chain(turnsToDegrees, degreesToRadians);\n * ```\n */\nexport function chain<A, B, C>(\n  first: Converter<A, B>,\n  second: Converter<B, C>,\n): Converter<A, C> {\n  return ((value: A) => second(first(value))) as Converter<A, C>;\n}\n\n/**\n * Create an identity converter (no-op, for type coercion).\n *\n * @example\n * ```ts\n * const pixelsIdentity = identity<Pixels>();\n * ```\n */\nexport function identity<T>(): Converter<T, T> {\n  return ((value: T) => value) as Converter<T, T>;\n}\n\n/* ═══════════════════════════════════════════════════════════════\n   CONVERSION REGISTRY (Optional Pattern)\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * A registry of converters for runtime lookup.\n * Useful when converter selection depends on runtime values.\n *\n * @example\n * ```ts\n * const angleConverters = new ConverterRegistry<Degrees>();\n * angleConverters.register('radians', degreesToRadians);\n * angleConverters.register('turns', degreesToTurns);\n *\n * const converted = angleConverters.convert(90 as Degrees, 'radians');\n * ```\n */\nexport class ConverterRegistry<From> {\n  private converters = new Map<string, Converter<From, unknown>>();\n\n  register<To>(name: string, converter: Converter<From, To>): this {\n    this.converters.set(name, converter as Converter<From, unknown>);\n    return this;\n  }\n\n  convert<To>(value: From, targetName: string): To {\n    const converter = this.converters.get(targetName);\n    if (!converter) {\n      throw new Error(`No converter registered for target: ${targetName}`);\n    }\n    return converter(value) as To;\n  }\n\n  has(targetName: string): boolean {\n    return this.converters.has(targetName);\n  }\n}\n"],"names":["createConverter","transform","value","createBiConverter","toTransform","fromTransform","createLinearConverter","factor","a","b","createStringConverter","validate","chain","first","second","identity","ConverterRegistry","name","converter","targetName"],"mappings":"gFA4DO,SAASA,EAGdC,EAA2D,CAC3D,OAASC,GAAgBD,EAAUC,CAAK,EAC1C,CAoBO,SAASC,EAIdC,EACAC,EACmB,CACnB,MAAO,CACL,GAAIL,EAAsBI,CAAW,EACrC,KAAMJ,EAAsBK,CAAa,CAAA,CAE7C,CAkBO,SAASC,EAGdC,EAAmC,CACnC,OAAOJ,KACAK,EAAID,KACJE,EAAIF,CAAA,CAEb,CAoBO,SAASG,EAGdC,EAAuD,CACvD,OAAST,IACHS,KAAmBT,CAAK,EACrBA,GAEX,CAcO,SAASU,EACdC,EACAC,EACiB,CACjB,OAASZ,GAAaY,EAAOD,EAAMX,CAAK,CAAC,EAC3C,CAUO,SAASa,GAA+B,CAC7C,OAASb,GAAaA,EACxB,CAmBO,MAAMc,CAAwB,CAA9B,aAAA,CACL,KAAQ,eAAiB,GAAsC,CAE/D,SAAaC,EAAcC,EAAsC,CAC/D,YAAK,WAAW,IAAID,EAAMC,CAAqC,EACxD,IACT,CAEA,QAAYhB,EAAaiB,EAAwB,CAC/C,MAAMD,EAAY,KAAK,WAAW,IAAIC,CAAU,EAChD,GAAI,CAACD,EACH,MAAM,IAAI,MAAM,uCAAuCC,CAAU,EAAE,EAErE,OAAOD,EAAUhB,CAAK,CACxB,CAEA,IAAIiB,EAA6B,CAC/B,OAAO,KAAK,WAAW,IAAIA,CAAU,CACvC,CACF"}

package/dist/convert.d.ts

@@ -0,0 +1,136 @@
+import { SmartNumber, SmartString } from './SmartPrimitive';
+/**
+ * A type-safe conversion function from one branded type to another.
+ *
+ * @example
+ * ```ts
+ * const degreesToRadians: Converter<Degrees, Radians> = (deg) => (deg * Math.PI / 180) as Radians;
+ * ```
+ */
+export type Converter<From, To> = (value: From) => To;
+/**
+ * A bidirectional converter with forward and reverse operations.
+ *
+ * @example
+ * ```ts
+ * const degreesRadians: BiConverter<Degrees, Radians> = {
+ *   to: (deg) => (deg * Math.PI / 180) as Radians,
+ *   from: (rad) => (rad * 180 / Math.PI) as Degrees,
+ * };
+ * ```
+ */
+export interface BiConverter<A, B> {
+    /** Convert from A to B */
+    to: Converter<A, B>;
+    /** Convert from B to A */
+    from: Converter<B, A>;
+}
+/**
+ * Create a type-safe converter between two branded number types.
+ *
+ * @param transform - The mathematical transformation function
+ * @returns A typed converter function
+ *
+ * @example
+ * ```ts
+ * type Celsius = SmartNumber<'Celsius'>;
+ * type Fahrenheit = SmartNumber<'Fahrenheit'>;
+ *
+ * const celsiusToFahrenheit = createConverter<Celsius, Fahrenheit>(c => c * 9/5 + 32);
+ * const temp: Fahrenheit = celsiusToFahrenheit(100 as Celsius); // 212
+ * ```
+ */
+export declare function createConverter<From extends SmartNumber<string>, To extends SmartNumber<string>>(transform: (value: number) => number): Converter<From, To>;
+/**
+ * Create a bidirectional converter between two branded number types.
+ *
+ * @param toTransform - Transform from A to B
+ * @param fromTransform - Transform from B to A
+ * @returns A BiConverter with both directions
+ *
+ * @example
+ * ```ts
+ * const celsiusFahrenheit = createBiConverter<Celsius, Fahrenheit>(
+ *   c => c * 9/5 + 32,
+ *   f => (f - 32) * 5/9
+ * );
+ *
+ * celsiusFahrenheit.to(0 as Celsius);     // 32 as Fahrenheit
+ * celsiusFahrenheit.from(32 as Fahrenheit); // 0 as Celsius
+ * ```
+ */
+export declare function createBiConverter<A extends SmartNumber<string>, B extends SmartNumber<string>>(toTransform: (value: number) => number, fromTransform: (value: number) => number): BiConverter<A, B>;
+/**
+ * Create a linear converter (multiply by factor).
+ * Useful for unit conversions with simple ratios.
+ *
+ * @param factor - The multiplication factor (A * factor = B)
+ * @returns A BiConverter using the linear relationship
+ *
+ * @example
+ * ```ts
+ * // 1 meter = 100 centimeters
+ * const metersCentimeters = createLinearConverter<Meters, Centimeters>(100);
+ *
+ * metersCentimeters.to(2 as Meters);       // 200 as Centimeters
+ * metersCentimeters.from(50 as Centimeters); // 0.5 as Meters
+ * ```
+ */
+export declare function createLinearConverter<A extends SmartNumber<string>, B extends SmartNumber<string>>(factor: number): BiConverter<A, B>;
+/**
+ * Create a converter for string types with validation.
+ *
+ * @param validate - Optional validation function (throws on invalid input)
+ * @returns A converter that casts strings to the target type
+ *
+ * @example
+ * ```ts
+ * type URL = SmartString<'URL'>;
+ *
+ * const toURL = createStringConverter<string, URL>((s) => {
+ *   if (!s.startsWith('http')) throw new Error('Invalid URL');
+ * });
+ *
+ * const url: URL = toURL('https://example.com'); // ✅
+ * const bad: URL = toURL('not-a-url');           // ❌ throws
+ * ```
+ */
+export declare function createStringConverter<From extends string, To extends SmartString<string>>(validate?: (value: From) => void): Converter<From, To>;
+/**
+ * Chain two converters together: A → B → C
+ *
+ * @example
+ * ```ts
+ * const turnsToRadians = chain(turnsToDegrees, degreesToRadians);
+ * ```
+ */
+export declare function chain<A, B, C>(first: Converter<A, B>, second: Converter<B, C>): Converter<A, C>;
+/**
+ * Create an identity converter (no-op, for type coercion).
+ *
+ * @example
+ * ```ts
+ * const pixelsIdentity = identity<Pixels>();
+ * ```
+ */
+export declare function identity<T>(): Converter<T, T>;
+/**
+ * A registry of converters for runtime lookup.
+ * Useful when converter selection depends on runtime values.
+ *
+ * @example
+ * ```ts
+ * const angleConverters = new ConverterRegistry<Degrees>();
+ * angleConverters.register('radians', degreesToRadians);
+ * angleConverters.register('turns', degreesToTurns);
+ *
+ * const converted = angleConverters.convert(90 as Degrees, 'radians');
+ * ```
+ */
+export declare class ConverterRegistry<From> {
+    private converters;
+    register<To>(name: string, converter: Converter<From, To>): this;
+    convert<To>(value: From, targetName: string): To;
+    has(targetName: string): boolean;
+}
+//# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMjE;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,EAAE,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,EAAE,CAAC;IAC/B,0BAA0B;IAC1B,EAAE,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpB,0BAA0B;IAC1B,IAAI,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACvB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,IAAI,SAAS,WAAW,CAAC,MAAM,CAAC,EAChC,EAAE,SAAS,WAAW,CAAC,MAAM,CAAC,EAC9B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,EAC7B,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,EAE7B,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACtC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GACvC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAKnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,EAC7B,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,EAC7B,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAKnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,SAAS,MAAM,EACnB,EAAE,SAAS,WAAW,CAAC,MAAM,CAAC,EAC9B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAKvD;AAMD;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC3B,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EACtB,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GACtB,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAEjB;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAE7C;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB,CAAC,IAAI;IACjC,OAAO,CAAC,UAAU,CAA+C;IAEjE,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI;IAKhE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,EAAE;IAQhD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;CAGjC"}

package/dist/convert.es.js

@@ -0,0 +1,51 @@
+function o(e) {
+  return ((r) => e(r));
+}
+function c(e, r) {
+  return {
+    to: o(e),
+    from: o(r)
+  };
+}
+function i(e) {
+  return c(
+    (r) => r * e,
+    (r) => r / e
+  );
+}
+function s(e) {
+  return ((r) => (e && e(r), r));
+}
+function u(e, r) {
+  return ((t) => r(e(t)));
+}
+function v() {
+  return ((e) => e);
+}
+class f {
+  constructor() {
+    this.converters = /* @__PURE__ */ new Map();
+  }
+  register(r, t) {
+    return this.converters.set(r, t), this;
+  }
+  convert(r, t) {
+    const n = this.converters.get(t);
+    if (!n)
+      throw new Error(`No converter registered for target: ${t}`);
+    return n(r);
+  }
+  has(r) {
+    return this.converters.has(r);
+  }
+}
+export {
+  f as ConverterRegistry,
+  u as chain,
+  c as createBiConverter,
+  o as createConverter,
+  i as createLinearConverter,
+  s as createStringConverter,
+  v as identity
+};
+//# sourceMappingURL=convert.es.js.map

package/dist/convert.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.es.js","sources":["../src/convert.ts"],"sourcesContent":["/**\n * 🔄 Conversion Utilities for Smart Primitives\n *\n * Type-safe conversion functions between branded types with a clean factory pattern.\n * Supports both one-way and bidirectional conversions.\n */\n\nimport type { SmartNumber, SmartString } from './SmartPrimitive';\n\n/* ═══════════════════════════════════════════════════════════════\n   CORE CONVERSION TYPES\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * A type-safe conversion function from one branded type to another.\n *\n * @example\n * ```ts\n * const degreesToRadians: Converter<Degrees, Radians> = (deg) => (deg * Math.PI / 180) as Radians;\n * ```\n */\nexport type Converter<From, To> = (value: From) => To;\n\n/**\n * A bidirectional converter with forward and reverse operations.\n *\n * @example\n * ```ts\n * const degreesRadians: BiConverter<Degrees, Radians> = {\n *   to: (deg) => (deg * Math.PI / 180) as Radians,\n *   from: (rad) => (rad * 180 / Math.PI) as Degrees,\n * };\n * ```\n */\nexport interface BiConverter<A, B> {\n  /** Convert from A to B */\n  to: Converter<A, B>;\n  /** Convert from B to A */\n  from: Converter<B, A>;\n}\n\n/* ═══════════════════════════════════════════════════════════════\n   CONVERSION FACTORY\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Create a type-safe converter between two branded number types.\n *\n * @param transform - The mathematical transformation function\n * @returns A typed converter function\n *\n * @example\n * ```ts\n * type Celsius = SmartNumber<'Celsius'>;\n * type Fahrenheit = SmartNumber<'Fahrenheit'>;\n *\n * const celsiusToFahrenheit = createConverter<Celsius, Fahrenheit>(c => c * 9/5 + 32);\n * const temp: Fahrenheit = celsiusToFahrenheit(100 as Celsius); // 212\n * ```\n */\nexport function createConverter<\n  From extends SmartNumber<string>,\n  To extends SmartNumber<string>,\n>(transform: (value: number) => number): Converter<From, To> {\n  return ((value: From) => transform(value) as To) as Converter<From, To>;\n}\n\n/**\n * Create a bidirectional converter between two branded number types.\n *\n * @param toTransform - Transform from A to B\n * @param fromTransform - Transform from B to A\n * @returns A BiConverter with both directions\n *\n * @example\n * ```ts\n * const celsiusFahrenheit = createBiConverter<Celsius, Fahrenheit>(\n *   c => c * 9/5 + 32,\n *   f => (f - 32) * 5/9\n * );\n *\n * celsiusFahrenheit.to(0 as Celsius);     // 32 as Fahrenheit\n * celsiusFahrenheit.from(32 as Fahrenheit); // 0 as Celsius\n * ```\n */\nexport function createBiConverter<\n  A extends SmartNumber<string>,\n  B extends SmartNumber<string>,\n>(\n  toTransform: (value: number) => number,\n  fromTransform: (value: number) => number,\n): BiConverter<A, B> {\n  return {\n    to: createConverter<A, B>(toTransform),\n    from: createConverter<B, A>(fromTransform),\n  };\n}\n\n/**\n * Create a linear converter (multiply by factor).\n * Useful for unit conversions with simple ratios.\n *\n * @param factor - The multiplication factor (A * factor = B)\n * @returns A BiConverter using the linear relationship\n *\n * @example\n * ```ts\n * // 1 meter = 100 centimeters\n * const metersCentimeters = createLinearConverter<Meters, Centimeters>(100);\n *\n * metersCentimeters.to(2 as Meters);       // 200 as Centimeters\n * metersCentimeters.from(50 as Centimeters); // 0.5 as Meters\n * ```\n */\nexport function createLinearConverter<\n  A extends SmartNumber<string>,\n  B extends SmartNumber<string>,\n>(factor: number): BiConverter<A, B> {\n  return createBiConverter<A, B>(\n    a => a * factor,\n    b => b / factor,\n  );\n}\n\n/**\n * Create a converter for string types with validation.\n *\n * @param validate - Optional validation function (throws on invalid input)\n * @returns A converter that casts strings to the target type\n *\n * @example\n * ```ts\n * type URL = SmartString<'URL'>;\n *\n * const toURL = createStringConverter<string, URL>((s) => {\n *   if (!s.startsWith('http')) throw new Error('Invalid URL');\n * });\n *\n * const url: URL = toURL('https://example.com'); // ✅\n * const bad: URL = toURL('not-a-url');           // ❌ throws\n * ```\n */\nexport function createStringConverter<\n  From extends string,\n  To extends SmartString<string>,\n>(validate?: (value: From) => void): Converter<From, To> {\n  return ((value: From) => {\n    if (validate) validate(value);\n    return value as unknown as To;\n  }) as Converter<From, To>;\n}\n\n/* ═══════════════════════════════════════════════════════════════\n   CHAINING & COMPOSITION\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Chain two converters together: A → B → C\n *\n * @example\n * ```ts\n * const turnsToRadians = chain(turnsToDegrees, degreesToRadians);\n * ```\n */\nexport function chain<A, B, C>(\n  first: Converter<A, B>,\n  second: Converter<B, C>,\n): Converter<A, C> {\n  return ((value: A) => second(first(value))) as Converter<A, C>;\n}\n\n/**\n * Create an identity converter (no-op, for type coercion).\n *\n * @example\n * ```ts\n * const pixelsIdentity = identity<Pixels>();\n * ```\n */\nexport function identity<T>(): Converter<T, T> {\n  return ((value: T) => value) as Converter<T, T>;\n}\n\n/* ═══════════════════════════════════════════════════════════════\n   CONVERSION REGISTRY (Optional Pattern)\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * A registry of converters for runtime lookup.\n * Useful when converter selection depends on runtime values.\n *\n * @example\n * ```ts\n * const angleConverters = new ConverterRegistry<Degrees>();\n * angleConverters.register('radians', degreesToRadians);\n * angleConverters.register('turns', degreesToTurns);\n *\n * const converted = angleConverters.convert(90 as Degrees, 'radians');\n * ```\n */\nexport class ConverterRegistry<From> {\n  private converters = new Map<string, Converter<From, unknown>>();\n\n  register<To>(name: string, converter: Converter<From, To>): this {\n    this.converters.set(name, converter as Converter<From, unknown>);\n    return this;\n  }\n\n  convert<To>(value: From, targetName: string): To {\n    const converter = this.converters.get(targetName);\n    if (!converter) {\n      throw new Error(`No converter registered for target: ${targetName}`);\n    }\n    return converter(value) as To;\n  }\n\n  has(targetName: string): boolean {\n    return this.converters.has(targetName);\n  }\n}\n"],"names":["createConverter","transform","value","createBiConverter","toTransform","fromTransform","createLinearConverter","factor","a","b","createStringConverter","validate","chain","first","second","identity","ConverterRegistry","name","converter","targetName"],"mappings":"AA4DO,SAASA,EAGdC,GAA2D;AAC3D,UAAQ,CAACC,MAAgBD,EAAUC,CAAK;AAC1C;AAoBO,SAASC,EAIdC,GACAC,GACmB;AACnB,SAAO;AAAA,IACL,IAAIL,EAAsBI,CAAW;AAAA,IACrC,MAAMJ,EAAsBK,CAAa;AAAA,EAAA;AAE7C;AAkBO,SAASC,EAGdC,GAAmC;AACnC,SAAOJ;AAAA,IACL,OAAKK,IAAID;AAAA,IACT,OAAKE,IAAIF;AAAA,EAAA;AAEb;AAoBO,SAASG,EAGdC,GAAuD;AACvD,UAAQ,CAACT,OACHS,OAAmBT,CAAK,GACrBA;AAEX;AAcO,SAASU,EACdC,GACAC,GACiB;AACjB,UAAQ,CAACZ,MAAaY,EAAOD,EAAMX,CAAK,CAAC;AAC3C;AAUO,SAASa,IAA+B;AAC7C,UAAQ,CAACb,MAAaA;AACxB;AAmBO,MAAMc,EAAwB;AAAA,EAA9B,cAAA;AACL,SAAQ,iCAAiB,IAAA;AAAA,EAAsC;AAAA,EAE/D,SAAaC,GAAcC,GAAsC;AAC/D,gBAAK,WAAW,IAAID,GAAMC,CAAqC,GACxD;AAAA,EACT;AAAA,EAEA,QAAYhB,GAAaiB,GAAwB;AAC/C,UAAMD,IAAY,KAAK,WAAW,IAAIC,CAAU;AAChD,QAAI,CAACD;AACH,YAAM,IAAI,MAAM,uCAAuCC,CAAU,EAAE;AAErE,WAAOD,EAAUhB,CAAK;AAAA,EACxB;AAAA,EAEA,IAAIiB,GAA6B;AAC/B,WAAO,KAAK,WAAW,IAAIA,CAAU;AAAA,EACvC;AACF;"}

package/dist/convert.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=convert.test-d.d.ts.map

package/dist/convert.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.test-d.d.ts","sourceRoot":"","sources":["../src/convert.test-d.ts"],"names":[],"mappings":""}

package/dist/index.cjs.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=!1;exports.USE_PLAIN_PRIMITIVES=e;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./convert.cjs.js"),e=require("./units/index.cjs.js");function t(i,o,r){return Math.min(Math.max(i,o),r)}function l(i,o,r){const n=r-o;return((i-o)%n+n)%n+o}exports.ConverterRegistry=s.ConverterRegistry;exports.chain=s.chain;exports.createBiConverter=s.createBiConverter;exports.createConverter=s.createConverter;exports.createLinearConverter=s.createLinearConverter;exports.createStringConverter=s.createStringConverter;exports.identity=s.identity;exports.applyVelocity=e.applyVelocity;exports.celsiusToFahrenheit=e.celsiusToFahrenheit;exports.centimetersToInches=e.centimetersToInches;exports.centimetersToMeters=e.centimetersToMeters;exports.centimetersToMillimeters=e.centimetersToMillimeters;exports.clampAlpha=e.clampAlpha;exports.clampNormalized=e.clampNormalized;exports.clampPercentage=e.clampPercentage;exports.clampSignedNormalized=e.clampSignedNormalized;exports.degreesToRadians=e.degreesToRadians;exports.degreesToTurns=e.degreesToTurns;exports.emsToPixels=e.emsToPixels;exports.fahrenheitToCelsius=e.fahrenheitToCelsius;exports.hoursToMinutes=e.hoursToMinutes;exports.inchesToCentimeters=e.inchesToCentimeters;exports.inchesToPixels=e.inchesToPixels;exports.inchesToPoints=e.inchesToPoints;exports.metersToCentimeters=e.metersToCentimeters;exports.millimetersToCentimeters=e.millimetersToCentimeters;exports.millisecondsToSeconds=e.millisecondsToSeconds;exports.minutesToHours=e.minutesToHours;exports.minutesToSeconds=e.minutesToSeconds;exports.normalizeDegrees=e.normalizeDegrees;exports.normalizeRadians=e.normalizeRadians;exports.normalizeTurns=e.normalizeTurns;exports.normalizedProgressToPercent=e.normalizedProgressToPercent;exports.normalizedToPercentage=e.normalizedToPercentage;exports.percentToNormalizedProgress=e.percentToNormalizedProgress;exports.percentageToNormalized=e.percentageToNormalized;exports.pixelsToEms=e.pixelsToEms;exports.pixelsToInches=e.pixelsToInches;exports.pixelsToRems=e.pixelsToRems;exports.pixelsToVh=e.pixelsToVh;exports.pixelsToVw=e.pixelsToVw;exports.pointsToInches=e.pointsToInches;exports.radiansToDegrees=e.radiansToDegrees;exports.radiansToTurns=e.radiansToTurns;exports.remsToPixels=e.remsToPixels;exports.secondsToMilliseconds=e.secondsToMilliseconds;exports.secondsToMinutes=e.secondsToMinutes;exports.turnsToDegrees=e.turnsToDegrees;exports.turnsToRadians=e.turnsToRadians;exports.velocityFromValues=e.velocityFromValues;exports.velocityMillisecondsToSeconds=e.velocityMillisecondsToSeconds;exports.velocitySecondsToMilliseconds=e.velocitySecondsToMilliseconds;exports.vhToPixels=e.vhToPixels;exports.vwToPixels=e.vwToPixels;exports.clamp=t;exports.wrap=l;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":["../src/SmartPrimitive.ts"],"sourcesContent":["/**\n * 🔧 FEATURE FLAG: Toggle smart primitive type checking\n * When false (default): SmartPrimitive types provide type safety\n * When true: All SmartNumber, SmartString, etc. become plain primitives\n *\n * Use cases:\n * - Performance testing (eliminate type overhead)\n * - Debugging type issues\n * - Gradual migration to/from smart primitives\n * - Bundle size optimization\n *\n * How to use:\n * 1. Change `false` to `true` below\n * 2. Your entire codebase now treats Pixels, URLs, etc. as plain primitives\n * 3. Cross-brand assignments that were errors become allowed\n * 4. All type extraction utilities become no-ops\n * 5. Change back to `false` to re-enable smart primitive type safety\n */\n\n// 🔧 FEATURE FLAG: Both runtime constant AND compile-time type\nexport const USE_PLAIN_PRIMITIVES = false as const; // 👈 Change to `true` for plain primitives, `false` for branded types\nexport type USE_PLAIN_PRIMITIVES_TYPE = typeof USE_PLAIN_PRIMITIVES;\n\n/**\n * Clean type extraction using the brand pattern\n * Respects the USE_PLAIN_PRIMITIVES flag.\n */\ntype BaseOf<T> = USE_PLAIN_PRIMITIVES_TYPE extends true\n  ? T // 🚫 Smart types disabled: type is already the base\n  : T extends number & { readonly __brand?: unknown }\n    ? number\n    : T extends string & { readonly __brand?: unknown }\n      ? string\n      : T extends boolean & { readonly __brand?: unknown }\n        ? boolean\n        : T; // 🎯 Extract base type or return as-is\n\n/**\n * Generic smart primitive type that provides **opt-in type safety** while staying flexible.\n *\n * **How it works:**\n * - ✅ **Accepts plain values**: You can use regular numbers, strings, etc. directly\n * - ✅ **Prevents cross-domain mixing**: TypeScript stops you from using pixels where milliseconds are expected\n * - ✅ **Zero runtime cost**: No performance impact - it's just TypeScript magic\n * - ✅ **Easy to disable**: Toggle `USE_PLAIN_PRIMITIVES` to turn off all smart typing\n *\n * **Example:**\n * ```ts\n * type Pixels = SmartPrimitive<number, 'Pixels'>;\n * type Milliseconds = SmartPrimitive<number, 'Milliseconds'>;\n *\n * let width: Pixels = 300;        // ✅ Plain number works\n * let delay: Milliseconds = 500;        // ✅ Plain number works\n * let oops: Pixels = delay;       // ❌ TypeScript error - caught the mistake!\n * ```\n *\n * This prevents bugs like accidentally using milliseconds where pixels are expected,\n * while keeping your code simple and readable.\n */\nexport type SmartPrimitive<\n  Base extends string | number | boolean | bigint | symbol,\n  BrandName extends string,\n> = USE_PLAIN_PRIMITIVES_TYPE extends true\n  ? Base\n  : Base & { readonly __brand?: BrandName };\n\n/**\n * A smart number type for domain-specific numeric values like pixels, milliseconds, etc.\n *\n * **Why use this?** Prevents common bugs like mixing up different kinds of numbers:\n * - Using milliseconds where pixels are expected\n * - Passing a width value to a duration parameter\n * - Confusing degrees with radians\n *\n * **How it works:**\n * - ✅ Works with plain numbers: `let width: Pixels = 300`\n * - ✅ Catches domain mix-ups: `let width: Pixels = duration` → TypeScript error\n * - ✅ Zero runtime cost: Just TypeScript checking, no JavaScript overhead\n *\n * Built on `SmartPrimitive` - respects the USE_PLAIN_PRIMITIVES flag for easy toggling.\n *\n * **Example:**\n * ```ts\n * type Pixels = SmartNumber<'Pixels'>;\n * type Milliseconds = SmartNumber<'Milliseconds'>;\n *\n * let width: Pixels = 300;        // ✅ works\n * let delay: Milliseconds = 500;        // ✅ works\n * let badAssign: Pixels = delay;  // ❌ type error - caught the mistake!\n * ```\n *\n * When USE_PLAIN_PRIMITIVES = false (default):\n * - Full smart number system with type safety between different units\n * - Plain numbers accepted seamlessly\n * - Clean tooltip display\n *\n * When USE_PLAIN_PRIMITIVES = true:\n * - All smart number types collapse to plain `number`\n * - Zero runtime overhead, maximum performance\n *\n * Usage remains the same regardless of flag state:\n * ```ts\n * let distance: Pixels = 300;           // ✅ always works\n * let branded: Pixels = 300 as Pixels;  // ✅ always works\n * ```\n */\nexport type SmartNumber<BrandName extends string> = SmartPrimitive<\n  number,\n  BrandName\n>;\n\n/**\n * A smart string type that accepts plain strings but maintains type identity.\n * Perfect for things like URLs, CSS selectors, or other domain-specific strings.\n *\n * Usage:\n * ```ts\n * type URL = SmartString<'URL'>;\n * type CSSSelector = SmartString<'CSSSelector'>;\n *\n * let url: URL = \"https://example.com\";        // ✅ works\n * let selector: CSSSelector = \".my-class\";     // ✅ works\n * let badAssign: URL = selector;               // ❌ type error\n * ```\n */\nexport type SmartString<BrandName extends string> = SmartPrimitive<\n  string,\n  BrandName\n>;\n\n/**\n * A smart boolean type that accepts plain booleans but maintains type identity.\n * Useful for domain-specific flags or state indicators.\n *\n * Usage:\n * ```ts\n * type IsVisible = SmartBoolean<'IsVisible'>;\n * type IsEnabled = SmartBoolean<'IsEnabled'>;\n *\n * let visible: IsVisible = true;               // ✅ works\n * let enabled: IsEnabled = false;              // ✅ works\n * let badAssign: IsVisible = enabled;          // ❌ type error\n * ```\n */\nexport type SmartBoolean<BrandName extends string> = SmartPrimitive<\n  boolean,\n  BrandName\n>;\n\n/**\n * Simplified Unbrand using the generic brand pattern.\n * Also respects the USE_PLAIN_PRIMITIVES flag.\n *\n * When USE_PLAIN_PRIMITIVES = true: This becomes a no-op (types pass through unchanged)\n * When USE_PLAIN_PRIMITIVES = false: Full unbranding to base types\n */\nexport type Unbrand<T> = USE_PLAIN_PRIMITIVES_TYPE extends true\n  ? T // 🚫 Smart types disabled: types pass through unchanged\n  : // 🎯 Smart types enabled: extract base types and recurse\n    // 1️⃣ If T has a brand, extract the base type (could be number, string, etc.)\n    T extends number & { readonly __brand?: unknown }\n    ? number\n    : T extends string & { readonly __brand?: unknown }\n      ? string\n      : T extends boolean & { readonly __brand?: unknown }\n        ? boolean\n        : // 2️⃣ If T is an object (e.g. your params bag), recurse each field\n          T extends Record<string, unknown>\n          ? { [K in keyof T]: Unbrand<T[K]> }\n          : // 3️⃣ Everything else stays the same\n            T;\n\n/**\n * Given any function type F, produce a new function type whose\n * arguments have been passed through Unbrand<…>, and whose return\n * type you can also choose to unbrand (or leave alone).\n */\nexport type UnbrandFn<F, UnbrandReturn extends boolean = false> = F extends (\n  ...args: infer A\n) => infer R\n  ? A extends readonly unknown[]\n    ? (\n        ...args: { [K in keyof A]: Unbrand<A[K]> }\n      ) => UnbrandReturn extends true ? Unbrand<R> : R\n    : never\n  : never;\n\n// Export the BaseOf utility for advanced users\nexport type { BaseOf };\n"],"names":["USE_PLAIN_PRIMITIVES"],"mappings":"gFAoBO,MAAMA,EAAuB"}
+{"version":3,"file":"index.cjs.js","sources":["../src/trait-utils.ts"],"sourcesContent":["/**\n * 🏷️ Trait System Utilities\n *\n * Core trait interfaces and wrapper types for the orthogonal trait system.\n * These are used across all unit type definitions to provide composable,\n * flag-aware type annotations.\n */\n\nimport type { UsePlainPrimitives } from './SmartPrimitive';\n\n/* ═══════════════════════════════════════════════════════════════\n   CORE TRAIT INTERFACES (Internal)\n   ═══════════════════════════════════════════════════════════════ */\n\ninterface Unit<U extends string> {\n  readonly _unit?: U;\n}\n\ninterface Range<Min extends number, Max extends number> {\n  readonly _range?: { readonly min: Min; readonly max: Max };\n}\n\ninterface Clamped {\n  readonly _clamped?: true;\n}\n\ninterface Periodic {\n  readonly _periodic?: true;\n}\n\ninterface Kind<K extends string> {\n  readonly _kind?: K;\n}\n\ninterface Integer {\n  readonly _integer?: true;\n}\n\n/* ═══════════════════════════════════════════════════════════════\n   EXPORTED TRAIT WRAPPERS (Flag-Aware)\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Marks a number with measurement units.\n */\nexport type WithUnit<U extends string> = number &\n  (UsePlainPrimitives extends true ? {} : Unit<U>);\n\n/**\n * Marks a number as having a reference range [Min, Max].\n */\nexport type WithRange<Min extends number, Max extends number> = number &\n  (UsePlainPrimitives extends true ? {} : Range<Min, Max>);\n\n/**\n * Marks a number as being clamped (constrained) to its range.\n */\nexport type WithClamped = number &\n  (UsePlainPrimitives extends true ? {} : Clamped);\n\n/**\n * Marks a number as periodic (wrapping around at boundaries).\n */\nexport type WithPeriodic = number &\n  (UsePlainPrimitives extends true ? {} : Periodic);\n\n/**\n * Groups related unit types under a common archetype/kind.\n */\nexport type WithKind<K extends string> = number &\n  (UsePlainPrimitives extends true ? {} : Kind<K>);\n\n/**\n * Marks a number as an integer (whole number).\n */\nexport type WithInteger = number &\n  (UsePlainPrimitives extends true ? {} : Integer);\n\n/* ═══════════════════════════════════════════════════════════════\n   TYPE EXTRACTION UTILITIES\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Extract units from a type.\n * @returns The unit string, or never if type has no Units trait.\n */\nexport type UnitOf<T> = T extends Unit<infer U> ? U : never;\n\n/**\n * Extract range from a type as a tuple [Min, Max].\n * @returns [Min, Max] tuple, or never if type has no Range trait.\n */\nexport type RangeOf<T> =\n  T extends Range<infer Min, infer Max> ? readonly [Min, Max] : never;\n\n/**\n * Extract min value from range trait.\n * @returns Min value, or never if type has no Range trait.\n */\nexport type MinOf<T> = T extends Range<infer Min, infer _Max> ? Min : never;\n\n/**\n * Extract max value from range trait.\n * @returns Max value, or never if type has no Range trait.\n */\nexport type MaxOf<T> = T extends Range<infer _Min, infer Max> ? Max : never;\n\n/**\n * Check if a type has the Clamped trait.\n * @returns true if clamped, false if not.\n */\nexport type IsClamped<T> = T extends Clamped ? true : false;\n\n/**\n * Check if a type has the Periodic trait.\n * @returns true if periodic, false if not.\n */\nexport type IsPeriodic<T> = T extends Periodic ? true : false;\n\n/**\n * Extract kind/archetype from a type.\n * @returns The kind string, or never if type has no Kind trait.\n */\nexport type KindOf<T> = T extends Kind<infer K> ? K : never;\n\n/* ═══════════════════════════════════════════════════════════════\n   TRAIT MODIFICATION UTILITIES\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Remove the Clamped trait from a type (return to unclamped).\n */\nexport type WithoutClamped<T> = T extends Clamped ? Omit<T, '_clamped'> : T;\n\n/**\n * Remove the Periodic trait from a type.\n */\nexport type WithoutPeriodic<T> = T extends Periodic ? Omit<T, '_periodic'> : T;\n\n/**\n * Change the units of a type (unit conversion).\n */\nexport type ChangeUnits<T, U extends string> = Omit<T, '_unit'> & WithUnit<U>;\n\n/**\n * Change the range of a type.\n */\nexport type ChangeRange<T, Min extends number, Max extends number> = Omit<\n  T,\n  '_range'\n> &\n  WithRange<Min, Max>;\n\n/* ═══════════════════════════════════════════════════════════════\n   RUNTIME UTILITIES\n   ═══════════════════════════════════════════════════════════════ */\n\n/**\n * Clamp a value to specified bounds, preserve orthogonal traits, and mark as clamped.\n */\nexport function clamp<T extends number, Min extends number, Max extends number>(\n  value: T,\n  min: Min,\n  max: Max,\n): WithRange<Min, Max> & WithClamped {\n  return Math.min(Math.max(value, min), max);\n}\n\n/**\n * Wrap a value to specified bounds, preserve orthogonal traits, and mark as periodic.\n */\nexport function wrap<T, Min extends number, Max extends number>(\n  value: T,\n  min: Min,\n  max: Max,\n): Omit<T, '_range' | '_periodic'> & WithRange<Min, Max> & WithPeriodic {\n  const range = max - min;\n  const normalized = ((((value as any) - min) % range) + range) % range;\n  return (normalized + min) as any;\n}\n"],"names":["clamp","value","min","max","wrap","range"],"mappings":"sJAgKO,SAASA,EACdC,EACAC,EACAC,EACmC,CACnC,OAAO,KAAK,IAAI,KAAK,IAAIF,EAAOC,CAAG,EAAGC,CAAG,CAC3C,CAKO,SAASC,EACdH,EACAC,EACAC,EACsE,CACtE,MAAME,EAAQF,EAAMD,EAEpB,QADuBD,EAAgBC,GAAOG,EAASA,GAASA,EAC3CH,CACvB"}

package/dist/index.d.ts

@@ -17,6 +17,11 @@
  * let oops: Pixels = delay;       // ❌ type error - caught!
  * ```
  */
-export type { SmartPrimitive, SmartNumber, SmartString, SmartBoolean, Unbrand, UnbrandFn, USE_PLAIN_PRIMITIVES_TYPE, BaseOf, } from './SmartPrimitive';
-export { USE_PLAIN_PRIMITIVES } from './SmartPrimitive';
+export type { SmartPrimitive, SmartPrimitiveConfig, SmartNumber, SmartString, SmartBoolean, SmartBigInt, SmartSymbol, Unbrand, UnbrandFn, UsePlainPrimitives, } from './SmartPrimitive';
+export type { Converter, BiConverter } from './convert';
+export { createConverter, createBiConverter, createLinearConverter, createStringConverter, chain, identity, ConverterRegistry, } from './convert';
+export * from './units';
+export type { WithUnit, WithRange, WithClamped, WithPeriodic, WithKind, WithInteger, UnitOf, RangeOf, MinOf, MaxOf, IsClamped, IsPeriodic, KindOf, WithoutClamped, WithoutPeriodic, ChangeUnits, ChangeRange, } from './trait-utils';
+export { clamp, wrap } from './trait-utils';
+export type { CSSEasing } from './strings/css';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,YAAY,EACV,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,OAAO,EACP,SAAS,EACT,yBAAyB,EACzB,MAAM,GACP,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EACX,WAAW,EACX,OAAO,EACP,SAAS,EACT,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,EACL,QAAQ,EACR,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAInB,cAAc,SAAS,CAAC;AAGxB,YAAY,EACV,QAAQ,EACR,SAAS,EACT,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,MAAM,EACN,OAAO,EACP,KAAK,EACL,KAAK,EACL,SAAS,EACT,UAAU,EACV,MAAM,EACN,cAAc,EACd,eAAe,EACf,WAAW,EACX,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAG5C,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}