### Install string-ts with npm

Source: https://github.com/gustavoguichard/string-ts/blob/main/SOW.md

Installs the string-ts library using npm. This command is used for project setup.

```bash
npm install string-ts
```

--------------------------------

### Pad String Start

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of `String.prototype.padStart`.

```typescript
import { padStart } from 'string-ts'

const str = 'hello'
const result = padStart(str, 10, '=')
//    ^ '=====hello'
```

--------------------------------

### Trim whitespace from start of string

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Use this function as a strongly-typed alternative to String.prototype.trimStart. It removes whitespace from the beginning of a string.

```typescript
import { trimStart } from 'string-ts'

const str = '  hello world  '
const result = trimStart(str)
//    ^ 'hello world  '
```

--------------------------------

### General string-ts Type Utilities

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Examples of various general-purpose string manipulation types provided by the 'string-ts' library.

```typescript
St.CharAt<'hello world', 6> // 'w'
St.Concat<['a', 'bc', 'def']> // 'abcdef'
St.EndsWith<'abc', 'c'> // true
St.Includes<'abcde', 'bcd'> // true
St.Join<['hello', 'world'], '-'> // 'hello-world'
St.Length<'hello'> // 5
St.PadEnd<'hello', 10, '='> // 'hello====='
St.PadStart<'hello', 10, '='> // '=====hello'
St.Repeat<'abc', 3> // 'abcabcabc'
St.Replace<'hello-world', 'l', '1'> // 'he1lo-world'
St.ReplaceAll<'hello-world', 'l', '1'> // 'he11o-wor1d'
St.Reverse<'Hello World!'> // '!dlroW olleH'
St.Slice<'hello-world', -5> // 'world'
St.Split<'hello-world', '-'> // ['hello', 'world']
St.Trim<' hello world '> // 'hello world'
St.StartsWith<'abc', 'a'> // true
St.TrimEnd<' hello world '> // ' hello world'
St.TrimStart<' hello world '> // 'hello world '
St.Truncate<'hello world', 9, '[...]'> // 'hello[...]'
St.Words<'hello-world'> // ['hello', 'world']
```

--------------------------------

### Check if string starts with prefix

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Use this function as a strongly-typed alternative to String.prototype.startsWith. It checks if a string begins with the characters of a specified string.

```typescript
import { startsWith } from 'string-ts'

const result = startsWith('abc', 'a')
//    ^ true
```

--------------------------------

### Get Character at Index

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of `String.prototype.charAt`.

```typescript
import { charAt } from 'string-ts'

const str = 'hello world'
const result = charAt(str, 6)
//    ^ 'w'
```

--------------------------------

### Check if string starts with a substring

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

The `startsWith` function returns a literal `true` or `false` type, indicating if a string begins with a specified substring. It supports an optional position argument to specify where the search should begin.

```typescript
import { startsWith } from 'string-ts'

const result1 = startsWith('hello world', 'hello')
//    ^? true

const result2 = startsWith('hello world', 'world')
//    ^? false

// With position
const result3 = startsWith('hello world', 'world', 6)
//    ^? true
```

```typescript
import type { StartsWith } from 'string-ts'
type Check = StartsWith<'/api/users', '/api'>
//   ^? true
```

--------------------------------

### Get String Length

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of `String.prototype.length`.

```typescript
import { length } from 'string-ts'

const str = 'hello'
const result = length(str)
//    ^ 5
```

--------------------------------

### padStart

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

This function is a strongly-typed counterpart of `String.prototype.padStart`.

```APIDOC
## padStart

### Description
Pads the current string with a given string (repeated, if necessary) so that the resulting string reaches a given length. The padding is applied from the start of the current string.

### Usage
```ts
import { padStart } from 'string-ts'

const str = 'hello'
const result = padStart(str, 10, '=')
// result will be '=====hello'
```
```

--------------------------------

### Build Project with tsup

Source: https://github.com/gustavoguichard/string-ts/blob/main/SOW.md

Bundles the project using tsup. This command is used to create distributable files.

```bash
npm run build
```

--------------------------------

### trimStart

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of String.prototype.trimStart, removing whitespace from the beginning of a string.

```APIDOC
## trimStart

### Description
This function is a strongly-typed counterpart of `String.prototype.trimStart`.

### Usage
```ts
import { trimStart } from 'string-ts'

const str = '  hello world  '
const result = trimStart(str)
//    ^ 'hello world  '
```
```

--------------------------------

### Run Tests with Vitest

Source: https://github.com/gustavoguichard/string-ts/blob/main/SOW.md

Executes the test suite for the project using Vitest. Ensure all tests pass before contributing.

```bash
npm test
```

--------------------------------

### startsWith

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterpart of String.prototype.startsWith. Returns a literal `true` or `false` type.

```APIDOC
## `startsWith`

Strongly-typed counterpart of `String.prototype.startsWith` — returns a literal `true` or `false` type.

```ts
import { startsWith } from 'string-ts'

const result1 = startsWith('hello world', 'hello')
//    ^? true

const result2 = startsWith('hello world', 'world')
//    ^? false

// With position
const result3 = startsWith('hello world', 'world', 6)
//    ^? true

// Type-level usage
import type { StartsWith } from 'string-ts'

