string-ts

Strongly typed string functions

StringUtils
gustavoguichard/string-tsstring-ts

README

string-ts


Strongly-typed string functions for all!

A demonstration of string-ts

😬 The problem


When you are working with literal strings, the string manipulation functions only work at the runtime level and the types don't follow those transformations.
You end up losing type information and possibly having to cast the result.

  1. ```ts
  2. const str = 'hello-world'
  3. const result = str.replace('-', ' ') // you should use: as 'hello world'
  4. //    ^? string
  5. ```

🤓 The solution


This library aims to solve this problem by providing a set of common functions that work with literal strings at both type and runtime level.

  1. ```ts
  2. import { replace } from 'string-ts'

  4. const str = 'hello-world'
  5. const result = replace(str, '-', ' ')
  6. //    ^ 'hello world'
  7. ```

🔍 Why this matters


TypeScript yields the best static analysis when types are highly specific.
Literals are more specific than type string.
This library preserves literals (and unions of literals) after transformations, unlike most existing utility libraries (and built-in string methods.)

In-depth example


In the below example, I want to get a strongly-typed, camel-case version of process.env.
One flow results in a loose type, and the other results in a more precise type.
This example should illustrate the highly-specific and flexible nature of string-ts.

  1. ```ts
  2. import { deepCamelKeys } from 'string-ts'
  3. import { camelCase, mapKeys } from 'lodash-es'
  4. import z from 'zod'

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

  10. function getEnvLoose() {
  11.   const rawEnv = EnvSchema.parse(process.env)
  12.   const env = mapKeys(rawEnv, (_v, k) => camelCase(k))
  13.   //    ^? Dictionary

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

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

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

  32. function main() {
  33.   getEnvLoose()
  34.   getEnvPrecise()
  35. }

  37. main()
  38. ```

📦 Installation


  1. ```bash
  2. npm install string-ts
  3. ```

🌳 Tree shaking


string-ts has been designed with tree shaking in mind.
We have tested it with build tools like Webpack, Vite, Rollup, etc.

👌 Supported TypeScript versions


string-ts currently only works on TypeScript v5+.

It also only work with common ASCII characters characters. We don't plan to support international characters or emojis.


📖 API


- Runtime counterparts of native type utilities
  - capitalize
  - uncapitalize
- Strongly-typed alternatives to native runtime utilities
  - charAt
  - concat
  - endsWith
  - includes
  - join
  - length
  - padEnd
  - padStart
  - repeat
  - replace
  - replaceAll
  - slice
  - split
  - startsWith
  - toLowerCase
  - toUpperCase
  - trim
  - trimEnd
  - trimStart
- Strongly-typed alternatives to common loosely-typed functions
  - camelCase
  - constantCase
  - delimiterCase
  - kebabCase
  - pascalCase
  - reverse
  - snakeCase
  - titleCase
  - truncate
  - words
- Strongly-typed shallow transformation of objects
  - camelKeys
  - constantKeys
  - delimiterKeys
  - kebabKeys
  - pascalKeys
  - snakeKeys
- Strongly-typed deep transformation of objects
  - deepCamelKeys
  - deepConstantKeys
  - deepDelimiterKeys
  - deepKebabKeys
  - deepPascalKeys
  - deepSnakeKeys
- Type Utilities
  - Native TS type utilities
  - General Type utilities from this library
  - Casing type utilities
  - Other exported type utilities
- Runtime-only utilities
  - deepTransformKeys


Runtime counterparts of native type utilities


capitalize


Capitalizes the first letter of a string. This is a runtime counterpart of `Capitalize` from `src/types.d.ts`.

  1. ```ts
  2. import { capitalize } from 'string-ts'

  4. const str = 'hello world'
  5. const result = capitalize(str)
  6. //    ^ 'Hello world'
  7. ```

uncapitalize


Uncapitalizes the first letter of a string. This is a runtime counterpart of `Uncapitalize` from `src/types.d.ts`.

  1. ```ts
  2. import { uncapitalize } from 'string-ts'

  4. const str = 'Hello world'
  5. const result = uncapitalize(str)
  6. //    ^ 'hello world'
  7. ```

