refactor(types): add a branded hexcolor type to replace plain strings

Author: MaitrayeeK

lib/svg/generator.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { generateSVG, generateMonthlySVG, particleCount, escapeXML } from './generator';
 import type { BadgeParams, ContributionCalendar, StreakStats, MonthlyStats } from '../../types';
+import { hexColor } from './sanitizer';
 
 describe('generateSVG', () => {
   const mockStats: StreakStats = {
@@ -186,9 +187,9 @@ describe('generateSVG', () => {
   describe('autoTheme', () => {
     const autoParams: BadgeParams = {
       user: 'avi',
-      bg: 'ffffff',
-      text: '24292f',
-      accent: '0969da',
+      bg: hexColor('ffffff'),
+      text: hexColor('24292f'),
+      accent: hexColor('0969da'),
       speed: '8s',
       scale: 'linear',
       autoTheme: true,
@@ -247,9 +248,9 @@ describe('generateSVG', () => {
     it('does NOT inject a media query for non-auto themes', () => {
       const staticParams: BadgeParams = {
         user: 'avi',
-        bg: '0d1117',
-        text: 'c9d1d9',
-        accent: '58a6ff',
+        bg: hexColor('0d1117'),
+        text: hexColor('c9d1d9'),
+        accent: hexColor('58a6ff'),
         speed: '8s',
         scale: 'linear',
         autoTheme: false,

lib/svg/sanitizer.ts

@@ -3,6 +3,8 @@
  * Prevents attribute injection and malformed SVG generation.
  */
 
+import type { HexColor } from '../../types/index';
+
 const HEX_COLOR_REGEX = /^([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
 
 /**
@@ -15,20 +17,36 @@ export function isValidHex(color?: string): boolean {
   return HEX_COLOR_REGEX.test(cleanColor);
 }
 
+/**
+ * Converts a known-safe hex color literal to the `HexColor` branded type.
+ * Intended for hardcoded values in theme definitions, tests, and fixtures
+ * where the color is authored by a developer rather than supplied by user input.
+ *
+ * If the value is invalid, falls back to `fallback` (defaults to `'000000'`).
+ * For user-supplied input, use `sanitizeHexColor` instead.
+ */
+export function hexColor(value: string, fallback = '000000'): HexColor {
+  const cleaned = value.replace('#', '');
+  if (HEX_COLOR_REGEX.test(cleaned)) {
+    return cleaned as HexColor;
+  }
+  return fallback.replace('#', '') as HexColor;
+}
+
 /**
  * Sanitizes a color input, ensuring it's a valid hex or falls back to a safe value.
  * Always returns a hex string WITHOUT the leading #.
  */
-export function sanitizeHexColor(input: string | undefined | null, fallback: string): string {
-  if (!input) return fallback.replace('#', '');
+export function sanitizeHexColor(input: string | undefined | null, fallback: string): HexColor {
+  if (!input) return fallback.replace('#', '') as HexColor;
 
   const cleanInput = input.trim().replace('#', '');
 
   if (HEX_COLOR_REGEX.test(cleanInput)) {
-    return cleanInput;
+    return cleanInput as HexColor;
   }
 
-  return fallback.replace('#', '');
+  return fallback.replace('#', '') as HexColor;
 }
 
 /**

lib/svg/themes.ts

@@ -1,72 +1,29 @@
 // lib/svg/themes.ts
 import { BadgeTheme } from '../../types';
+import { hexColor } from './sanitizer';
+
+function makeTheme(bg: string, text: string, accent: string): BadgeTheme {
+  return {
+    bg: hexColor(bg),
+    text: hexColor(text),
+    accent: hexColor(accent),
+  };
+}
 
 export const themes: Record<string, BadgeTheme> = {
-  dark: {
-    bg: '0d1117',
-    text: 'c9d1d9',
-    accent: '58a6ff',
-  },
-  light: {
-    bg: 'ffffff',
-    text: '24292f',
-    accent: '0969da',
-  },
-  neon: {
-    bg: '000000',
-    text: '00ffcc',
-    accent: 'ff00ff',
-  },
-  github: {
-    bg: '0d1117',
-    text: 'ffffff',
-    accent: '238636', // The classic green
-  },
-  dracula: {
-    bg: '282a36',
-    text: 'f8f8f2',
-    accent: 'bd93f9',
-  },
-  ocean: {
-    bg: '0a192f',
-    text: 'ccd6f6',
-    accent: '64ffda',
-  },
-  sunset: {
-    bg: '1a0a0a',
-    text: 'ffd6c0',
-    accent: 'ff6b35',
-  },
-  forest: {
-    bg: '0d1f0d',
-    text: 'c8f0c8',
-    accent: '39d353',
-  },
-  rose: {
-    bg: '1f0d14',
-    text: 'f0c8d4',
-    accent: 'ff6b9d',
-  },
-  nord: {
-    bg: '2e3440',
-    text: 'd8dee9',
-    accent: '88c0d0',
-  },
-  synthwave: {
-    bg: '0d0221',
-    text: 'f8f8f2',
-    accent: 'ff2d78',
-  },
-  gruvbox: {
-    bg: '282828',
-    text: 'ebdbb2',
-    accent: 'fe8019',
-  },
-  highcontrast: {
-    bg: '0a0a0a', // High-contrast theme: vivid red-orange accent on near-black background.
-    text: '888888',
-    accent: 'ff4500',
-  },
+  dark: makeTheme('0d1117', 'c9d1d9', '58a6ff'),
+  light: makeTheme('ffffff', '24292f', '0969da'),
+  neon: makeTheme('000000', '00ffcc', 'ff00ff'),
+  github: makeTheme('0d1117', 'ffffff', '238636'),
+  dracula: makeTheme('282a36', 'f8f8f2', 'bd93f9'),
+  ocean: makeTheme('0a192f', 'ccd6f6', '64ffda'),
+  sunset: makeTheme('1a0a0a', 'ffd6c0', 'ff6b35'),
+  forest: makeTheme('0d1f0d', 'c8f0c8', '39d353'),
+  rose: makeTheme('1f0d14', 'f0c8d4', 'ff6b9d'),
+  nord: makeTheme('2e3440', 'd8dee9', '88c0d0'),
+  synthwave: makeTheme('0d0221', 'f8f8f2', 'ff2d78'),
+  gruvbox: makeTheme('282828', 'ebdbb2', 'fe8019'),
+  highcontrast: makeTheme('0a0a0a', '888888', 'ff4500'),
 };
 
 // Auto-theme pairs: the SVG switches between these two palettes

scripts/benchmark-svg.ts

@@ -1,5 +1,6 @@
 import { performance } from 'perf_hooks';
 import { generateSVG } from '../lib/svg/generator';
+import { hexColor } from '../lib/svg/sanitizer';
 
 const stats = {
   currentStreak: 12,
@@ -30,21 +31,21 @@ const calendar = {
 const themes = [
   {
     name: 'dark',
-    bg: '0d1117',
-    accent: '00ffaa',
-    text: 'ffffff',
+    bg: hexColor('0d1117'),
+    accent: hexColor('00ffaa'),
+    text: hexColor('ffffff'),
   },
   {
     name: 'light',
-    bg: 'ffffff',
-    accent: 'ff00aa',
-    text: '111111',
+    bg: hexColor('ffffff'),
+    accent: hexColor('ff00aa'),
+    text: hexColor('111111'),
   },
   {
     name: 'purple',
-    bg: '1a1025',
-    accent: '9b5cff',
-    text: 'f5f5f5',
+    bg: hexColor('1a1025'),
+    accent: hexColor('9b5cff'),
+    text: hexColor('f5f5f5'),
   },
 ];
 

types/index.ts

@@ -1,3 +1,5 @@
+export type HexColor = string & { __brand: 'HexColor' };
+
 export interface StreakStats {
   currentStreak: number;
   longestStreak: number;
@@ -6,9 +8,9 @@ export interface StreakStats {
 }
 
 export interface BadgeTheme {
-  bg: string;
-  text: string;
-  accent: string;
+  bg: HexColor;
+  text: HexColor;
+  accent: HexColor;
 }
 
 export interface ContributionDay {
@@ -35,9 +37,9 @@ export interface MonthlyStats {
 
 export interface BadgeParams {
   user: string;
-  bg: string;
-  text: string;
-  accent: string;
+  bg: HexColor;
+  text: HexColor;
+  accent: HexColor;
   speed: string;
   scale: 'linear' | 'log';
   font?: string;