type Check = StartsWith<'/api/users', '/api'>
//   ^? true
```
```

--------------------------------

### Get literal string length

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

The `length` function returns the exact numeric literal length of a string, providing type safety for string lengths.

```typescript
import { length } from 'string-ts'

const len = length('hello')
//    ^? 5

const len2 = length('hello world')
//    ^? 11
```

```typescript
import type { Length } from 'string-ts'
type L = Length<'typescript'>
//   ^? 10
```

--------------------------------

### string-ts Casing Type Utilities (Core)

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Demonstrates core string casing conversion types like CamelCase, KebabCase, PascalCase, etc.

```typescript
St.CamelCase<'hello-world'> // 'helloWorld'
St.ConstantCase<'helloWorld'> // 'HELLO_WORLD'
St.DelimiterCase<'hello world', '.'> // 'hello.world'
St.KebabCase<'helloWorld'> // 'hello-world'
St.PascalCase<'hello-world'> // 'HelloWorld'
St.SnakeCase<'helloWorld'> // 'hello_world'
St.TitleCase<'helloWorld'> // 'Hello World'
```

--------------------------------

### String Padding with padStart and padEnd

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Use padStart and padEnd for runtime string padding. They return exact literals for padding up to 45 characters, falling back to template literals for larger pads. Default padding character is a space.

```typescript
import { padStart, padEnd } from 'string-ts'

const ps = padStart('hello', 10, '=')
//    ^? '=====hello'

const pe = padEnd('hello', 10, '-')
//    ^? 'hello-----'

// Pad with default space
const spaced = padStart('42', 5)
//    ^? '   42'
```

```typescript
import type { PadStart, PadEnd } from 'string-ts'
type Padded = PadEnd<'ID', 6, '0'>
//   ^? 'ID0000'
```

--------------------------------

### trim / trimStart / trimEnd

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterparts of String.prototype.trim, trimStart, and trimEnd. Return the exact trimmed literal type.

```APIDOC
## `trim` / `trimStart` / `trimEnd`

Strongly-typed counterparts of `String.prototype.trim`, `trimStart`, and `trimEnd` — return the exact trimmed literal type.

```ts
import { trim, trimStart, trimEnd } from 'string-ts'

const trimmed = trim('  hello world  ')
//    ^? 'hello world'

const startTrimmed = trimStart('  hello world  ')
//    ^? 'hello world  '

const endTrimmed = trimEnd('  hello world  ')
//    ^? '  hello world'

// Type-level usage
import type { Trim, TrimStart, TrimEnd } from 'string-ts'

type T = Trim<'   padded   '>
//   ^? 'padded'
```
```

--------------------------------

### Check if string includes a substring

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

The `includes` function returns a literal boolean type (`true` or `false`) indicating if a string contains a specified substring. An optional position offset can be provided to start the search from a specific index.

```typescript
import { includes } from 'string-ts'

const result1 = includes('hello world', 'world')
//    ^? true

const result2 = includes('hello world', 'xyz')
//    ^? false

// With position offset
const result3 = includes('abcdef', 'abc', 2)
//    ^? false  (search starts at index 2)
```

```typescript
import type { Includes } from 'string-ts'
type HasFoo = Includes<'foobar', 'foo'>
//   ^? true
```

--------------------------------

### Transform snake_case API response to camelCase with deepCamelKeys

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Use `deepCamelKeys` to recursively convert all snake_case keys in an object to camelCase. This function preserves type information, allowing TypeScript to infer the resulting structure accurately. Ensure `string-ts` is installed and imported.

```typescript
import { deepCamelKeys } from 'string-ts'

// Simulated API response (snake_case from a REST API)
const apiResponse = {
  user_id: 42,
  full_name: 'Alice Smith',
  contact_info: {
    email_address: 'alice@example.com',
    phone_number: '+1-555-0100',
  },
  order_history: [
    { order_id: 1, total_price: 99.99 },
    { order_id: 2, total_price: 149.00 },
  ],
} as const

const user = deepCamelKeys(apiResponse)
//    ^? {
//         userId: 42,
//         fullName: 'Alice Smith',
//         contactInfo: { emailAddress: 'alice@example.com', phoneNumber: '+1-555-0100' },
//         orderHistory: { orderId: number, totalPrice: number }[]
//       }

// All keys are now camelCase with correct types
console.log(user.userId)
console.log(user.contactInfo.emailAddress)
console.log(user.orderHistory[0].totalPrice)
```

--------------------------------

### padEnd

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

This function is a strongly-typed counterpart of `String.prototype.padEnd`.

```APIDOC
## padEnd

### Description
Pads the current string with a given string (repeated, if necessary) so that the resulting string reaches a given length. The padding is applied from the end of the current string.

### Usage
```ts
import { padEnd } from 'string-ts'

const str = 'hello'
const result = padEnd(str, 10, '=')
// result will be 'hello====='
```
```

--------------------------------

### join

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

This function is a strongly-typed counterpart of `Array.prototype.join`.

```APIDOC
## join

### Description
Joins all elements of an array into a string.

### Usage
```ts
import { join } from 'string-ts'

const arr = ['hello', 'world']
const result = join(arr, ' ')
// result will be 'hello world'
```
```

--------------------------------