Strongly-typed alternatives to native runtime utilities


charAt


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

  1. ```ts
  2. import { charAt } from 'string-ts'

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

concat


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

  1. ```ts
  2. import { concat } from 'string-ts'

  4. const result = concat('a', 'bc', 'def')
  5. //    ^ 'abcdef'
  6. ```

endsWith


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

  1. ```ts
  2. import { endsWith } from 'string-ts'

  4. const result = endsWith('abc', 'c')
  5. //    ^ true
  6. ```

includes


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

  1. ```ts
  2. import { includes } from 'string-ts'

  4. const result = includes('abcde', 'bcd')
  5. //    ^ true
  6. ```

join


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

  1. ```ts
  2. import { join } from 'string-ts'

  4. const str = ['hello', 'world']
  5. const result = join(str, ' ')
  6. //    ^ 'hello world'
  7. ```

length


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

  1. ```ts
  2. import { length } from 'string-ts'

  4. const str = 'hello'
  5. const result = length(str)
  6. //    ^ 5
  7. ```

padEnd


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

  1. ```ts
  2. import { padEnd } from 'string-ts'

  4. const str = 'hello'
  5. const result = padEnd(str, 10, '=')
  6. //    ^ 'hello====='
  7. ```

padStart


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

  1. ```ts
  2. import { padStart } from 'string-ts'

  4. const str = 'hello'
  5. const result = padStart(str, 10, '=')
  6. //    ^ '=====hello'
  7. ```

repeat


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

  1. ```ts
  2. import { repeat } from 'string-ts'

  4. const str = 'abc'
  5. const result = repeat(str, 3)
  6. //    ^ 'abcabcabc'
  7. ```

replace


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._

  1. ```ts
  2. import { replace } from 'string-ts'

  4. const str = 'hello-world-'
  5. const result = replace(str, '-', ' ')
  6. //    ^ 'hello world-'
  7. const looselyTypedResult = replace(str, /-/, ' ')
  8. //    ^ string
  9. ```

replaceAll


This function is a strongly-typed counterpart of String.prototype.replaceAll.
It also has a polyfill for runtimes older than ES2021.

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

  1. ```ts
  2. import { replaceAll } from 'string-ts'

  4. const str = 'hello-world-'
  5. const result = replaceAll(str, '-', ' ')
  6. //    ^ 'hello world '
  7. const looselyTypedResult = replaceAll(str, /-/g, ' ')
  8. //    ^ string
  9. ```

slice


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

  1. ```ts
  2. import { slice } from 'string-ts'

  4. const str = 'hello-world'
  5. const result = slice(str, 6)
  6. //    ^ 'world'
  7. const result2 = slice(str, 1, 5)
  8. //    ^ 'ello'
  9. const result3 = slice(str, -5)
  10. //    ^ 'world'
  11. ```

split


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

  1. ```ts
  2. import { split } from 'string-ts'

  4. const str = 'hello-world'
  5. const result = split(str, '-')
  6. //    ^ ['hello', 'world']
  7. ```

startsWith


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

  1. ```ts
  2. import { startsWith } from 'string-ts'

  4. const result = startsWith('abc', 'a')
  5. //    ^ true
  6. ```

toLowerCase


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

  1. ```ts
  2. import { toLowerCase } from 'string-ts'

  4. const str = 'HELLO WORLD'
  5. const result = toLowerCase(str)
  6. //    ^ 'hello world'
  7. ```

toUpperCase


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

  1. ```ts
  2. import { toUpperCase } from 'string-ts'

  4. const str = 'hello world'
  5. const result = toUpperCase(str)
  6. //    ^ 'HELLO WORLD'
  7. ```

trim


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

  1. ```ts
  2. import { trim } from 'string-ts'

  4. const str = '  hello world  '
  5. const result = trim(str)
  6. //    ^ 'hello world'
  7. ```