@penner/smart-primitive 0.0.1 → 0.1.0

package/README.md

@@ -1,267 +1,302 @@
 # @penner/smart-primitive
 
-Type-safe branded primitives with zero runtime overhead. Prevent bugs by distinguishing different kinds of numbers, strings, and booleans at compile time.
+Type-safe primitives for TypeScript. Catch unit mix-ups at compile time with zero runtime cost.
 
-## Why Smart Primitives?
+## Installation
 
-Ever accidentally used milliseconds where pixels were expected? Or passed a URL to a function expecting a CSS selector? **Smart primitives** catch these mistakes at compile time, with zero runtime cost.
+```bash
+npm install @penner/smart-primitive
+```
 
-```typescript
-import { SmartNumber, SmartString } from '@penner/smart-primitive';
+## Quick Start
 
-type Pixels = SmartNumber<'Pixels'>;
-type Milliseconds = SmartNumber<'Milliseconds'>;
-type URL = SmartString<'URL'>;
-type CSSSelector = SmartString<'CSSSelector'>;
+Import ready-to-use types, annotate your variables and parameters, and let TypeScript catch mistakes:
 
-// ✅ Works perfectly
-let width: Pixels = 300;
-let delay: Milliseconds = 500;
-let link: URL = 'https://example.com';
-let selector: CSSSelector = '.button';
+```typescript
+import { Pixels, Milliseconds, Degrees } from '@penner/smart-primitive';
 
-// ❌ TypeScript catches the mistake!
-let oops: Pixels = delay; // Error: Type 'Milliseconds' is not assignable to type 'Pixels'
-let wrong: URL = selector; // Error: Type 'CSSSelector' is not assignable to type 'URL'
-```
+function animate(
+  element: HTMLElement,
+  distance: Pixels,
+  duration: Milliseconds,
+  rotation: Degrees,
+) {
+  // ...
+}
 
-## Features
+const dist: Pixels = 100;
+const time: Milliseconds = 500;
+const angle: Degrees = 90;
 
-- ✅ **Zero runtime overhead** - Pure TypeScript, no JavaScript generated
-- ✅ **Works with plain values** - No wrapping or conversion needed
-- ✅ **Prevents cross-domain mixing** - TypeScript stops you from mixing incompatible types
-- ✅ **Toggleable type safety** - Turn off all smart typing with one flag
-- ✅ **Utility functions** - `Unbrand`, `BaseOf`, `UnbrandFn` for working with branded types
-- ✅ **Clean tooltips** - TypeScript shows clean type names, not implementation details
+animate(el, dist, time, angle); // ✅ correct
+animate(el, time, dist, angle); // ❌ Error! Can't use Milliseconds where Pixels expected
+```
 
-## Installation
+Plain values are always assignable — no casting or wrapping required:
 
-```bash
-npm install @penner/smart-primitive
+```typescript
+const width: Pixels = 300; // ✅ plain number works
+const delay: Milliseconds = 1000; // ✅ plain number works
+const opacity: Alpha = 0.8; // ✅ plain number works
 ```
 
-## Quick Start
+### Available Unit Types
 
-### Smart Numbers
+| Category    | Types                                                                                                                |
+| ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| Time        | `Seconds`, `Milliseconds`, `Minutes`, `Hours`                                                                        |
+| Length      | `Pixels`, `Ems`, `Rems`, `Vw`, `Vh`, `Percent`, `Points`, `Inches`, `Centimeters`, `Millimeters`, `Meters`           |
+| Angle       | `Degrees`, `Radians`, `Turns`                                                                                        |
+| Normalized  | `Normalized` (0–1), `SignedNormalized` (−1–1), `ClampedNormalized`, `Percentage` (0–100), `Alpha`, `Ratio`, `Factor` |
+| Temperature | `Celsius`, `Fahrenheit`                                                                                              |
+| Color       | `ColorByte` (0–255), `RGBTuple`, `RGBATuple`                                                                         |
+| Integer     | `Index`                                                                                                              |
+| Animation   | `NormalizedTime` (clamped 0–1), `NormalizedProgress` (can overshoot), `PercentProgress`                              |
 
-Perfect for units, measurements, or any numeric domain:
+All types are importable from the package root or from `@penner/smart-primitive/units`.
 
-```typescript
-import { SmartNumber } from '@penner/smart-primitive';
+## The Trait System
 
-type Pixels = SmartNumber<'Pixels'>;
-type Milliseconds = SmartNumber<'Milliseconds'>;
-type Degrees = SmartNumber<'Degrees'>;
+These types are built from a small set of composable **traits** — phantom interfaces combined via TypeScript intersection (`&`).
 