### Import string-ts Type Utilities

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Import all type utilities from the 'string-ts' library using an alias for convenience.

```typescript
import type * as St from 'string-ts'
```

--------------------------------

### Basic String Replacement (Runtime)

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Demonstrates the limitation of built-in string replace, which returns a loose 'string' type.

```typescript
const str = 'hello-world'
const result = str.replace('-', ' ') // you should use: as 'hello world'
//    ^? string
```

--------------------------------

### Casing type utilities - Core

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Core type utilities for converting strings between different casing conventions.

```APIDOC
## Casing type utilities

### Core

```ts
import type * as St from 'string-ts'

St.CamelCase<'hello-world'> // 'helloWorld'
St.ConstantCase<'helloWorld'> // 'HELLO_WORLD'
St.DelimiterCase<'hello world', '.'> // 'hello.world'
St.KebabCase<'helloWorld'> // 'hello-world'
St.PascalCase<'hello-world'> // 'HelloWorld'
St.SnakeCase<'helloWorld'> // 'hello_world'
St.TitleCase<'helloWorld'> // 'Hello World'
```
```

--------------------------------

### join

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterpart of `Array.prototype.join` — joins a tuple of literal strings with a delimiter and preserves the resulting literal type.

```APIDOC
## `join`

Strongly-typed counterpart of `Array.prototype.join` — joins a tuple of literal strings with a delimiter and preserves the resulting literal type.

```ts
import { join } from 'string-ts'

const parts = ['hello', 'world'] as const
const result = join(parts, '-')
//    ^? 'hello-world'

const path = join(['api', 'v2', 'users'], '/')
//    ^? 'api/v2/users'

const noDelim = join(['a', 'b', 'c'])
//    ^? 'abc'

// Type-level usage
import type { Join } from 'string-ts'
type Sentence = Join<['one', 'two', 'three'], ' '>
//   ^? 'one two three'
```
```

--------------------------------

### Pad String End

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of `String.prototype.padEnd`.

```typescript
import { padEnd } from 'string-ts'

const str = 'hello'
const result = padEnd(str, 10, '=')
//    ^ 'hello====='
```

--------------------------------

### Strongly-typed process.env Transformation

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Demonstrates converting environment variables from SCREAMING_SNAKE_CASE to camelCase with full type safety using `deepCamelKeys` and Zod for schema validation. This ensures type-correct access to environment variables.

```typescript
import { deepCamelKeys } from 'string-ts'
import z from 'zod'

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().url(),
  API_SECRET_KEY: z.string().min(32),
})

function getEnv() {
  const rawEnv = EnvSchema.parse(process.env)
  return deepCamelKeys(rawEnv)
  //     ^? { nodeEnv: 'development' | 'production' | 'test', databaseUrl: string, apiSecretKey: string }
}

const env = getEnv()
console.log(env.nodeEnv)       // 'development'
console.log(env.databaseUrl)   // 'postgresql://...'
// console.log(env.DATABASE_URL) // Error: Property 'DATABASE_URL' does not exist
```

--------------------------------

### Shallow object key transformation

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Utilities for transforming keys of shallow objects.

```APIDOC
## Casing type utilities

### Shallow object key transformation

```ts
import type * as St from 'string-ts'

St.CamelKeys<{ 'hello-world': { 'foo-bar': 'baz' } }>
// { helloWorld: { 'foo-bar': 'baz' } }
St.ConstantKeys<{ helloWorld: { fooBar: 'baz' } }>
// { 'HELLO_WORLD': { fooBar: 'baz' } }
St.DelimiterKeys<{ 'hello-world': { 'foo-bar': 'baz' } }, '.'>
// { 'hello.world': { 'foo-bar': 'baz' } }
St.KebabKeys<{ helloWorld: { fooBar: 'baz' } }>
// { 'hello-world': { fooBar: 'baz' } }
St.PascalKeys<{ 'hello-world': { 'foo-bar': 'baz' } }>
// { HelloWorld: { 'foo-bar': 'baz' } }
St.SnakeKeys<{ helloWorld: { fooBar: 'baz' } }>
// { 'hello_world': { fooBar: 'baz' } }
```
```

--------------------------------

### Custom LowerCase and UpperCase Types

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Shows how to define custom LowerCase and UpperCase types using existing string-ts utilities or runtime functions.

```typescript
type LowerCase<T extends string> = Lowercase<DelimiterCase<T, ' '>>
type UpperCase<T extends string> = Uppercase<DelimiterCase<T, ' '>>
```

```typescript
type LowerCase<T extends string> = ReturnType<typeof lowerCase<T>>
type UpperCase<T extends string> = ReturnType<typeof upperCase<T>>
```

--------------------------------

### General type utilities

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A collection of general-purpose string manipulation type utilities.

```APIDOC
## General type utilities from this library

```ts
import type * as St from 'string-ts'

