@penner/smart-primitive

Type-safe primitives for TypeScript. Catch unit mix-ups at compile time with zero runtime cost.

Installation

npm install @penner/smart-primitive

Quick Start

Import ready-to-use types, annotate your variables and parameters, and let TypeScript catch mistakes:

import { Pixels, Milliseconds, Degrees } from "@penner/smart-primitive";

function animate(
  element: HTMLElement,
  distance: Pixels,
  duration: Milliseconds,
  rotation: Degrees,
) {
  // ...
}

const dist: Pixels = 100;
const time: Milliseconds = 500;
const angle: Degrees = 90;

animate(el, dist, time, angle); // ✅ correct
animate(el, time, dist, angle); // ❌ Error! Can't use Milliseconds where Pixels expected

Plain values are always assignable — no casting or wrapping required:

const width: Pixels = 300; // ✅ plain number works
const delay: Milliseconds = 1000; // ✅ plain number works
const opacity: Alpha = 0.8; // ✅ plain number works

Available Unit Types

| 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 |

All types are importable from the package root or from @penner/smart-primitive/units.

The Trait System

These types are built from a small set of composable traits — phantom interfaces combined via TypeScript intersection (&).

How Types Are Composed

A simple type like Pixels needs just a unit and kind:

// Pixels = number with unit 'px' and kind 'length'
type Pixels = WithUnit<"px"> & WithKind<"length">;

A richer type layers on more traits:

// Degrees = number with unit 'deg', range [0, 360), periodic wrapping, kind 'angle'
type Degrees = WithUnit<"deg"> & WithRange<0, 360> & WithPeriodic & WithKind<"angle">;

Some types only need a range:

// Normalized = number in the range [0, 1], unclamped (can overshoot)
type Normalized = WithRange<0, 1>;

// ClampedNormalized = Normalized that's guaranteed within bounds
type ClampedNormalized = Normalized & WithClamped;

Core Traits

| 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 |

Defining Custom Types

Compose traits to define your own domain types:

import { WithUnit, WithRange, WithClamped, WithKind } from "@penner/smart-primitive";

// A simple branded unit
type Frames = WithUnit<"frames"> & WithKind<"time">;

// A bounded value
type Volume = WithRange<0, 100> & WithUnit<"percent"> & WithClamped;

// An unbounded measurement
type Force = WithUnit<"N"> & WithKind<"force">;

Trait Extraction

Query type-level metadata from trait-based types:

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

Transform types by adding, removing, or changing traits:

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

Runtime Utilities

The clamp and wrap functions operate on trait-based types and refine the output type accordingly:

import { clamp, wrap } from "@penner/smart-primitive";

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

Conversions

Each unit module ships pre-built converter functions:

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

For custom conversions, use the factory functions:

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);

Advanced patterns like chain (compose converters) and ConverterRegistry (runtime lookup) are also available.

String Types

The library includes semantic string types via @penner/smart-primitive/strings, with template literal validation where possible:

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 = "[email protected]";

See the strings module for the full list of CSS, web, and data format types.

SmartPrimitive & SmartNumber

For quick, ad-hoc branded types that don't need trait composition, SmartNumber and SmartString are still available:

import { SmartNumber, SmartString } from "@penner/smart-primitive";

type Score = SmartNumber<"Score">;
type SessionToken = SmartString<"SessionToken">;

const points: Score = 42;
const token: SessionToken = "abc123";

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.

Feature Flag: Toggle Type Safety

Disable all smart typing across your project via module augmentation:

// In a .d.ts file in your project (e.g., smart-primitive.d.ts):
declare module "@penner/smart-primitive" {
  interface SmartPrimitiveConfig {
    usePlainPrimitives: true;
  }
}

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.

Performance note: benchmarking shows this flag has no measurable effect on typecheck speed — smart-primitive intersections are cheap to resolve. See typecheck performance analysis.

Utility Types

Unbrand<T>

Strip branding from types, recursing into object structures:

import type { Unbrand } from "@penner/smart-primitive";

type Config = { width: Pixels; duration: Milliseconds };
type Plain = Unbrand<Config>;
// { width: number; duration: number }

UnbrandFn<F>

Strip branding from function parameter types:

import type { UnbrandFn } from "@penner/smart-primitive";

declare function move(distance: Pixels, duration: Milliseconds): void;
type PlainMove = UnbrandFn<typeof move>;
// (distance: number, duration: number) => void

TypeScript Compatibility

Requires TypeScript 4.5 or higher.

AI Agent Skill

This package ships a SKILL.md file with guidance for AI coding agents on how to apply SmartPrimitive types correctly — choosing the right base type, composing traits, and avoiding common mistakes.

To use it with an agent that supports skills (e.g., Claude):

# Copy to your project's skills directory
cp node_modules/@penner/smart-primitive/SKILL.md .claude/skills/smart-primitive/SKILL.md

Then invoke with /smart-primitive or by asking the agent to "use smart-primitives" on a file or interface.

The skill is also useful as a human-readable style guide for applying SmartPrimitive types consistently across a codebase.

License

MIT