@sil/case

@sil/case

A comprehensive TypeScript library for converting strings between different case formats. This package provides utilities to transform strings into various naming conventions commonly used in programming, including camelCase, PascalCase, kebab-case, snake_case, and more.

Features

• 🚀 Zero dependencies
• 📦 Lightweight and performant
• 🔧 TypeScript support with full type definitions
• 🌐 Handles special characters with normalization support
• ⚡ Consistent and predictable transformations
• 🧪 Well tested

Installation

npm install @sil/case

Usage

import { kebabCase, camelCase, PascalCase, snakeCase } from "@sil/case";

const myString = "This Is My STRING";

console.log(kebabCase(myString));    // "this-is-my-string"
console.log(camelCase(myString));    // "thisIsMyString"
console.log(PascalCase(myString));   // "ThisIsMyString"
console.log(snakeCase(myString));    // "this_is_my_string"

API Reference

Core Conversion Functions

PascalCase(str: string, options?: Options): string

Converts a string to PascalCase (also known as UpperCamelCase). The first letter of each word is capitalized and spaces are removed.

PascalCase("hello world");        // "HelloWorld"
PascalCase("hello-world");        // "HelloWorld"
PascalCase("hello_world");        // "HelloWorld"
PascalCase("helloWorld");         // "HelloWorld"

Options:

• exclude: Array of characters to exclude from transformation

pascalCase(str: string, options?: Options): string

Alias for PascalCase function.

camelCase(str: string, options?: Options): string

Converts a string to camelCase. Similar to PascalCase but the first letter is lowercase.

camelCase("hello world");         // "helloWorld"
camelCase("Hello World");         // "helloWorld"
camelCase("hello-world");         // "helloWorld"
camelCase("HELLO_WORLD");         // "helloWorld"

Options:

• exclude: Array of characters to exclude from transformation

kebabCase(str: string): string

Converts a string to kebab-case (lowercase words separated by hyphens).

kebabCase("HelloWorld");          // "hello-world"
kebabCase("helloWorld");          // "hello-world"
kebabCase("hello world");         // "hello-world"
kebabCase("HELLO_WORLD");         // "hello-world"

snakeCase(str: string): string

Converts a string to snake_case (lowercase words separated by underscores).

snakeCase("HelloWorld");          // "hello_world"
snakeCase("helloWorld");          // "hello_world"
snakeCase("hello world");         // "hello_world"
snakeCase("hello-world");         // "hello_world"

upperSnakeCase(str: string): string

Converts a string to UPPER_SNAKE_CASE (uppercase words separated by underscores).

upperSnakeCase("HelloWorld");     // "HELLO_WORLD"
upperSnakeCase("helloWorld");     // "HELLO_WORLD"
upperSnakeCase("hello world");    // "HELLO_WORLD"
upperSnakeCase("hello-world");    // "HELLO_WORLD"

slugCase(str: string): string

Alias for kebabCase. Converts a string to slug format (lowercase with hyphens).

slugCase("Hello World!");         // "hello-world"
slugCase("HelloWorld");           // "hello-world"

constCase(str: string, startChar?: string): string

Converts a string to CONSTANT_CASE. Similar to upperSnakeCase but ensures the string doesn't start with a number. If it does, prepends a character (default: "_").

constCase("myVariable");          // "MY_VARIABLE"
constCase("my variable");         // "MY_VARIABLE"
constCase("123 variable");        // "_123_VARIABLE"
constCase("123 variable", "$");  // "$123_VARIABLE"

Parameters:

• startChar: Character to prepend if the string starts with a number (default: "_")

sentenceCase(str: string): string

Converts a string to sentence case (first letter capitalized, rest lowercase, with spaces).

sentenceCase("HELLO_WORLD");      // "Hello world"
sentenceCase("helloWorld");       // "Hello world"
sentenceCase("hello-world");      // "Hello world"
sentenceCase("HelloWorld");       // "Hello world"

Utility Functions

isUpperCase(char: string): boolean

Checks if a character is uppercase.

isUpperCase("A");                 // true
isUpperCase("a");                 // false
isUpperCase("1");                 // true (numbers are considered uppercase)

containsSpecialCharacters(str: string): boolean

Checks if a string contains any special characters (like accented letters).

containsSpecialCharacters("hello");    // false
containsSpecialCharacters("héllo");    // true
containsSpecialCharacters("café");     // true

normalize(str: string): string

Normalizes special characters to their ASCII equivalents. Useful for removing accents and diacritics.

normalize("café");                // "cafe"
normalize("naïve");               // "naive"
normalize("Zürich");              // "Zurich"
normalize("señor");               // "senor"

Helper Functions

camelToSnakeCase(str: string): string

Converts a camelCase string directly to snake_case.

camelToSnakeCase("helloWorld");   // "hello_world"
camelToSnakeCase("myVariableName"); // "my_variable_name"

camelToSlugCase(str: string): string

Converts a camelCase string directly to slug-case.

camelToSlugCase("helloWorld");    // "hello-world"
camelToSlugCase("myVariableName"); // "my-variable-name"

Special Characters Support

The library includes comprehensive support for special characters and diacritics, automatically converting them to their closest ASCII equivalents:

• à, á, ä, â → a
• è, é, ë, ê → e
• ì, í, ï, î → i
• ò, ó, ö, ô → o
• ù, ú, ü, û → u
• And many more...

Examples

Working with Different Input Formats

import * as Case from "@sil/case";

// From various formats to camelCase
Case.camelCase("user_name");           // "userName"
Case.camelCase("user-name");           // "userName"
Case.camelCase("UserName");            // "userName"
Case.camelCase("USER_NAME");           // "userName"
Case.camelCase("user name");           // "userName"

// Handling edge cases
Case.kebabCase("");                    // ""
Case.snakeCase("   ");                 // ""
Case.PascalCase("123abc");            // "123Abc"
Case.constCase("123abc");             // "_123_ABC"

// Working with special characters
Case.normalize("José García");         // "Jose Garcia"
Case.kebabCase("José García");         // "jose-garcia"
Case.snakeCase("Øystein Åse");        // "oystein_ase"

Real-World Use Cases

// Converting API responses to JavaScript conventions
const apiResponse = {
  user_name: "john_doe",
  created_at: "2023-01-01",
  is_active: true
};

const jsObject = Object.keys(apiResponse).reduce((acc, key) => {
  acc[Case.camelCase(key)] = apiResponse[key];
  return acc;
}, {});
// Result: { userName: "john_doe", createdAt: "2023-01-01", isActive: true }

// Creating CSS classes from JavaScript variables
const componentName = "MyCustomButton";
const cssClass = Case.kebabCase(componentName);  // "my-custom-button"

// Creating constant names
const eventName = "user clicked button";
const EVENT_CONSTANT = Case.constCase(eventName); // "USER_CLICKED_BUTTON"

// Creating readable headers from database fields
const dbField = "created_at_timestamp";
const headerText = Case.sentenceCase(dbField);    // "Created at timestamp"

TypeScript Support

The package includes full TypeScript definitions:

interface Options {
  exclude?: string[];
}

// All functions are fully typed
import { camelCase, PascalCase } from "@sil/case";

const result: string = camelCase("hello-world");
const withOptions: string = PascalCase("hello-world", { exclude: ["-"] });

Testing

The package includes comprehensive test coverage. To run tests:

npm test

For development with watch mode:

npm run dev:test

Building

To build the package:

npm run build

License

MIT © Sil van Diepen