St.CharAt<'hello world', 6> // 'w'
St.Concat<['a', 'bc', 'def']> // 'abcdef'
St.EndsWith<'abc', 'c'> // true
St.Includes<'abcde', 'bcd'> // true
St.Join<['hello', 'world'], '-'> // 'hello-world'
St.Length<'hello'> // 5
St.PadEnd<'hello', 10, '='> // 'hello====='
St.PadStart<'hello', 10, '='> // '=====hello'
St.Repeat<'abc', 3> // 'abcabcabc'
St.Replace<'hello-world', 'l', '1'> // 'he1lo-world'
St.ReplaceAll<'hello-world', 'l', '1'> // 'he11o-wor1d'
St.Reverse<'Hello World!'> // '!dlroW olleH'
St.Slice<'hello-world', -5> // 'world'
St.Split<'hello-world', '-'> // ['hello', 'world']
St.Trim<' hello world '> // 'hello world'
St.StartsWith<'abc', 'a'> // true
St.TrimEnd<' hello world '> // ' hello world'
St.TrimStart<' hello world '> // 'hello world '
St.Truncate<'hello world', 9, '[...]'> // 'hello[...]'
St.Words<'hello-world'> // ['hello', 'world']
```
```

--------------------------------

### kebabCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to kebab-case at both runtime and type levels.

```APIDOC
## kebabCase

### Description
This function converts a string to `kebab-case` at both runtime and type levels.

### Usage
```ts
import { kebabCase } from 'string-ts'

const str = 'helloWorld'
const result = kebabCase(str)
//    ^ 'hello-world'
```
```

--------------------------------

### Native TS String Type Utilities

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Demonstrates the usage of built-in TypeScript string manipulation types.

```typescript
Capitalize<'hello world'> // 'Hello world'
Lowercase<'HELLO WORLD'> // 'hello world'
Uppercase<'hello world'> // 'HELLO WORLD'
```

--------------------------------

### join: Strongly-typed array to string joining

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Join a tuple of literal strings with a delimiter using the join function, preserving the resulting literal type. Supports type-level usage.

```typescript
import { join } from 'string-ts'

const parts = ['hello', 'world'] as const
const result = join(parts, '-')
//    ^? 'hello-world'

const path = join(['api', 'v2', 'users'], '/')
//    ^? 'api/v2/users'

const noDelim = join(['a', 'b', 'c'])
//    ^? 'abc'

// Type-level usage
import type { Join } from 'string-ts'
type Sentence = Join<['one', 'two', 'three'], ' '>
//   ^? 'one two three'
```

--------------------------------

### Deep PascalCase Object Keys (Runtime)

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Recursively converts object keys to PascalCase at runtime. Ensure the 'string-ts' library is imported.

```typescript
import { deepPascalKeys } from 'string-ts'

const data = {
  'hello-world': {
    'foo-bar': 'baz',
  },
} as const
const result = deepPascalKeys(data)
//    ^ { HelloWorld: { FooBar: 'baz' } }
```

--------------------------------

### pascalCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to PascalCase at both runtime and type levels.

```APIDOC
## pascalCase

### Description
This function converts a string to `PascalCase` at both runtime and type levels.

### Usage
```ts
import { pascalCase } from 'string-ts'

const str = 'hello-world'
const result = pascalCase(str)
//    ^ 'HelloWorld'
```
```

--------------------------------

### titleCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to Title Case at both runtime and type levels.

```APIDOC
## titleCase

### Description
This function converts a string to `Title Case` at both runtime and type levels.

### Usage
```ts
import { titleCase } from 'string-ts'

const str = 'helloWorld'
const result = titleCase(str)
//    ^ 'Hello World'
```
```

--------------------------------

### split

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterpart of `String.prototype.split` — splits a literal string on a delimiter and returns a typed tuple.

```APIDOC
## `split`

Strongly-typed counterpart of `String.prototype.split` — splits a literal string on a delimiter and returns a typed tuple.

```ts
import { split } from 'string-ts'

const str = 'hello-world-foo' as const

const parts = split(str, '-')
//    ^? ['hello', 'world', 'foo']

const chars = split('abc')
//    ^? ['a', 'b', 'c']

// Useful for destructuring with full type safety
const [first, second] = split('foo:bar', ':')
//     ^? 'foo'          ^? 'bar'

// Type-level usage
import type { Split } from 'string-ts'
type Segments = Split<'a.b.c', '.'>
//   ^? ['a', 'b', 'c']
```
```

--------------------------------

### repeat

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

This function is a strongly-typed counterpart of `String.prototype.repeat`.

_Note: for counts above 45 the return type falls back to `string` to avoid TypeScript's type-instantiation depth limit. See [Known limitations](#known-limitations)._

```APIDOC
## repeat

### Description
Returns a new string which contains the specified number of copies of the string on which it was called, concatenated together.

### Usage
```ts
import { repeat } from 'string-ts'

const str = 'abc'
const result = repeat(str, 3)
// result will be 'abcabcabc'
```
```

--------------------------------

### Standard String Replace (TypeScript)

Source: https://github.com/gustavoguichard/string-ts/blob/main/SOW.md

Demonstrates how standard JavaScript string replace can widen literal types. Use string-ts for type preservation.

```typescript
const str = 'hello-world'
const result = str.replace('-', ' ')
//    ^? string
```

--------------------------------

### includes

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterpart of String.prototype.includes. Returns `true` or `false` as a literal boolean type.

```APIDOC
## `includes`

Strongly-typed counterpart of `String.prototype.includes` — returns `true` or `false` as a literal boolean type.

```ts
import { includes } from 'string-ts'

