# @sil/case

> Convert cases

Latest version **1.0.0** (published 2025-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @sil/case
pnpm add @sil/case
yarn add @sil/case
bun add @sil/case
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2025-09-11 |
| First published | 2022-07-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 78 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Sil van Diepen |
| Maintainers | hacobvandipyan, silvandiepen |
| Keywords | Convert, cases |

## Links

- npm: https://www.npmjs.com/package/@sil/case
- npm.io page: https://npm.io/package/@sil/case

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 1.0.0 (latest) — 2025-09-11
- 0.3.1 — 2024-07-05
- 0.3.0 — 2024-07-05
- 0.2.0 — 2024-04-02
- 0.1.0 — 2023-05-10
- 0.0.5 — 2022-12-26
- 0.0.4 — 2022-12-26
- 0.0.3 — 2022-08-09
- 0.0.2 — 2022-08-05
- 0.0.1 — 2022-07-15

## README

# @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

```bash
npm install @sil/case
```

## Usage

```js
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.

```js
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.

```js
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).

```js
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).

```js
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).

```js
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).

```js
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: "_").

```js
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).

```js
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.

```js
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).

```js
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.

```js
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.

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

#### `camelToSlugCase(str: string): string`
Converts a camelCase string directly to slug-case.

```js
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

```js
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

```js
// 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:

```typescript
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:

```bash
npm test
```

For development with watch mode:

```bash
npm run dev:test
```

## Building

To build the package:

```bash
npm run build
```

## License

MIT © Sil van Diepen

---
_Source: https://npm.io/package/@sil/case · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._