diff --git a/README.md b/README.md index bbeb70b..f6f2cd3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Strongly-typed string functions for all! -![A demonstration of string-ts](https://github.com/gustavoguichard/string-ts/assets/566971/0aa5603f-871d-4eb7-8ace-6a73466cec4d) +![A demonstration of string-ts](https://github.com/gustavoguichard/string-ts/assets/566971/0aa5603f-871d-4eb7-8ace-6a73466cec4d) ## 😬 The problem @@ -87,39 +87,39 @@ npm install string-ts - [Runtime counterparts of native type utilities](#runtime-counterparts-of-native-type-utilities) - [capitalize](#capitalize) - [Strongly-typed alternatives to native runtime utilities](#strongly-typed-alternatives-to-native-runtime-utilities) - - [toUpperCase](#touppercase) - - [toLowerCase](#tolowercase) - - [trim](#trim) - - [trimStart](#trimstart) - - [trimEnd](#trimend) - [chartAt](#charat) - [join](#join) - [replace](#replace) - [replaceAll](#replaceall) - [split](#split) + - [toLowerCase](#tolowercase) + - [toUpperCase](#touppercase) + - [trim](#trim) + - [trimEnd](#trimend) + - [trimStart](#trimstart) - [Strongly-typed alternatives to common loosely-typed functions](#strongly-typed-alternatives-to-common-loosely-typed-functions) - - [words](#words) - - [toDelimiterCase](#todelimitercase) - [toCamelCase](#tocamelcase) - - [toPascalCase](#topascalcase) + - [toConstantCase](#toconstantcase) + - [toDelimiterCase](#todelimitercase) - [toKebabCase](#tokebabcase) + - [toPascalCase](#topascalcase) - [toSnakeCase](#tosnakecase) - - [toConstantCase](#toconstantcase) - [toTitleCase](#totitlecase) + - [words](#words) - [Strongly-typed shallow transformation of objects](#strongly-typed-shallow-transformation-of-objects) - - [DelimiterKeys](#delimiterkeys) - [CamelKeys](#camelkeys) - - [PascalKeys](#pascalkeys) + - [ConstantKeys](#constantkeys) + - [DelimiterKeys](#delimiterkeys) - [KebabKeys](#kebabkeys) + - [PascalKeys](#pascalkeys) - [SnakeKeys](#snakekeys) - - [ConstantKeys](#constantkeys) - [Strongly-typed deep transformation of objects](#strongly-typed-deep-transformation-of-objects) - - [deepDelimiterKeys](#deepdelimiterkeys) - [deepCamelKeys](#deepcamelkeys) - - [deepPascalKeys](#deeppascalkeys) + - [deepConstantKeys](#deepconstantkeys) + - [deepDelimiterKeys](#deepdelimiterkeys) - [deepKebabKeys](#deepkebabkeys) + - [deepPascalKeys](#deeppascalkeys) - [deepSnakeKeys](#deepsnakekeys) - - [deepConstantKeys](#deepconstantkeys) - [Type Utilities](#type-utilities) - [Native TS type utilities](#native-ts-type-utilities) - [General Type utilities from this library](#general-type-utilities-from-this-library) @@ -146,66 +146,6 @@ const result = capitalize(str) ## Strongly-typed alternatives to native runtime utilities -### toUpperCase - -This function is a strongly-typed counterpart of `String.prototype.toUpperCase`. - -```ts -import { toUpperCase } from 'string-ts' - -const str = 'hello world' -const result = toUpperCase(str) -// ^ 'HELLO WORLD' -``` - -### toLowerCase - -This function is a strongly-typed counterpart of `String.prototype.toLowerCase`. - -```ts -import { toLowerCase } from 'string-ts' - -const str = 'HELLO WORLD' -const result = toLowerCase(str) -// ^ 'hello world' -``` - -### trim - -This function is a strongly-typed counterpart of `String.prototype.trim`. - -```ts -import { trim } from 'string-ts' - -const str = ' hello world ' -const result = trim(str) -// ^ 'hello world' -``` - -### trimStart - -This function is a strongly-typed counterpart of `String.prototype.trimStart`. - -```ts -import { trimStart } from 'string-ts' - -const str = ' hello world ' -const result = trimStart(str) -// ^ 'hello world ' -``` - -### trimEnd - -This function is a strongly-typed counterpart of `String.prototype.trimEnd`. - -```ts -import { trimEnd } from 'string-ts' - -const str = ' hello world ' -const result = trimEnd(str) -// ^ ' hello world' -``` - ### charAt This function is a strongly-typed counterpart of `String.prototype.charAt`. @@ -266,32 +206,68 @@ const result = split(str, '-') // ^ ['hello', 'world'] ``` -## Strongly-typed alternatives to common loosely-typed functions +### toLowerCase -### words +This function is a strongly-typed counterpart of `String.prototype.toLowerCase`. -This function identifies the words in a string and returns a tuple of words split by separators, differences in casing, numbers, and etc. +```ts +import { toLowerCase } from 'string-ts' + +const str = 'HELLO WORLD' +const result = toLowerCase(str) +// ^ 'hello world' +``` + +### toUpperCase + +This function is a strongly-typed counterpart of `String.prototype.toUpperCase`. ```ts -import { words } from 'string-ts' +import { toUpperCase } from 'string-ts' -const str = '-20someVery-weird String' -const result = words(str) -// ^ ['20', 'some', 'Very', 'weird', 'String'] +const str = 'hello world' +const result = toUpperCase(str) +// ^ 'HELLO WORLD' ``` -### toDelimiterCase +### trim -This function converts a string to a new case with a custom delimiter at both runtime and type levels. +This function is a strongly-typed counterpart of `String.prototype.trim`. ```ts -import { toDelimiterCase } from 'string-ts' +import { trim } from 'string-ts' -const str = 'helloWorld' -const result = toDelimiterCase(str, '.') -// ^ 'hello.World' +const str = ' hello world ' +const result = trim(str) +// ^ 'hello world' ``` +### trimEnd + +This function is a strongly-typed counterpart of `String.prototype.trimEnd`. + +```ts +import { trimEnd } from 'string-ts' + +const str = ' hello world ' +const result = trimEnd(str) +// ^ ' hello world' +``` + +### trimStart + +This function is a strongly-typed counterpart of `String.prototype.trimStart`. + +```ts +import { trimStart } from 'string-ts' + +const str = ' hello world ' +const result = trimStart(str) +// ^ 'hello world ' +``` + +## Strongly-typed alternatives to common loosely-typed functions + ### toCamelCase This function converts a string to `camelCase` at both runtime and type levels. @@ -304,16 +280,28 @@ const result = toCamelCase(str) // ^ 'helloWorld' ``` -### toPascalCase +### toConstantCase -This function converts a string to `PascalCase` at both runtime and type levels. +This function converts a string to `CONSTANT_CASE` at both runtime and type levels. ```ts -import { toPascalCase } from 'string-ts' +import { toConstantCase } from 'string-ts' -const str = 'hello-world' -const result = toPascalCase(str) -// ^ 'HelloWorld' +const str = 'helloWorld' +const result = toConstantCase(str) +// ^ 'HELLO_WORLD' +``` + +### toDelimiterCase + +This function converts a string to a new case with a custom delimiter at both runtime and type levels. + +```ts +import { toDelimiterCase } from 'string-ts' + +const str = 'helloWorld' +const result = toDelimiterCase(str, '.') +// ^ 'hello.World' ``` ### toKebabCase @@ -328,28 +316,28 @@ const result = toKebabCase(str) // ^ 'hello-world' ``` -### toSnakeCase +### toPascalCase -This function converts a string to `snake_case` at both runtime and type levels. +This function converts a string to `PascalCase` at both runtime and type levels. ```ts -import { toSnakeCase } from 'string-ts' +import { toPascalCase } from 'string-ts' -const str = 'helloWorld' -const result = toSnakeCase(str) -// ^ 'hello_world' +const str = 'hello-world' +const result = toPascalCase(str) +// ^ 'HelloWorld' ``` -### toConstantCase +### toSnakeCase -This function converts a string to `CONSTANT_CASE` at both runtime and type levels. +This function converts a string to `snake_case` at both runtime and type levels. ```ts -import { toConstantCase } from 'string-ts' +import { toSnakeCase } from 'string-ts' const str = 'helloWorld' -const result = toConstantCase(str) -// ^ 'HELLO_WORLD' +const result = toSnakeCase(str) +// ^ 'hello_world' ``` ### toTitleCase @@ -364,24 +352,20 @@ const result = toTitleCase(str) // ^ 'Hello World' ``` -## Strongly-typed shallow transformation of objects - -### delimiterKeys +### words -This function shallowly converts the keys of an object to a new case with a custom delimiter at both runtime and type levels. +This function identifies the words in a string and returns a tuple of words split by separators, differences in casing, numbers, and etc. ```ts -import { delimiterKeys } from 'string-ts' +import { words } from 'string-ts' -const data = { - 'hello-world': { - 'foo-bar': 'baz', - }, -} as const -const result = delimiterKeys(data, '.') -// ^ { 'hello.world': { 'foo-bar': 'baz' } } +const str = '-20someVery-weird String' +const result = words(str) +// ^ ['20', 'some', 'Very', 'weird', 'String'] ``` +## Strongly-typed shallow transformation of objects + ### camelKeys This function shallowly converts the keys of an object to `camelCase` at both runtime and type levels. @@ -398,20 +382,36 @@ const result = camelKeys(data) // ^ { helloWorld: { 'foo-bar': 'baz' } } ``` -### pascalKeys +### constantKeys -This function shallowly converts the keys of an object to `PascalCase` at both runtime and type levels. +This function shallowly converts the keys of an object to `CONSTANT_CASE` at both runtime and type levels. ```ts -import { pascalKeys } from 'string-ts' +import { constantKeys } from 'string-ts' + +const data = { + helloWorld: { + fooBar: 'baz', + }, +} as const +const result = constantKeys(data) +// ^ { 'HELLO_WORLD': { 'fooBar': 'baz' } } +``` + +### delimiterKeys + +This function shallowly converts the keys of an object to a new case with a custom delimiter at both runtime and type levels. + +```ts +import { delimiterKeys } from 'string-ts' const data = { 'hello-world': { 'foo-bar': 'baz', }, } as const -const result = pascalKeys(data) -// ^ { HelloWorld: { FooBar: 'baz' } } +const result = delimiterKeys(data, '.') +// ^ { 'hello.world': { 'foo-bar': 'baz' } } ``` ### kebabKeys @@ -430,86 +430,86 @@ const result = kebabKeys(data) // ^ { 'hello-world': { fooBar: 'baz' } } ``` -### snakeKeys +### pascalKeys -This function shallowly converts the keys of an object to `snake_case` at both runtime and type levels. +This function shallowly converts the keys of an object to `PascalCase` at both runtime and type levels. ```ts -import { snakeKeys } from 'string-ts' +import { pascalKeys } from 'string-ts' const data = { - helloWorld: { - fooBar: 'baz', + 'hello-world': { + 'foo-bar': 'baz', }, } as const -const result = snakeKeys(data) -// ^ { 'hello_world': { 'fooBar': 'baz' } } +const result = pascalKeys(data) +// ^ { HelloWorld: { FooBar: 'baz' } } ``` -### constantKeys +### snakeKeys -This function shallowly converts the keys of an object to `CONSTANT_CASE` at both runtime and type levels. +This function shallowly converts the keys of an object to `snake_case` at both runtime and type levels. ```ts -import { constantKeys } from 'string-ts' +import { snakeKeys } from 'string-ts' const data = { helloWorld: { fooBar: 'baz', }, } as const -const result = constantKeys(data) -// ^ { 'HELLO_WORLD': { 'fooBar': 'baz' } } +const result = snakeKeys(data) +// ^ { 'hello_world': { 'fooBar': 'baz' } } ``` ## Strongly-typed deep transformation of objects -### deepDelimiterKeys +### deepCamelKeys -This function recursively converts the keys of an object to a new case with a custom delimiter at both runtime and type levels. +This function recursively converts the keys of an object to `camelCase` at both runtime and type levels. ```ts -import { deepDelimiterKeys } from 'string-ts' +import { deepCamelKeys } from 'string-ts' const data = { 'hello-world': { 'foo-bar': 'baz', }, } as const -const result = deepDelimiterKeys(data, '.') -// ^ { 'hello.world': { 'foo.bar': 'baz' } } +const result = deepCamelKeys(data) +// ^ { helloWorld: { fooBar: 'baz' } } ``` -### deepCamelKeys +### deepConstantKeys -This function recursively converts the keys of an object to `camelCase` at both runtime and type levels. +This function recursively converts the keys of an object to `CONSTANT_CASE` at both runtime and type levels. ```ts -import { deepCamelKeys } from 'string-ts' +import { deepConstantKeys } from 'string-ts' const data = { - 'hello-world': { - 'foo-bar': 'baz', + helloWorld: { + fooBar: 'baz', }, } as const -const result = deepCamelKeys(data) -// ^ { helloWorld: { fooBar: 'baz' } } +const result = deepConstantKeys(data) +// ^ { 'HELLO_WORLD': { 'FOO_BAR': 'baz' } } ``` -### deepPascalKeys +### deepDelimiterKeys -This function recursively converts the keys of an object to `PascalCase` at both runtime and type levels. +This function recursively converts the keys of an object to a new case with a custom delimiter at both runtime and type levels. ```ts -import { deepPascalKeys } from 'string-ts' +import { deepDelimiterKeys } from 'string-ts' const data = { 'hello-world': { 'foo-bar': 'baz', }, } as const -const result = deepPascalKeys(data) -// ^ { HelloWorld: { FooBar: 'baz' } } +const result = deepDelimiterKeys(data, '.') +// ^ { 'hello.world': { 'foo.bar': 'baz' } } ``` ### deepKebabKeys @@ -528,36 +528,36 @@ const result = deepKebabKeys(data) // ^ { 'hello-world': { 'foo-bar': 'baz' } } ``` -### deepSnakeKeys +### deepPascalKeys -This function recursively converts the keys of an object to `snake_case` at both runtime and type levels. +This function recursively converts the keys of an object to `PascalCase` at both runtime and type levels. ```ts -import { deepSnakeKeys } from 'string-ts' +import { deepPascalKeys } from 'string-ts' const data = { - helloWorld: { - fooBar: 'baz', + 'hello-world': { + 'foo-bar': 'baz', }, } as const -const result = deepSnakeKeys(data) -// ^ { 'hello_world': { 'foo_bar': 'baz' } } +const result = deepPascalKeys(data) +// ^ { HelloWorld: { FooBar: 'baz' } } ``` -### deepConstantKeys +### deepSnakeKeys -This function recursively converts the keys of an object to `CONSTANT_CASE` at both runtime and type levels. +This function recursively converts the keys of an object to `snake_case` at both runtime and type levels. ```ts -import { deepConstantKeys } from 'string-ts' +import { deepSnakeKeys } from 'string-ts' const data = { helloWorld: { fooBar: 'baz', }, } as const -const result = deepConstantKeys(data) -// ^ { 'HELLO_WORLD': { 'FOO_BAR': 'baz' } } +const result = deepSnakeKeys(data) +// ^ { 'hello_world': { 'foo_bar': 'baz' } } ``` ## Type Utilities @@ -579,60 +579,51 @@ Uppercase<'hello world'> // 'HELLO WORLD' ### General Type utilities from this library ```ts -St.Words<'hello-world'> // ['hello', 'world'] St.CharAt<'hello world', 6> // 'w' St.Join<['hello', 'world'], '-'> // 'hello-world' St.Replace<'hello-world', 'l', '1'> // 'he1lo-world' St.ReplaceAll<'hello-world', 'l', '1'> // 'he11o-wor1d' St.Split<'hello-world', '-'> // ['hello', 'world'] -St.TrimStart<' hello world '> // 'hello world ' -St.TrimEnd<' hello world '> // ' hello world' St.Trim<' hello world '> // 'hello world' +St.TrimEnd<' hello world '> // ' hello world' +St.TrimStart<' hello world '> // 'hello world ' +St.Words<'hello-world'> // ['hello', 'world'] ``` ### Casing type utilities ```ts St.CamelCase<'hello-world'> // 'helloWorld' -St.PascalCase<'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.ConstantCase<'helloWorld'> // 'HELLO_WORLD' St.TitleCase<'helloWorld'> // 'Hello World' -St.DelimiterCase<'hello world', '.'> // 'hello.world' // SHALLOW OBJECT KEY TRANSFORMATION St.CamelKeys<{ 'hello-world': { 'foo-bar': 'baz' } }> // { helloWorld: { 'foo-bar': 'baz' } } -St.PascalKeys<{ - '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' } } -St.ConstantKeys<{ - helloWorld: { fooBar: 'baz' } -}> // { 'HELLO_WORLD': { fooBar: 'baz' } } -St.DelimiterKeys<{ 'hello-world': { 'foo-bar': 'baz' } }, '.'> -// { 'hello.world': { 'foo-bar': 'baz' } } // DEEP OBJECT KEY TRANSFORMATION St.DeepCamelKeys<{ 'hello-world': { 'foo-bar': 'baz' } }> // { helloWorld: { fooBar: 'baz' } } -St.DeepPascalKeys<{ - 'hello-world': { 'foo-bar': 'baz' } -}> // { HelloWorld: { FooBar: 'baz' } } -St.DeepKebabKeys<{ - helloWorld: { fooBar: 'baz' } -}> // { 'hello-world': { 'foo-bar': 'baz' } } -St.DeepSnakeKeys<{ - helloWorld: { fooBar: 'baz' } -}> // { 'hello_world': { 'foo_bar': 'baz' } } St.DeepConstantKeys<{ helloWorld: { fooBar: 'baz' } }> // { 'HELLO_WORLD': { 'FOO_BAR': 'baz' } } @@ -642,6 +633,15 @@ St.DeepDelimiterKeys< }, '.' > // { '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' } } ``` ### Other exported type utilities