const result1 = includes('hello world', 'world')
//    ^? true

const result2 = includes('hello world', 'xyz')
//    ^? false

// With position offset
const result3 = includes('abcdef', 'abc', 2)
//    ^? false  (search starts at index 2)

// Type-level usage
import type { Includes } from 'string-ts'

type HasFoo = Includes<'foobar', 'foo'>
//   ^? true
```
```

--------------------------------

### trim

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of String.prototype.trim, removing whitespace from both ends of a string.

```APIDOC
## trim

### Description
This function is a strongly-typed counterpart of `String.prototype.trim`.

### Usage
```ts
import { trim } from 'string-ts'

const str = '  hello world  '
const result = trim(str)
//    ^ 'hello world'
```
```

--------------------------------

### Trim whitespace from strings

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Provides type-safe `trim`, `trimStart`, and `trimEnd` functions that return the exact trimmed literal type. These functions remove whitespace from the beginning, end, or both sides of a string.

```typescript
import { trim, trimStart, trimEnd } from 'string-ts'

const trimmed = trim('  hello world  ')
//    ^? 'hello world'

const startTrimmed = trimStart('  hello world  ')
//    ^? 'hello world  '

const endTrimmed = trimEnd('  hello world  ')
//    ^? '  hello world'
```

```typescript
import type { Trim, TrimStart, TrimEnd } from 'string-ts'
type T = Trim<'   padded   '>
//   ^? 'padded'
```

--------------------------------

### Join Array Elements into String

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of `Array.prototype.join`.

```typescript
import { join } from 'string-ts'

const str = ['hello', 'world']
const result = join(str, ' ')
//    ^ 'hello world'
```

--------------------------------

### trimEnd

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of String.prototype.trimEnd, removing whitespace from the end of a string.

```APIDOC
## trimEnd

### Description
This function is a strongly-typed counterpart of `String.prototype.trimEnd`.

### Usage
```ts
import { trimEnd } from 'string-ts'

const str = '  hello world  '
const result = trimEnd(str)
//    ^ '  hello world'
```
```

--------------------------------

### Convert Object Keys to kebab-case

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Shallowly converts object keys to kebab-case at runtime and type level. Useful for CSS or URL-friendly keys.

```typescript
import { kebabKeys } from 'string-ts'

const data = {
  helloWorld: {
    fooBar: 'baz',
  },
} as const
const result = kebabKeys(data)
//    ^ { 'hello-world': { fooBar: 'baz' } }
```

--------------------------------

### replace

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of String.prototype.replace. Note: Partial Regex support may result in loose typing.

```APIDOC
## replace

### Description
This function is a strongly-typed counterpart of `String.prototype.replace`.

_Warning: this is a partial implementation, as we don't fully support Regex. Using a RegExp lookup will result in a loose typing._

### Usage
```ts
import { replace } from 'string-ts'

const str = 'hello-world-'
const result = replace(str, '-', ' ')
//    ^ 'hello world-'
const looselyTypedResult = replace(str, /-/, ' ')
//    ^ string
```
```

--------------------------------

### toLowerCase / toUpperCase

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterparts of the native case methods. Return `Lowercase<T>` and `Uppercase<T>` respectively.

```APIDOC
## `toLowerCase` / `toUpperCase`

Strongly-typed counterparts of the native case methods — return `Lowercase<T>` and `Uppercase<T>` respectively.

```ts
import { toLowerCase, toUpperCase } from 'string-ts'

const lower = toLowerCase('Hello WORLD')
//    ^? 'hello world'

const upper = toUpperCase('Hello World')
//    ^? 'HELLO WORLD'

// Useful for literal key normalization
function normalize<T extends string>(key: T): Lowercase<T> {
  return toLowerCase(key)
}
const k = normalize('USER_ID')
//    ^? 'user_id'
```
```

--------------------------------

### Deep Object Key Transformation (Runtime)

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Recursively transforms object keys at runtime using a provided transformation function. Imports 'deepTransformKeys' and a transformation function like 'toUpperCase'.

```typescript
import { deepTransformKeys, toUpperCase } from 'string-ts'

const data = { helloWorld: 'baz' } as const

type MyType<T> = { [K in keyof T as Uppercase<K>]: T[K] }
const result = deepTransformKeys(data, toUpperCase) as MyType<typeof data>
//    ^ { 'HELLOWORLD': 'baz' }
```

--------------------------------

### Convert string to Title Case

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to Title Case at both runtime and type levels.

```typescript
import { titleCase } from 'string-ts'

const str = 'helloWorld'
const result = titleCase(str)
//    ^ 'Hello World'
```

--------------------------------

### deepPascalKeys

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Recursively converts the keys of an object to PascalCase at both runtime and type levels.

```APIDOC
## deepPascalKeys

### Description
This function recursively converts the keys of an object to `PascalCase` at both runtime and type levels.

### Usage
```ts
import { deepPascalKeys } from 'string-ts'

const data = {
  'hello-world': {
    'foo-bar': 'baz',
  },
} as const
const result = deepPascalKeys(data)
//    ^ { HelloWorld: { FooBar: 'baz' } }
```
```

--------------------------------