-function animate(distance: Pixels, duration: Milliseconds, rotation: Degrees) {
-  console.log(`Move ${distance}px over ${duration}ms, rotate ${rotation}°`);
-}
+### How Types Are Composed
 
-animate(100, 500, 90); // ✅ works
-animate(100, 500, 500); // ✅ works (but is it degrees or milliseconds? TypeScript doesn't know yet)
+A simple type like `Pixels` needs just a unit and kind:
 
-// But if you assign first:
-let delay: Milliseconds = 500;
-animate(100, delay, delay); // ❌ Error! Can't use Milliseconds where Degrees expected
+```typescript
+// Pixels = number with unit 'px' and kind 'length'
+type Pixels = WithUnit<'px'> & WithKind<'length'>;
 ```
 
-### Smart Strings
-
-Distinguish between different kinds of strings:
+A richer type layers on more traits:
 
 ```typescript
-import { SmartString } from '@penner/smart-primitive';
+// Degrees = number with unit 'deg', range [0, 360), periodic wrapping, kind 'angle'
+type Degrees = WithUnit<'deg'> &
+  WithRange<0, 360> &
+  WithPeriodic &
+  WithKind<'angle'>;
+```
 
-type URL = SmartString<'URL'>;
-type EmailAddress = SmartString<'EmailAddress'>;
-type CSSSelector = SmartString<'CSSSelector'>;
+Some types only need a range:
 
-function fetchData(endpoint: URL) {
-  // implementation
-}
+```typescript
+// Normalized = number in the range [0, 1], unclamped (can overshoot)
+type Normalized = WithRange<0, 1>;
 
-function sendEmail(address: EmailAddress) {
-  // implementation
-}
+// ClampedNormalized = Normalized that's guaranteed within bounds
+type ClampedNormalized = Normalized & WithClamped;
+```
 
-let api: URL = 'https://api.example.com';
-let email: EmailAddress = 'user@example.com';
+### Core Traits
 
-fetchData(api); // ✅ works
-fetchData(email); // ❌ Error! EmailAddress is not a URL
-```
+| Trait                 | Purpose                                                                      |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `WithUnit<U>`         | Labels the measurement unit (`'px'`, `'ms'`, `'deg'`, …)                     |
+| `WithRange<Min, Max>` | Documents the reference range (informational)                                |
+| `WithClamped`         | Marks the value as constrained to its range                                  |
+| `WithPeriodic`        | Marks the value as wrapping at range boundaries                              |
+| `WithKind<K>`         | Groups related types under an archetype (`'length'`, `'time'`, `'angle'`, …) |
+| `WithInteger`         | Marks the value as a whole number                                            |
 
-### Smart Booleans
+### Defining Custom Types
 
-Even booleans can benefit from type safety:
+Compose traits to define your own domain types:
 
 ```typescript
-import { SmartBoolean } from '@penner/smart-primitive';
-
-type IsVisible = SmartBoolean<'IsVisible'>;
-type IsEnabled = SmartBoolean<'IsEnabled'>;
+import {
+  WithUnit,
+  WithRange,
+  WithClamped,
+  WithKind,
+} from '@penner/smart-primitive';
 
-function toggleVisibility(visible: IsVisible) {
-  // implementation
-}
+// A simple branded unit
+type Frames = WithUnit<'frames'> & WithKind<'time'>;
 
-let visible: IsVisible = true;
-let enabled: IsEnabled = true;
+// A bounded value
+type Volume = WithRange<0, 100> & WithUnit<'percent'> & WithClamped;
 
-toggleVisibility(visible); // ✅ works
-toggleVisibility(enabled); // ❌ Error! IsEnabled is not IsVisible
+// An unbounded measurement
+type Force = WithUnit<'N'> & WithKind<'force'>;
 ```
 
-## Advanced Usage
+### Trait Extraction
 
-### Utility Types
+Query type-level metadata from trait-based types:
 
-#### `Unbrand<T>`
+```typescript
+import type {
+  UnitOf,
+  RangeOf,
+  MinOf,
+  MaxOf,
+  IsClamped,
+  IsPeriodic,
+  KindOf,
+} from '@penner/smart-primitive';
+
+type U = UnitOf<Degrees>; // 'deg'
+type R = RangeOf<Degrees>; // readonly [0, 360]
+type K = KindOf<Pixels>; // 'length'
+type C = IsClamped<Alpha>; // false
+type P = IsPeriodic<Degrees>; // true
+```
+
+### Trait Modification
 
-Remove branding from types, converting them back to primitives:
+Transform types by adding, removing, or changing traits:
 
 ```typescript
