@penner/smart-primitive 0.0.1

package/README.md

@@ -0,0 +1,267 @@
+# @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.
+
+## Why Smart Primitives?
+
+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.
+
+```typescript
+import { SmartNumber, SmartString } from '@penner/smart-primitive';
+
+type Pixels = SmartNumber<'Pixels'>;
+type Milliseconds = SmartNumber<'Milliseconds'>;
+type URL = SmartString<'URL'>;
+type CSSSelector = SmartString<'CSSSelector'>;
+
+// ✅ Works perfectly
+let width: Pixels = 300;
+let delay: Milliseconds = 500;
+let link: URL = 'https://example.com';
+let selector: CSSSelector = '.button';
+
+// ❌ 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'
+```
+
+## Features
+
+- ✅ **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
+
+## Installation
+
+```bash
+npm install @penner/smart-primitive
+```
+
+## Quick Start
+
+### Smart Numbers
+
+Perfect for units, measurements, or any numeric domain:
+
+```typescript
+import { SmartNumber } from '@penner/smart-primitive';
+
+type Pixels = SmartNumber<'Pixels'>;
+type Milliseconds = SmartNumber<'Milliseconds'>;
+type Degrees = SmartNumber<'Degrees'>;
+
+function animate(distance: Pixels, duration: Milliseconds, rotation: Degrees) {
+  console.log(`Move ${distance}px over ${duration}ms, rotate ${rotation}°`);
+}
+
+animate(100, 500, 90); // ✅ works
+animate(100, 500, 500); // ✅ works (but is it degrees or milliseconds? TypeScript doesn't know yet)
+
+// But if you assign first:
+let delay: Milliseconds = 500;
+animate(100, delay, delay); // ❌ Error! Can't use Milliseconds where Degrees expected
+```
+
+### Smart Strings
+
+Distinguish between different kinds of strings:
+
+```typescript
+import { SmartString } from '@penner/smart-primitive';
+
+type URL = SmartString<'URL'>;
+type EmailAddress = SmartString<'EmailAddress'>;
+type CSSSelector = SmartString<'CSSSelector'>;
+
+function fetchData(endpoint: URL) {
+  // implementation
+}
+
+function sendEmail(address: EmailAddress) {
+  // implementation
+}
+
+let api: URL = 'https://api.example.com';
+let email: EmailAddress = 'user@example.com';
+
+fetchData(api); // ✅ works
+fetchData(email); // ❌ Error! EmailAddress is not a URL
+```
+
+### Smart Booleans
+
+Even booleans can benefit from type safety:
+
+```typescript
+import { SmartBoolean } from '@penner/smart-primitive';
+
+type IsVisible = SmartBoolean<'IsVisible'>;
+type IsEnabled = SmartBoolean<'IsEnabled'>;
+
+function toggleVisibility(visible: IsVisible) {
+  // implementation
+}
+
+let visible: IsVisible = true;
+let enabled: IsEnabled = true;
+
+toggleVisibility(visible); // ✅ works
+toggleVisibility(enabled); // ❌ Error! IsEnabled is not IsVisible
+```
+
+## Advanced Usage
+
+### Utility Types
+
+#### `Unbrand<T>`
+
+Remove branding from types, converting them back to primitives:
+
+```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',
+};
+```
+
+#### `BaseOf<T>`
+
+Extract the base primitive type:
+
+```typescript
+import { BaseOf } from '@penner/smart-primitive';
+
+type PixelsBase = BaseOf<Pixels>; // number
+type URLBase = BaseOf<URL>; // string
+type IsVisibleBase = BaseOf<IsVisible>; // boolean
+```
+
+#### `UnbrandFn<F>`
+
+Unbrand function parameters:
+
+```typescript
+import { UnbrandFn } from '@penner/smart-primitive';
+
+function animate(distance: Pixels, duration: Milliseconds): void {
+  // implementation
+}
+
+type PlainAnimate = UnbrandFn<typeof animate>;
+// Result: (distance: number, duration: number) => void
+```
+
+### Feature Flag: Toggle Type Safety
+
+You can disable all smart type checking with a single flag. This is useful for:
+
+- Performance testing
+- Debugging type issues
+- Gradual migration
+- Bundle size optimization
+
+```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)
+```
+
+## How It Works
+
+Smart primitives use TypeScript's brand pattern (also called phantom types or nominal typing). The implementation is remarkably simple:
+
+```typescript
+export type SmartPrimitive<
+  Base extends string | number | boolean | bigint | symbol,
+  BrandName extends string,
+> = Base & { readonly __brand?: BrandName };
+```
+
+The `__brand` property is:
+
+- **Optional** - so plain primitives are assignable
+- **Readonly** - prevents accidental modification
+- **Never actually exists at runtime** - TypeScript-only, zero overhead
+
+## TypeScript Compatibility
+
+Requires TypeScript 4.5 or higher.
+
+## Examples
+
+### Complex Object Structures
+
+```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,
+};
+```
+
+### Function Safety
+
+```typescript
+function moveElement(
+  element: HTMLElement,
+  distance: Pixels,
+  duration: Milliseconds,
+): void {
+  // TypeScript ensures you can't accidentally swap parameters
+}
+
+let dist: Pixels = 100;
+let time: Milliseconds = 500;
+
+moveElement(element, dist, time); // ✅ correct
+moveElement(element, time, dist); // ❌ Error! Parameters swapped
+```
+
+## License
+
+MIT
+
+## Related Packages
+
+- [`@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
+
+## Contributing
+
+Contributions welcome! Please read the [contributing guidelines](../../CONTRIBUTING.md) first.

package/dist/SmartPrimitive.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 🔧 FEATURE FLAG: Toggle smart primitive type checking
+ * When false (default): SmartPrimitive types provide type safety
+ * When true: All SmartNumber, SmartString, etc. become plain primitives
+ *
+ * Use cases:
+ * - Performance testing (eliminate type overhead)
+ * - Debugging type issues
+ * - 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
+ */
+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.
+ */
+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;
+/**
+ * Generic smart primitive type that provides **opt-in type safety** while staying flexible.
+ *
+ * **How it works:**
+ * - ✅ **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
+ *
+ * **Example:**
+ * ```ts
+ * type Pixels = SmartPrimitive<number, 'Pixels'>;
+ * type Milliseconds = SmartPrimitive<number, 'Milliseconds'>;
+ *
+ * let width: Pixels = 300;        // ✅ Plain number works
+ * let delay: Milliseconds = 500;        // ✅ Plain number works
+ * let oops: Pixels = delay;       // ❌ TypeScript error - caught the mistake!
+ * ```
+ *
+ * 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;
+};
+/**
+ * A smart number type for domain-specific numeric values like pixels, milliseconds, etc.
+ *
+ * **Why use this?** Prevents common bugs like mixing up different kinds of numbers:
+ * - Using milliseconds where pixels are expected
+ * - Passing a width value to a duration parameter
+ * - Confusing degrees with radians
+ *
+ * **How it works:**
+ * - ✅ Works with plain numbers: `let width: Pixels = 300`
+ * - ✅ 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.
+ *
+ * **Example:**
+ * ```ts
+ * type Pixels = SmartNumber<'Pixels'>;
+ * type Milliseconds = SmartNumber<'Milliseconds'>;
+ *
+ * let width: Pixels = 300;        // ✅ works
+ * let delay: Milliseconds = 500;        // ✅ works
+ * let badAssign: Pixels = delay;  // ❌ type error - caught the mistake!
+ * ```
+ *
+ * When USE_PLAIN_PRIMITIVES = false (default):
+ * - Full smart number system with type safety between different units
+ * - Plain numbers accepted seamlessly
+ * - Clean tooltip display
+ *
+ * When USE_PLAIN_PRIMITIVES = true:
+ * - All smart number types collapse to plain `number`
+ * - Zero runtime overhead, maximum performance
+ *
+ * Usage remains the same regardless of flag state:
+ * ```ts
+ * let distance: Pixels = 300;           // ✅ always works
+ * let branded: Pixels = 300 as Pixels;  // ✅ always works
+ * ```
+ */
+export type SmartNumber<BrandName extends string> = SmartPrimitive<number, BrandName>;
+/**
+ * A smart string type that accepts plain strings but maintains type identity.
+ * Perfect for things like URLs, CSS selectors, or other domain-specific strings.
+ *
+ * Usage:
+ * ```ts
+ * type URL = SmartString<'URL'>;
+ * type CSSSelector = SmartString<'CSSSelector'>;
+ *
+ * let url: URL = "https://example.com";        // ✅ works
+ * let selector: CSSSelector = ".my-class";     // ✅ works
+ * let badAssign: URL = selector;               // ❌ type error
+ * ```
+ */
+export type SmartString<BrandName extends string> = SmartPrimitive<string, BrandName>;
+/**
+ * A smart boolean type that accepts plain booleans but maintains type identity.
+ * Useful for domain-specific flags or state indicators.
+ *
+ * Usage:
+ * ```ts
+ * type IsVisible = SmartBoolean<'IsVisible'>;
+ * type IsEnabled = SmartBoolean<'IsEnabled'>;
+ *
+ * let visible: IsVisible = true;               // ✅ works
+ * let enabled: IsEnabled = false;              // ✅ works
+ * let badAssign: IsVisible = enabled;          // ❌ type error
+ * ```
+ */
+export type SmartBoolean<BrandName extends string> = SmartPrimitive<boolean, BrandName>;
+/**
+ * Simplified Unbrand using the generic brand pattern.
+ * Also respects the USE_PLAIN_PRIMITIVES flag.
+ *
+ * When USE_PLAIN_PRIMITIVES = true: This becomes a no-op (types pass through unchanged)
+ * When USE_PLAIN_PRIMITIVES = false: Full unbranding to base types
+ */
+export type Unbrand<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 extends Record<string, unknown> ? {
+    [K in keyof T]: Unbrand<T[K]>;
+} : T;
+/**
+ * Given any function type F, produce a new function type whose
+ * arguments have been passed through Unbrand<…>, and whose return
+ * type you can also choose to unbrand (or leave alone).
+ */
+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 };
+//# sourceMappingURL=SmartPrimitive.d.ts.map

package/dist/SmartPrimitive.d.ts.map

@@ -0,0 +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"}

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

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

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

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

package/dist/index.cjs.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=!1;exports.USE_PLAIN_PRIMITIVES=e;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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, with no runtime cost.
+ *
+ * @example
+ * ```ts
+ * import { SmartNumber, SmartString } from '@penner/smart-primitive';
+ *
+ * type Pixels = SmartNumber<'Pixels'>;
+ * type Milliseconds = SmartNumber<'Milliseconds'>;
+ * type URL = SmartString<'URL'>;
+ *
+ * let width: Pixels = 300;        // ✅ works
+ * let delay: Milliseconds = 500;  // ✅ works
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.es.js

@@ -0,0 +1,5 @@
+const I = !1;
+export {
+  I as USE_PLAIN_PRIMITIVES
+};
+//# sourceMappingURL=index.es.js.map

package/dist/index.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.es.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":"AAoBO,MAAMA,IAAuB;"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@penner/smart-primitive",
+  "version": "0.0.1",
+  "description": "Type-safe branded primitives with zero runtime overhead - prevent bugs by distinguishing different kinds of numbers, strings, and booleans",
+  "author": "Robert Penner <robert@robertpenner.com> (https://robertpenner.com)",
+  "homepage": "https://github.com/robertpenner/penner",
+  "repository": "github:robertpenner/penner",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.17"
+  },
+  "keywords": [
+    "typescript",
+    "branded-types",
+    "type-safety",
+    "smart-types",
+    "phantom-types",
+    "zero-runtime",
+    "compile-time",
+    "units",
+    "type-checking",
+    "developer-experience"
+  ],
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsc && vite build --watch",
+    "build": "tsc && vite build",
+    "build:types": "dts-bundle-generator --config ./dts-bundle-generator.config.ts",
+    "lint:scripts": "eslint ./src --ext .ts",
+    "format:scripts": "prettier ./src --write",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.8.1",
+    "@typescript-eslint/eslint-plugin": "^8.11.0",
+    "@typescript-eslint/parser": "^8.11.0",
+    "@vitest/coverage-v8": "^3.2.2",
+    "dts-bundle-generator": "^9.5.1",
+    "eslint": "^9.13.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "prettier": "^3.3.3",
+    "tslib": "^2.8.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "vite": "^5.4.10",
+    "vite-plugin-dts": "^4.3.0",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.2"
+  }
+}