### Deep Key Transformation (Camel, Snake, Kebab, Pascal, Constant, Delimiter)

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Recursively transforms all keys in nested objects and arrays of objects to a specified case style, including type-level transformation. Ensure the correct function is imported for the desired case style.

```typescript
import { deepCamelKeys, deepSnakeKeys, deepKebabKeys, deepPascalKeys, deepConstantKeys, deepDelimiterKeys } from 'string-ts'

const apiResponse = {
  'user-id': 1,
  'user-name': 'Alice',
  'address-info': {
    'street-name': 'Main St',
    'zip-code': '12345',
  },
} as const

deepCamelKeys(apiResponse)
// ^? { userId: 1, userName: 'Alice', addressInfo: { streetName: 'Main St', zipCode: '12345' } }

deepSnakeKeys(apiResponse)
// ^? { user_id: 1, user_name: 'Alice', address_info: { street_name: 'Main St', zip_code: '12345' } }

deepKebabKeys({ userId: 1, addressInfo: { zipCode: '12345' } } as const)
// ^? { 'user-id': 1, 'address-info': { 'zip-code': '12345' } }

deepPascalKeys(apiResponse)
// ^? { UserId: 1, UserName: 'Alice', AddressInfo: { StreetName: 'Main St', ZipCode: '12345' } }

deepConstantKeys({ fooBar: { bazQux: true } } as const)
// ^? { FOO_BAR: { BAZ_QUX: true } }

deepDelimiterKeys(apiResponse, '.')
// ^? { 'user.id': 1, 'user.name': 'Alice', 'address.info': { 'street.name': 'Main St', 'zip.code': '12345' } }
```

--------------------------------

### Convert string to PascalCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to PascalCase at both runtime and type levels.

```typescript
import { pascalCase } from 'string-ts'

const str = 'hello-world'
const result = pascalCase(str)
//    ^ 'HelloWorld'
```

--------------------------------

### Convert String to Upper Case with Word Splitting (Runtime)

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Use `upperCase` to split words, join them with a space, and then convert to upper case. This differs from `toUpperCase` by splitting words first.

```typescript
import { upperCase } from 'string-ts'

upperCase('hello-world')
//        ^? 'HELLO WORLD'

upperCase('helloWorld')
//        ^? 'HELLO WORLD'

upperCase('my_constant_val')
//        ^? 'MY CONSTANT VAL'
```

--------------------------------

### constantCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to CONSTANT_CASE at both runtime and type levels.

```APIDOC
## constantCase

### Description
This function converts a string to `CONSTANT_CASE` at both runtime and type levels.

### Usage
```ts
import { constantCase } from 'string-ts'

const str = 'helloWorld'
const result = constantCase(str)
//    ^ 'HELLO_WORLD'
```
```

--------------------------------

### Convert string to kebab-case

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to kebab-case at both runtime and type levels.

```typescript
import { kebabCase } from 'string-ts'

const str = 'helloWorld'
const result = kebabCase(str)
//    ^ 'hello-world'
```

--------------------------------

### Convert String to Title Case (Runtime & Type)

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Use `titleCase` to capitalize each word in a string and join them with spaces. Supports type-level conversion.

```typescript
import { titleCase } from 'string-ts'

titleCase('hello-world')
//        ^? 'Hello World'

titleCase('hello_world_foo')
//        ^? 'Hello World Foo'

titleCase('myPageTitle')
//        ^? 'My Page Title'

// Type-level usage
import type { TitleCase } from 'string-ts'
type Label = TitleCase<'user-profile-settings'>
//   ^? 'User Profile Settings'
```

--------------------------------

### Deep Camel Case Conversion

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Compares loose vs. precise type handling for environment variable keys using lodash-es and string-ts's deepCamelKeys.

```typescript
import { deepCamelKeys } from 'string-ts'
import { camelCase, mapKeys } from 'lodash-es'
import z from 'zod'

const EnvSchema = z.object({
  NODE_ENV: z.string(),
})

function getEnvLoose() {
  const rawEnv = EnvSchema.parse(process.env)
  const env = mapKeys(rawEnv, (_v, k) => camelCase(k))
  //    ^? Dictionary<string>

  // `Dictionary<string>` is too loose
  // TypeScript is okay with this, 'abc' is expected to be of type `string`
  // This will have unexpected behavior at runtime
  console.log(env.abc)
}

function getEnvPrecise() {
  const rawEnv = EnvSchema.parse(process.env)
  const env = deepCamelKeys(rawEnv)
  //    ^? { nodeEnv: string }

  // Error: Property 'abc' does not exist on type '{ nodeEnv: string; }'
  // Our type is more specific, so TypeScript catches this error.
  // This mistake will be caught at compile time
  console.log(env.abc)
}

function main() {
  getEnvLoose()
  getEnvPrecise()
}

main()
```

--------------------------------

### Native String Method Overrides

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Applies strongly-typed versions of native string methods project-wide by importing 'string-ts/native'. Supports methods like replace, charAt, startsWith, and split.

```typescript
import 'string-ts/native'

const str = 'hello-world' as const

str.replace('-', '_')
//  ^? 'hello_world'

str.charAt(6)
//  ^? 'w'

str.startsWith('hello')
//  ^? true

str.split('-')
//  ^? ['hello', 'world']
```

