Add Branded Types for Compile-Time Type Safety (#17)

* add branded types

* update package

Author: Zheruel

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2025-09-06
+
+### Added
+
+- **Branded Types for TypeScript** - Compile-time type safety for validated strings
+  - New `branded` namespace export with zero runtime overhead
+  - Three branded types: `Email`, `URL`, `Slug`
+  - **Type Guards**: `isValidEmail()`, `isValidUrl()`, `isSlug()` for type narrowing
+  - **Builder Functions**: `toEmail()`, `toUrl()`, `toSlug()` for safe construction with validation
+  - **Assertion Functions**: `assertEmail()`, `assertUrl()`, `assertSlug()` for runtime assertions with type narrowing
+  - **Unsafe Variants**: `unsafeEmail()`, `unsafeUrl()`, `unsafeSlug()` for trusted inputs
+  - **Utility Functions**: `ensureSlug()` for intelligent slug handling
+  - **Custom Error Class**: `BrandedTypeError` for validation failures
+  - Generic `Brand<K, T>` type utility for creating custom branded types
+  - Full tree-shaking support - only imported when used
+  - 100% test coverage with type-level tests using `expectTypeOf`
+  - Comprehensive documentation with usage examples
+
+### Performance
+
+- Branded type guards have identical performance to base validators
+- Unsafe variants operate at ~18M ops/sec (simple type casts)
+- No impact on bundle size for non-TypeScript users
+- Bundle size remains under 6.5KB limit (6.35KB CJS)
+
 ## [0.6.0] - 2025-09-06
 
 ### Added

README.md

@@ -753,6 +753,128 @@ Features:
 - Preserves original casing
 - Handles edge cases like unchanged plurals (sheep→sheep)
 
+### Branded Types (TypeScript)
+
+Nano-string-utils provides branded types for compile-time type safety with validated strings. These types add zero runtime overhead and are fully tree-shakeable.
+
+```typescript
+import { branded } from "nano-string-utils";
+```
+
+#### Type Guards
+
+Type guards narrow string types to branded types:
+
+```typescript
+const input: string = getUserInput();
+
+if (branded.isValidEmail(input)) {
+  // input is now typed as Email
+  sendEmail(input);
+}
+
+if (branded.isValidUrl(input)) {
+  // input is now typed as URL
+  fetch(input);
+}
+
+if (branded.isSlug(input)) {
+  // input is now typed as Slug
+  useAsRoute(input);
+}
+```
+
+#### Builder Functions
+
+Safely create branded types with validation:
+
+```typescript
+// Returns Email | null
+const email = branded.toEmail("[email protected]");
+if (email) {
+  sendEmail(email); // email is typed as Email
+}
+
+// Returns URL | null
+const url = branded.toUrl("https://example.com");
+if (url) {
+  fetch(url); // url is typed as URL
+}
+
+// Always returns Slug (transforms input)
+const slug = branded.toSlug("Hello World!"); // 'hello-world' as Slug
+createRoute(slug);
+
+// Smart slug handling
+const slug2 = branded.ensureSlug("already-a-slug"); // returns as-is if valid
+const slug3 = branded.ensureSlug("Not A Slug!"); // transforms to 'not-a-slug'
+```
+
+#### Assertion Functions
+
+Assert types with runtime validation:
+
+```typescript
+const input: string = getUserInput();
+
+// Throws BrandedTypeError if invalid
+branded.assertEmail(input);
+// input is now typed as Email
+sendEmail(input);
+
+// Custom error messages
+branded.assertUrl(input, "Invalid webhook URL");
+
+// All assertion functions available
+branded.assertEmail(str);
+branded.assertUrl(str);
+branded.assertSlug(str);
+```
+
+#### Unsafe Variants
+
+For trusted inputs where validation isn't needed:
+
+```typescript
+// Use only when you're certain the input is valid
+const trustedEmail = branded.unsafeEmail("[email protected]");
+const trustedUrl = branded.unsafeUrl("https://internal.api");
+const trustedSlug = branded.unsafeSlug("already-valid-slug");
+```
+
+#### Available Types
+
+- `Email` - Validated email addresses
+- `URL` - Validated URLs (http/https/ftp/ftps)
+- `Slug` - URL-safe slugs (lowercase, hyphenated)
+- `Brand<T, K>` - Generic branding utility for custom types
+
+#### Benefits
+
+- **Zero runtime overhead** - Types are erased at compilation
+- **Type safety** - Prevent passing unvalidated strings to functions
+- **IntelliSense support** - Full autocomplete and type hints
+- **Tree-shakeable** - Only imported if used
+- **Composable** - Works with existing string functions
+
+```typescript
+// Example: Type-safe API
+function sendNewsletter(email: branded.Email) {
+  // Can only be called with validated emails
+  api.send(email);
+}
+
+// Won't compile without validation
+const userInput = "[email protected]";
+// sendNewsletter(userInput); // ❌ Type error!
+
+// Must validate first
+const validated = branded.toEmail(userInput);
+if (validated) {
+  sendNewsletter(validated); // ✅ Type safe!
+}
+```
+
 ## Bundle Size
 
 Each utility is optimized to be as small as possible:

benchmarks/branded.bench.ts

@@ -0,0 +1,64 @@
+import { bench, describe } from "vitest";
+import { branded, isEmail, isUrl, slugify } from "../src/index";
+
+describe("Branded Types Performance", () => {
+  const validEmail = "[email protected]";
+  const validUrl = "https://example.com";
+  const textToSlug = "Hello World Example";
+
+  bench("branded.isValidEmail", () => {
+    branded.isValidEmail(validEmail);
+  });
+
+  bench("isEmail (baseline)", () => {
+    isEmail(validEmail);
+  });
+
+  bench("branded.isValidUrl", () => {
+    branded.isValidUrl(validUrl);
+  });
+
+  bench("isUrl (baseline)", () => {
+    isUrl(validUrl);
+  });
+
+  bench("branded.isSlug", () => {
+    branded.isSlug("hello-world");
+  });
+
+  bench("branded.toEmail", () => {
+    branded.toEmail(validEmail);
+  });
+
+  bench("branded.toUrl", () => {
+    branded.toUrl(validUrl);
+  });
+
+  bench("branded.toSlug", () => {
+    branded.toSlug(textToSlug);
+  });
+
+  bench("slugify (baseline)", () => {
+    slugify(textToSlug);
+  });
+
+  bench("branded.ensureSlug (already valid)", () => {
+    branded.ensureSlug("already-a-slug");
+  });
+
+  bench("branded.ensureSlug (needs transform)", () => {
+    branded.ensureSlug("Not A Slug");
+  });
+
+  bench("branded.unsafeEmail", () => {
+    branded.unsafeEmail(validEmail);
+  });
+
+  bench("branded.unsafeUrl", () => {
+    branded.unsafeUrl(validUrl);
+  });
+
+  bench("branded.unsafeSlug", () => {
+    branded.unsafeSlug("test-slug");
+  });
+});

jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@zheruel/nano-string-utils",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "exports": "./src/index.ts",
   "publish": {
     "include": ["src/**/*.ts", "README.md", "LICENSE", "CHANGELOG.md"],

package.json

@@ -1,6 +1,6 @@
 {
   "name": "nano-string-utils",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Ultra-lightweight string utilities with zero dependencies",
   "type": "module",
   "main": "./dist/index.cjs",

src/index.ts

@@ -49,3 +49,6 @@ export {
 export { pluralize } from "./pluralize.js";
 export { singularize } from "./singularize.js";
 export { memoize, type MemoizeOptions } from "./memoize.js";
+
+// Branded types namespace export
+export * as branded from "./types/index.js";

src/types/assertions.ts

@@ -0,0 +1,64 @@
+import {
+  BrandedTypeError,
+  type Email,
+  type URL,
+  type Slug,
+} from "./branded.js";
+import { isValidEmail, isValidUrl, isSlug } from "./guards.js";
+
+/**
+ * Asserts that a string is a valid Email, throwing if validation fails.
+ * After this assertion, TypeScript knows the value is an Email.
+ * @param str - The string to validate
+ * @param message - Optional custom error message
+ * @throws {BrandedTypeError} If the string is not a valid email
+ * @example
+ * const input: string = getUserInput();
+ * assertEmail(input);
+ * // input is now typed as Email
+ * sendEmail(input);
+ */
+export function assertEmail(
+  str: string,
+  message?: string
+): asserts str is Email {
+  if (!isValidEmail(str)) {
+    throw new BrandedTypeError(message || "Email", str);
+  }
+}
+
+/**
+ * Asserts that a string is a valid URL, throwing if validation fails.
+ * After this assertion, TypeScript knows the value is a URL.
+ * @param str - The string to validate
+ * @param message - Optional custom error message
+ * @throws {BrandedTypeError} If the string is not a valid URL
+ * @example
+ * const input: string = getUserInput();
+ * assertUrl(input);
+ * // input is now typed as URL
+ * fetch(input);
+ */
+export function assertUrl(str: string, message?: string): asserts str is URL {
+  if (!isValidUrl(str)) {
+    throw new BrandedTypeError(message || "URL", str);
+  }
+}
+
+/**
+ * Asserts that a string is a valid Slug, throwing if validation fails.
+ * After this assertion, TypeScript knows the value is a Slug.
+ * @param str - The string to validate
+ * @param message - Optional custom error message
+ * @throws {BrandedTypeError} If the string is not a valid slug
+ * @example
+ * const input: string = 'hello-world';
+ * assertSlug(input);
+ * // input is now typed as Slug
+ * createRoute(input);
+ */
+export function assertSlug(str: string, message?: string): asserts str is Slug {
+  if (!isSlug(str)) {
+    throw new BrandedTypeError(message || "Slug", str);
+  }
+}

src/types/branded.ts

@@ -0,0 +1,49 @@
+/**
+ * Core branded type system for compile-time type safety.
+ * Branded types provide nominal typing in TypeScript's structural type system.
+ */
+
+/**
+ * Generic brand type that creates a nominal type by intersecting
+ * with a unique brand property that only exists at the type level.
+ */
+export type Brand<K, T> = K & { __brand: T };
+
+/**
+ * Email branded type - represents a validated email address string.
+ * Use with type guards and builder functions for type safety.
+ * @example
+ * const email: Email = toEmail('[email protected]')!;
+ */
+export type Email = Brand<string, "Email">;
+
+/**
+ * URL branded type - represents a validated URL string.
+ * Use with type guards and builder functions for type safety.
+ * @example
+ * const url: URL = toUrl('https://example.com')!;
+ */
+export type URL = Brand<string, "URL">;
+
+/**
+ * Slug branded type - represents a URL-safe slug string.
+ * Use with type guards and builder functions for type safety.
+ * @example
+ * const slug: Slug = toSlug('Hello World'); // 'hello-world'
+ */
+export type Slug = Brand<string, "Slug">;
+
+/**
+ * Type guard result type for better type inference
+ */
+export type ValidationResult<T> = T | null;
+
+/**
+ * Assertion error for branded type validation failures
+ */
+export class BrandedTypeError extends Error {
+  constructor(type: string, value: string) {
+    super(`Invalid ${type}: "${value}"`);
+    this.name = "BrandedTypeError";
+  }
+}