-import { Unbrand } from '@penner/smart-primitive';
-
-type Config = {
-  width: Pixels;
-  duration: Milliseconds;
-  url: URL;
-};
-
-type PlainConfig = Unbrand<Config>;
-// Result: { width: number; duration: number; url: string; }
-
-const config: PlainConfig = {
-  width: 100,
-  duration: 500,
-  url: 'https://example.com',
-};
+import type {
+  WithoutClamped,
+  ChangeUnits,
+  ChangeRange,
+} from '@penner/smart-primitive';
+
+type Unclamped = WithoutClamped<ClampedNormalized>; // remove clamping
+type InInches = ChangeUnits<Pixels, 'in'>; // swap units
+type WiderRange = ChangeRange<Normalized, -1, 2>; // change range
 ```
 
-#### `BaseOf<T>`
+### Runtime Utilities
 
-Extract the base primitive type:
+The `clamp` and `wrap` functions operate on trait-based types and refine the output type accordingly:
 
 ```typescript
-import { BaseOf } from '@penner/smart-primitive';
+import { clamp, wrap } from '@penner/smart-primitive';
 
-type PixelsBase = BaseOf<Pixels>; // number
-type URLBase = BaseOf<URL>; // string
-type IsVisibleBase = BaseOf<IsVisible>; // boolean
+const v = clamp(1.5, 0, 1); // value: 1, type: WithRange<0, 1> & WithClamped
+const w = wrap(450, 0, 360); // value: 90, type: WithRange<0, 360> & WithPeriodic
 ```
 
-#### `UnbrandFn<F>`
+## Conversions
 
-Unbrand function parameters:
+Each unit module ships pre-built converter functions:
 
 ```typescript
-import { UnbrandFn } from '@penner/smart-primitive';
+import { degreesToRadians, radiansToDegrees } from '@penner/smart-primitive';
+import {
+  secondsToMilliseconds,
+  celsiusToFahrenheit,
+} from '@penner/smart-primitive';
+import {
+  normalizedToPercentage,
+  metersToCentimeters,
+} from '@penner/smart-primitive';
+
+const rad: Radians = degreesToRadians(90); // π/2
+const ms: Milliseconds = secondsToMilliseconds(2); // 2000
+const pct: Percentage = normalizedToPercentage(0.75); // 75
+```
 
-function animate(distance: Pixels, duration: Milliseconds): void {
-  // implementation
-}
+For custom conversions, use the factory functions:
 
-type PlainAnimate = UnbrandFn<typeof animate>;
-// Result: (distance: number, duration: number) => void
+```typescript
+import {
+  createConverter,
+  createBiConverter,
+  createLinearConverter,
+} from '@penner/smart-primitive';
+
+// One-way converter
+const framesToSeconds = createConverter<Frames, Seconds>(f => f / 60);
+
+// Bidirectional converter
+const pixelsRems = createBiConverter<Pixels, Rems>(
+  px => px / 16,
+  rem => rem * 16,
+);
+pixelsRems.to(32); // 2 Rems
+pixelsRems.from(1.5); // 24 Pixels
+
+// Linear ratio converter
+const metersCm = createLinearConverter<Meters, Centimeters>(100);
 ```
 
-### Feature Flag: Toggle Type Safety
+Advanced patterns like `chain` (compose converters) and `ConverterRegistry` (runtime lookup) are also available.
 
-You can disable all smart type checking with a single flag. This is useful for:
+## String Types
 
-- Performance testing
-- Debugging type issues
-- Gradual migration
-- Bundle size optimization
+The library includes semantic string types via `@penner/smart-primitive/strings`, with template literal validation where possible:
 
 ```typescript