--------------------------------

### camelCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to camelCase at both runtime and type levels.

```APIDOC
## camelCase

### Description
This function converts a string to `camelCase` at both runtime and type levels.

### Usage
```ts
import { camelCase } from 'string-ts'

const str = 'hello-world'
const result = camelCase(str)
//    ^ 'helloWorld'
```
```

--------------------------------

### Convert String to Lower Case with Word Splitting (Runtime)

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Use `lowerCase` to split words, join them with a space, and then convert to lower case. This differs from `toLowerCase` by splitting words first.

```typescript
import { lowerCase } from 'string-ts'

lowerCase('HELLO-WORLD')
//        ^? 'hello world'

lowerCase('helloWorld')
//        ^? 'hello world'

lowerCase('MY_CONSTANT')
//        ^? 'my constant'
```

--------------------------------

### Other exported type utilities

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Miscellaneous type utilities for character and string property checks.

```APIDOC
## Other exported type utilities

```ts
import type * as St from 'string-ts'

St.IsDigit<'a'> // false
St.IsDigit<'1'> // true
St.IsLetter<'a'> // true
St.IsLetter<'1'> // false
St.IsLower<'a'> // true
St.IsLower<'A'> // false
St.IsUpper<'a'> // false
St.IsUpper<'A'> // true
St.IsSeparator<' '> // true
St.IsSeparator<'-'> // true
St.IsSeparator<'a'> // false
St.IsSpecial<'a'> // false
St.IsSpecial<'!'> // true
St.IsSpecial<' '> // false
```
```

--------------------------------

### Convert Object Keys to PascalCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Shallowly converts object keys to PascalCase at runtime and type level. Often used for component props or class names.

```typescript
import { pascalKeys } from 'string-ts'

const data = {
  'hello-world': {
    'foo-bar': 'baz',
  },
} as const
const result = pascalKeys(data)
//    ^ { HelloWorld: { FooBar: 'baz' } }
```

--------------------------------

### Reverse String (Runtime & Type)

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Use `reverse` to reverse a string. Available for both runtime and type-level operations.

```typescript
import { reverse } from 'string-ts'

reverse('hello')
//      ^? 'olleh'

reverse('Hello StringTS!')
//      ^? '!STgnirtS olleH'

// Type-level usage
import type { Reverse } from 'string-ts'
type Rev = Reverse<'abcde'>
//   ^? 'edcba'
```

--------------------------------

### Native TS type utilities

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Provides basic string manipulation types directly available in TypeScript.

```APIDOC
## Native TS type utilities

```ts
Capitalize<'hello world'> // 'Hello world'
Lowercase<'HELLO WORLD'> // 'hello world'
Uppercase<'hello world'> // 'HELLO WORLD'
```
```

--------------------------------

### Typed String Replace (string-ts)

Source: https://github.com/gustavoguichard/string-ts/blob/main/SOW.md

Shows how string-ts's replace function preserves literal types. Import 'replace' from 'string-ts' to use.

```typescript
import { replace } from 'string-ts'
const str = 'hello-world'
const result = replace(str, '-', ' ')
//    ^ 'hello world'
```

--------------------------------

### lowerCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to lower case at both runtime and type levels. Splits by words and joins them with a space.

```APIDOC
## lowerCase

### Description
This function converts a string to `lower case` at both runtime and type levels.
_NOTE: this function will split by words and join them with `" "`, unlike `toLowerCase`._

### Usage
```ts
import { lowerCase } from 'string-ts'

const str = 'HELLO-WORLD'
const result = lowerCase(str)
//    ^ 'hello world'
```
```

--------------------------------

### slice

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterpart of `String.prototype.slice` — supports positive and negative indices, and preserves the resulting literal.

```APIDOC
## `slice`

Strongly-typed counterpart of `String.prototype.slice` — supports positive and negative indices, and preserves the resulting literal.

```ts
import { slice } from 'string-ts'

const str = 'hello-world' as const

const fromSix = slice(str, 6)
//    ^? 'world'

const sub = slice(str, 1, 5)
//    ^? 'ello'

const negative = slice(str, -5)
//    ^? 'world'

// Type-level usage
import type { Slice } from 'string-ts'
type Last4 = Slice<'typescript', -4>
//   ^? 'ipt' — note: resolves to literal based on input length
```
```

--------------------------------

### Deep snake_case Object Keys (Runtime)

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Recursively converts object keys to snake_case at runtime. Ensure the 'string-ts' library is imported.

```typescript
import { deepSnakeKeys } from 'string-ts'

const data = {
  helloWorld: {
    fooBar: 'baz',
  },
} as const
const result = deepSnakeKeys(data)
//    ^ { 'hello_world': { 'foo_bar': 'baz' } }
```

--------------------------------

### snakeCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Converts a string to snake_case at both runtime and type levels.

```APIDOC
## snakeCase

### Description
This function converts a string to `snake_case` at both runtime and type levels.

### Usage
```ts
import { snakeCase } from 'string-ts'

const str = 'helloWorld'
const result = snakeCase(str)
//    ^ 'hello_world'
```
```

--------------------------------

### Deep object key transformation

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Utilities for recursively transforming keys of nested objects.

