Add Template Literal Types for Case Conversions (#18)

* add template literal types

* update docs

Author: Zheruel

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2025-09-07
+
+### Added
+
+- **Template Literal Types for Case Conversions** - Compile-time type transformations
+  - Advanced TypeScript template literal types for all 9 case conversion functions
+  - Precise type inference for literal strings (e.g., `kebabCase("helloWorld")` returns type `"hello-world"`)
+  - Function overloads preserve literal types while maintaining backward compatibility
+  - Complex type-level string parsing with proper word boundary detection
+  - Handles camelCase, PascalCase, ALLCAPS, consecutive digits, and special characters
+  - Zero runtime cost - all transformations happen at compile time
+  - Runtime strings still return regular `string` type for backward compatibility
+  - Comprehensive type-level tests and real-world usage examples
+  - Enhanced IDE support with autocomplete showing exact transformed strings
+  - No impact on bundle size (remains at 6.01 kB)
+
 ## [0.7.0] - 2025-09-06
 
 ### Added

README.md

@@ -14,11 +14,11 @@ Ultra-lightweight string utilities with zero dependencies. Tree-shakeable, fully
 - 🚀 **Zero dependencies** - No bloat, just pure functions
 - 📦 **< 1KB per function** - Minimal bundle impact
 - 🌳 **Tree-shakeable** - Only import what you need
-- 💪 **Fully typed** - Complete TypeScript support with function overloads
+- 💪 **Fully typed** - Complete TypeScript support with function overloads and template literal types
 - ⚡ **Fast performance** - 2-25x faster than lodash for many operations
 - ⚡ **ESM & CJS** - Works everywhere
 - 🧪 **100% tested** - Reliable and production-ready
-- 🔒 **Type-safe** - Written in strict TypeScript with enhanced type inference
+- 🔒 **Type-safe** - Written in strict TypeScript with enhanced type inference and compile-time transformations
 - 📝 **Well documented** - JSDoc comments for all functions
 
 ## Installation
@@ -875,6 +875,79 @@ if (validated) {
 }
 ```
 
+### Template Literal Types (TypeScript)
+
+Case conversion functions now provide precise type inference for literal strings at compile time. This feature enhances IDE support with exact type transformations while maintaining full backward compatibility.
+
+```typescript
+import { camelCase, kebabCase, snakeCase } from "nano-string-utils";
+
+// Literal strings get exact transformed types
+const endpoint = kebabCase("getUserProfile");
+// Type: "get-user-profile" (not just string!)
+
+const column = snakeCase("firstName");
+// Type: "first_name"
+
+const methodName = camelCase("fetch-user-data");
+// Type: "fetchUserData"
+
+// Runtime strings still return regular string type
+const userInput: string = getUserInput();
+const result = camelCase(userInput);
+// Type: string (backward compatible)
+```
+
+#### All Case Conversions Support Template Literals
+
+```typescript
+camelCase("hello-world");    // Type: "helloWorld"
+kebabCase("helloWorld");     // Type: "hello-world"
+snakeCase("HelloWorld");     // Type: "hello_world"
+pascalCase("hello-world");   // Type: "HelloWorld"
+constantCase("helloWorld");  // Type: "HELLO_WORLD"
+dotCase("HelloWorld");       // Type: "hello.world"
+pathCase("helloWorld");      // Type: "hello/world"
+sentenceCase("hello-world"); // Type: "Hello world"
+titleCase("hello-world");    // Type: "Hello World"
+```
+
+#### Type-Safe Configuration Objects
+
+Transform configuration keys between naming conventions:
+
+```typescript
+const config = {
+  "api-base-url": "https://api.example.com",
+  "max-retries": 3,
+} as const;
+
+// Convert keys to camelCase at type level
+type ConfigCamelCase = {
+  [K in keyof typeof config as CamelCase<K>]: (typeof config)[K];
+};
+// Type: { apiBaseUrl: string; maxRetries: number; }
+```
+
+#### API Route Mapping
+
+Create type-safe method names from API routes:
+
+```typescript
+type ApiRoutes = "user-profile" | "user-settings" | "admin-panel";
+
+type MethodNames = {
+  [K in ApiRoutes as `fetch${PascalCase<K>}`]: () => Promise<void>;
+};
+// Creates: fetchUserProfile(), fetchUserSettings(), fetchAdminPanel()
+```
+
+Benefits:
+- ✅ **Zero runtime cost** - All transformations happen at compile time
+- ✅ **Better IDE support** - Autocomplete shows exact transformed strings
+- ✅ **Type safety** - Catch typos and incorrect transformations during development
+- ✅ **Backward compatible** - Runtime strings work exactly as before
+
 ## Bundle Size
 
 Each utility is optimized to be as small as possible:

examples/template-literal-types.ts

@@ -0,0 +1,209 @@
+/**
+ * Examples demonstrating template literal types for case conversions
+ * These provide compile-time type transformations for better type safety
+ */
+
+import {
+  camelCase,
+  kebabCase,
+  snakeCase,
+  pascalCase,
+  constantCase,
+  dotCase,
+  pathCase,
+  sentenceCase,
+  titleCase,
+} from "../src/index.js";
+
+import type {
+  CamelCase,
+  KebabCase,
+  SnakeCase,
+  PascalCase,
+  ConstantCase,
+  DotCase,
+  PathCase,
+  SentenceCase,
+  TitleCase,
+} from "../src/types/string-literals.js";
+
+// ============================================
+// 1. Basic Usage - Literal strings get literal types
+// ============================================
+
+// When you pass a literal string, you get the exact transformed type back
+const apiEndpoint = kebabCase("getUserProfile");
+// Type: "get-user-profile" (not just string!)
+
+const dbColumn = snakeCase("firstName");
+// Type: "first_name"
+
+const componentName = pascalCase("user-avatar");
+// Type: "UserAvatar"
+
+const envVar = constantCase("apiKey");
+// Type: "API_KEY"
+
+// ============================================
+// 2. Type-safe API Routes
+// ============================================
+
+// Define your routes with literal types
+type ApiRoutes = "user-profile" | "user-settings" | "admin-panel";
+
+// Convert to camelCase for JavaScript method names
+type MethodNames = {
+  [K in ApiRoutes as `fetch${PascalCase<K>}`]: () => Promise<void>;
+};
+
+// This creates an interface with:
+// fetchUserProfile(): Promise<void>
+// fetchUserSettings(): Promise<void>
+// fetchAdminPanel(): Promise<void>
+
+// ============================================
+// 3. Configuration Objects
+// ============================================
+
+// Convert between different naming conventions in configs
+const config = {
+  "api-base-url": "https://api.example.com",
+  "max-retries": 3,
+  "timeout-ms": 5000,
+} as const;
+
+// Transform keys to camelCase for JavaScript usage
+type ConfigCamelCase = {
+  [K in keyof typeof config as CamelCase<K>]: (typeof config)[K];
+};
+
+// Now you have type-safe camelCase keys:
+// apiBaseUrl: "https://api.example.com"
+// maxRetries: 3
+// timeoutMs: 5000
+
+// ============================================
+// 4. Database Schema Mapping
+// ============================================
+
+// Map JavaScript property names to database columns
+class User {
+  firstName: string = "";
+  lastName: string = "";
+  emailAddress: string = "";
+
+  // Get the database column name with compile-time safety
+  getColumn<T extends keyof this & string>(prop: T): SnakeCase<T> {
+    return snakeCase(prop) as SnakeCase<T>;
+  }
+}
+
+const user = new User();
+const column = user.getColumn("firstName");
+// Type: "first_name"
+
+// ============================================
+// 5. Event Handler Names
+// ============================================
+
+// Convert event names to handler method names
+type EventName = "user-clicked" | "form-submitted" | "data-loaded";
+
+type HandlerName<T extends EventName> = `on${PascalCase<T>}`;
+
+function createHandler<T extends EventName>(event: T): HandlerName<T> {
+  return `on${pascalCase(event)}` as HandlerName<T>;
+}
+
+const clickHandler = createHandler("user-clicked");
+// Type: "onUserClicked"
+
+// ============================================
+// 6. CSS Class Names
+// ============================================
+
+// Convert component names to BEM-style CSS classes
+type ComponentName = "UserProfile" | "NavigationMenu" | "SearchBar";
+
+function getCssClass<T extends ComponentName>(component: T): KebabCase<T> {
+  return kebabCase(component) as KebabCase<T>;
+}
+
+const cssClass = getCssClass("UserProfile");
+// Type: "user-profile"
+
+// ============================================
+// 7. Backward Compatibility
+// ============================================
+
+// Runtime strings still work exactly as before
+function processUserInput(input: string): string {
+  // Returns regular string type for runtime values
+  return camelCase(input);
+}
+
+const userInput = "some-runtime-value";
+const result = camelCase(userInput);
+// Type: string (not a literal type)
+
+// ============================================
+// 8. Chaining Transformations
+// ============================================
+
+// Chain multiple transformations with type safety
+const original = "hello-world" as const;
+
+const camel = camelCase(original);
+// Type: "helloWorld"
+
+const pascal = pascalCase(camel);
+// Type: "HelloWorld"
+
+const constant = constantCase(pascal);
+// Type: "HELLO_WORLD"
+
+const sentence = sentenceCase(constant);
+// Type: "Hello world"
+
+// ============================================
+// 9. Template Literal Composition
+// ============================================
+
+const prefix = "get" as const;
+const entity = "user-profile" as const;
+const methodName = camelCase(`${prefix}-${entity}`);
+// Type: "getUserProfile"
+
+// ============================================
+// 10. Type Guards with Literal Types
+// ============================================
+
+type KebabString = `${string}-${string}`;
+
+function isKebabCase(str: string): str is KebabString {
+  return str.includes("-") && str === str.toLowerCase();
+}
+
+function processKebab(str: string) {
+  if (isKebabCase(str)) {
+    // TypeScript knows str matches kebab pattern
+    const camelVersion = camelCase(str);
+    // Gets more precise type inference
+    return camelVersion;
+  }
+  return str;
+}
+
+// ============================================
+// Export for demonstration
+// ============================================
+
+export {
+  apiEndpoint,
+  dbColumn,
+  componentName,
+  envVar,
+  clickHandler,
+  cssClass,
+  methodName,
+};

jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@zheruel/nano-string-utils",
-  "version": "0.7.0",
+  "version": "0.8.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.7.0",
+  "version": "0.8.0",
   "description": "Ultra-lightweight string utilities with zero dependencies",
   "type": "module",
   "main": "./dist/index.cjs",

src/camelCase.ts

@@ -1,4 +1,5 @@
 import { words } from "./words.js";
+import type { CamelCase } from "./types/string-literals.js";
 
 /**
  * Converts a string to camelCase
@@ -8,8 +9,13 @@ import { words } from "./words.js";
  * camelCase('hello world') // 'helloWorld'
  * camelCase('hello-world') // 'helloWorld'
  * camelCase('hello_world') // 'helloWorld'
+ *
+ * // With template literal types
+ * const result = camelCase('hello-world'); // type: "helloWorld"
  */
-export const camelCase = (str: string): string => {
+export function camelCase<T extends string>(str: T): CamelCase<T>;
+export function camelCase(str: string): string;
+export function camelCase(str: string): string {
   const wordList = words(str);
 
   if (wordList.length === 0) return "";
@@ -22,4 +28,4 @@ export const camelCase = (str: string): string => {
       return lower.charAt(0).toUpperCase() + lower.slice(1);
     })
     .join("");
-};
+}

src/constantCase.ts

@@ -1,3 +1,5 @@
+import type { ConstantCase } from "./types/string-literals.js";
+
 // Pre-compiled regex patterns for better performance
 const CONST_ACRONYM = /([A-Z]+)([A-Z][a-z])/g;
 const CONST_LOWERCASE_UPPER = /([a-z0-9])([A-Z])/g;
@@ -15,8 +17,13 @@ const CONST_SPLIT = /\s+/;
  * constantCase('helloWorld') // 'HELLO_WORLD'
  * constantCase('hello-world') // 'HELLO_WORLD'
  * constantCase('__hello__world__') // 'HELLO_WORLD'
+ *
+ * // With template literal types
+ * const result = constantCase('helloWorld'); // type: "HELLO_WORLD"
  */
-export const constantCase = (str: string): string => {
+export function constantCase<T extends string>(str: T): ConstantCase<T>;
+export function constantCase(str: string): string;
+export function constantCase(str: string): string {
   if (!str) return str;
 
   // Handle camelCase/PascalCase by adding spaces before capitals
@@ -43,4 +50,4 @@ export const constantCase = (str: string): string => {
     .join("_");
 
   return result;
-};
+}