-// In your SmartPrimitive.ts file
-export const USE_PLAIN_PRIMITIVES = true as const; // 👈 Change to true
-
-// Now ALL smart types become plain primitives
-type Pixels = SmartNumber<'Pixels'>; // becomes: number
-type URL = SmartString<'URL'>; // becomes: string
-type IsVisible = SmartBoolean<'IsVisible'>; // becomes: boolean
-
-// All cross-brand assignments are now allowed
-let width: Pixels = 100;
-let delay: Milliseconds = 200;
-width = delay; // ✅ Now allowed! (when flag is true)
+import type {
+  CSSLength,
+  CSSCustomProperty,
+  UUID,
+  EmailAddress,
+} from '@penner/smart-primitive/strings';
+
+const width: CSSLength = '16px'; // template: `${number}${CSSLengthUnit}`
+const prop: CSSCustomProperty = '--main-color'; // template: `--${string}`
+const id: UUID = '550e8400-e29b-41d4-a716-446655440000';
+const email: EmailAddress = 'user@example.com';
 ```
 
-## How It Works
+See the [strings module](./src/strings/) for the full list of CSS, web, and data format types.
 
-Smart primitives use TypeScript's brand pattern (also called phantom types or nominal typing). The implementation is remarkably simple:
+## SmartPrimitive & SmartNumber
 
-```typescript
-export type SmartPrimitive<
-  Base extends string | number | boolean | bigint | symbol,
-  BrandName extends string,
-> = Base & { readonly __brand?: BrandName };
-```
+For quick, ad-hoc branded types that don't need trait composition, `SmartNumber` and `SmartString` are still available:
 
-The `__brand` property is:
+```typescript
+import { SmartNumber, SmartString } from '@penner/smart-primitive';
 
-- **Optional** - so plain primitives are assignable
-- **Readonly** - prevents accidental modification
-- **Never actually exists at runtime** - TypeScript-only, zero overhead
+type Score = SmartNumber<'Score'>;
+type SessionToken = SmartString<'SessionToken'>;
 
-## TypeScript Compatibility
+const points: Score = 42;
+const token: SessionToken = 'abc123';
+```
 
-Requires TypeScript 4.5 or higher.
+> **Note:** All pre-built unit types (`Pixels`, `Degrees`, `Milliseconds`, etc.) are now defined using the trait system rather than `SmartNumber`. Trait-based types carry richer metadata (units, ranges, kinds) and support extraction utilities like `UnitOf` and `RangeOf`. For a discussion of the tradeoffs between the two approaches, see [SmartPrimitive vs Traits analysis](../../docs/research/smart-primitive-vs-traits.md).
 
-## Examples
+## Feature Flag: Toggle Type Safety
 
-### Complex Object Structures
+Disable all smart typing across your project via module augmentation:
 
 ```typescript
-type AnimationConfig = {
-  timing: {
-    duration: Milliseconds;
-    delay: Milliseconds;
-  };
-  position: {
-    start: Pixels;
-    end: Pixels;
-  };
-  rotation: Degrees;
-};
-
-const config: AnimationConfig = {
-  timing: { duration: 1000, delay: 200 },
-  position: { start: 0, end: 500 },
-  rotation: 180,
-};
+// In a .d.ts file in your project (e.g., smart-primitive.d.ts):
+declare module '@penner/smart-primitive' {
+  interface SmartPrimitiveConfig {
+    usePlainPrimitives: true;
+  }
+}
 ```
 
-### Function Safety
+When enabled, all smart types collapse to plain primitives (`number`, `string`, etc.) and all cross-type assignments are allowed. Useful for debugging type issues or gradual migration.
 
-```typescript
-function moveElement(
-  element: HTMLElement,
-  distance: Pixels,
-  duration: Milliseconds,
-): void {
-  // TypeScript ensures you can't accidentally swap parameters
-}
+## Utility Types
+
+### `Unbrand<T>`
+
+Strip branding from types, recursing into object structures:
 
-let dist: Pixels = 100;
-let time: Milliseconds = 500;
+```typescript
+import type { Unbrand } from '@penner/smart-primitive';
 
-moveElement(element, dist, time); // ✅ correct
-moveElement(element, time, dist); // ❌ Error! Parameters swapped
+type Config = { width: Pixels; duration: Milliseconds };
+type Plain = Unbrand<Config>;
+// { width: number; duration: number }
 ```
 
-## License
+### `UnbrandFn<F>`
 
-MIT
+Strip branding from function parameter types:
 
-## Related Packages
+```typescript
+import type { UnbrandFn } from '@penner/smart-primitive';
 
-- [`@penner/easing`](https://www.npmjs.com/package/@penner/easing) - Modern Penner easing functions
-- [`@penner/responsive-easing`](https://www.npmjs.com/package/@penner/responsive-easing) - Responsive motion design system
+declare function move(distance: Pixels, duration: Milliseconds): void;
+type PlainMove = UnbrandFn<typeof move>;
+// (distance: number, duration: number) => void
+```
+
+## TypeScript Compatibility
 
-## Contributing
+Requires TypeScript 4.5 or higher.
 
-Contributions welcome! Please read the [contributing guidelines](../../CONTRIBUTING.md) first.
+## License
+
+MIT