```APIDOC
## Casing type utilities

### Deep object key transformation

```ts
import type * as St from 'string-ts'

St.DeepCamelKeys<{
  'hello-world': { 'foo-bar': 'baz' }
}> // { helloWorld: { fooBar: 'baz' } }
St.DeepConstantKeys<{
  helloWorld: { fooBar: 'baz' }
}> // { 'HELLO_WORLD': { 'FOO_BAR': 'baz' } }
St.DeepDelimiterKeys<
  {
    'hello-world': { 'foo-bar': 'baz' }
  },
  '.'
> // { 'hello.world': { 'foo.bar': 'baz' } }
St.DeepKebabKeys<{
  helloWorld: { fooBar: 'baz' }
}> // { 'hello-world': { 'foo-bar': 'baz' } }
St.DeepPascalKeys<{
  'hello-world': { 'foo-bar': 'baz' }
}> // { HelloWorld: { FooBar: 'baz' } }
St.DeepSnakeKeys<{
  helloWorld: { fooBar: 'baz' }
}> // { 'hello_world': { 'foo_bar': 'baz' } }
```
```

--------------------------------

### Native String Method Overrides

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Importing 'string-ts/native' globally patches String.prototype type declarations to return strongly-typed literal results instead of 'string', without any runtime cost.

```APIDOC
## Native String Method Overrides (`string-ts/native`)

A single import that globally patches `String.prototype` type declarations to return strongly-typed literal results instead of `string`, without any runtime cost.

```ts
// Add once to your project entry point or a .d.ts file
import 'string-ts/native'

const str = 'hello-world' as const

const char = str.charAt(6)
//    ^? 'w'

const replaced = str.replace('-', '_')
//    ^? 'hello_world'

const split = str.split('-')
//    ^? ['hello', 'world']

const upper = str.toUpperCase()
//    ^? 'HELLO-WORLD'

const starts = str.startsWith('hello')
//    ^? true

// Array.prototype.join is also typed
const parts = ['foo', 'bar', 'baz'] as const
const joined = parts.join('-')
//    ^? 'foo-bar-baz'
```
```

--------------------------------

### concat

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterpart of `String.prototype.concat` — concatenates multiple literal strings and preserves the resulting literal type.

```APIDOC
## `concat`

Strongly-typed counterpart of `String.prototype.concat` — concatenates multiple literal strings and preserves the resulting literal type.

```ts
import { concat } from 'string-ts'

const result = concat('Hello', ', ', 'World', '!')
//    ^? 'Hello, World!'

const base = 'foo' as const
const built = concat(base, '-bar', '-baz')
//    ^? 'foo-bar-baz'

// Type-level usage
import type { Concat } from 'string-ts'
type Full = Concat<['api', '/', 'v1', '/', 'users']>
//   ^? 'api/v1/users'
```
```

--------------------------------

### toUpperCase

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

A strongly-typed counterpart of String.prototype.toUpperCase, converting the calling string value to upper case.

```APIDOC
## toUpperCase

### Description
This function is a strongly-typed counterpart of `String.prototype.toUpperCase`.

### Usage
```ts
import { toUpperCase } from 'string-ts'

const str = 'hello world'
const result = toUpperCase(str)
//    ^ 'HELLO WORLD'
```
```

--------------------------------

### length

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

Strongly-typed counterpart of String.prototype.length. Returns the exact numeric literal length of a string.

```APIDOC
## `length`

Strongly-typed counterpart of `String.prototype.length` — returns the exact numeric literal length of a string.

```ts
import { length } from 'string-ts'

const len = length('hello')
//    ^? 5

const len2 = length('hello world')
//    ^? 11

// Type-level usage
import type { Length } from 'string-ts'

type L = Length<'typescript'>
//   ^? 10
```
```

--------------------------------

### deepTransformKeys

Source: https://github.com/gustavoguichard/string-ts/blob/main/README.md

Recursively converts the keys of an object to a custom format at runtime.

```APIDOC
## Runtime-only utilities

### deepTransformKeys

This function recursively converts the keys of an object to a custom format, but only at runtime level.

```ts
import { deepTransformKeys, toUpperCase } from 'string-ts'

const data = { helloWorld: 'baz' } as const

type MyType<T> = { [K in keyof T as Uppercase<K>]: T[K] }
const result = deepTransformKeys(data, toUpperCase) as MyType<typeof data>
//    ^ { 'HELLOWORLD': 'baz' }
```
```

--------------------------------

### Converting Strings to kebab-case

Source: https://context7.com/gustavoguichard/string-ts/llms.txt

The kebabCase function converts strings to kebab-case, supporting various input formats including camelCase, PascalCase, and snake_case. This is useful for CSS class names or URL slugs. It also supports type-level usage.

```typescript
import { kebabCase } from 'string-ts'

kebabCase('helloWorld')
//        ^? 'hello-world'

kebabCase('Hello World Foo')
//        ^? 'hello-world-foo'

kebabCase('MY_CONSTANT')
//        ^? 'my-constant'

// Useful for CSS class names or URL slugs
const cssClass = kebabCase('backgroundColor')
//               ^? 'background-color'
```

```typescript
import type { KebabCase } from 'string-ts'
type Slug = KebabCase<'UserProfile'>
//   ^? 'user-profile'
```