https://github.com/sveltinio/ts-utils
A bunch of common utilities in pure Typescript to deal with primitives, strings, urls, objects, collections, dates etc.
https://github.com/sveltinio/ts-utils
javascript neverthrow typescript utilities-library
Last synced: 3 months ago
JSON representation
A bunch of common utilities in pure Typescript to deal with primitives, strings, urls, objects, collections, dates etc.
- Host: GitHub
- URL: https://github.com/sveltinio/ts-utils
- Owner: sveltinio
- License: mit
- Created: 2023-03-07T19:52:18.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-12-06T01:43:45.000Z (over 1 year ago)
- Last Synced: 2025-02-14T19:49:24.035Z (3 months ago)
- Topics: javascript, neverthrow, typescript, utilities-library
- Language: TypeScript
- Homepage: https://ts-utils.sveltin.io/
- Size: 604 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
@sveltinio/ts-utils
A bunch of common utilities in pure Typescript to deal with primitives, strings, urls, objects, collections, dates etc.
> The package has been created to make my life easier with the requirements of [Sveltin] based projects and its [packages]. Anyhow, Sveltin is definitely not mandatory and you could find something fitting your needs.
## Table of contents
- [Installation](#installation)
- [Usage](#usage)
- [Type-Safe Error Handling](#type-safe-error-handling)
- [What's inside?](#whats-inside)
- [Is](#is)
- [Collections](#collections)
- [Colors](#colors)
- [Dates](#dates)
- [Objects](#objects)
- [Paths](#paths)
- [Strings](#strings)
- [Urls](#urls)
## Installation
```bash
npm install @sveltinio/ts-utils
# or
pnpm add @sveltinio/ts-utils
# or
yarn add @sveltinio/ts-utils
```
## Usage
The package supports ES Module and Common JS formats.
### ESM
```javascript
import { isString, isRegExp } from '@sveltinio/ts-utils/is';
import { contains, uniq } from '@sveltinio/ts-utils/collections';
import { isEmpty, camelToKebab } from '@sveltinio/ts-utils';
// ...
```
### CJS
```javascript
const { hasProperty, hasPropertyValue } = require('@sveltinio/ts-utils/objects')
```
## Type-Safe Error Handling
Except the functions returning a `boolean` value, the others mainly return a `Result` type that represents either success (`Ok`) or failure (`Err`) from [neverthrow] for a [type-safe error handling].
```typescript
// from neverthrow docs
type Result
= Ok // contains a success value of type T
| Err // contains a failure value of type E
```
The ways to access the return value from a `Result` type may vary based on the use-case and your programming style. Below some samples for quick reference:
```javascript
import { toKebabCase } from '@sveltinio/ts-utils/strings';
toKebabCase('hello world').value;
// => "hello-world"
const result1 = toKebabCase('hello world');
if (result1.isOk()) {
console.log(result1.value); // => "hello-world"
}
const result2 = toKebabCase('hello world').match(
(str) => str, // => "hello-world"
(err) => `${err.message}`
);
console.log(result2);
toKebabCase(2)
.map((str) => console.log(str))
.mapErr((err) => {
throw new Error(err.message); // => Error: [strings.toKebabCase] Expected string value as input
});
```
> Refer to the [neverthrow documentation] for the full picture.
## What's inside?
### Is
Type guard utilities helping with [primitive] values and basic objects.
Read the **[docs](https://ts-utils.sveltin.io/modules/is.html)**.
```javascript
import { ... } from '@sveltinio/ts-utils/is';
```
| Name | Description |
|:--------------|:-----------------------------------------------------|
| isBool | Checks if a given value is of type `boolean` |
| isNumber | Checks if a given value is of type `number` |
| isBigInt | Checks if a given value is of type `bigint` |
| isString | Checks if a given value is of type `string` |
| isArray | Checks if a given value is an array |
| isObject | Checks if a given value is an object |
| isPlainObject | Checks if a given value is a plain JavaScript object |
| isFunction | Checks if a given value is of type `function` |
| isSymbol | Checks if a given value is of type `symbol` |
| isDate | Checks if a given value is a valid `Date` object |
| isRegExp | Checks if a given value is a valid `RegExp` object |
| isDefined | Checks if a given value is defined and not null |
| isTruthy | Checks if a given value is a [truthy] value |
| isNullish | Checks if a value is null or undefined |
| isNull | Checks if a given value is null |
| isUndefined | Checks if a given value is undefined |
| isEmpty | Checks if a given value is empty or not |
### Collections
Some utilities to deal with arrays.
Read the **[docs](https://ts-utils.sveltin.io/modules/collections.html)**.
```javascript
import { ... } from '@sveltinio/ts-utils/collections';
```
| Name | Description |
|:----------------- |:--------------------------------------------------------------------------------------------------- |
| sortBy | Sorts an array of objects based on a specified property and order |
| groupedByOne | (1:1) Groups an array of objects by a specified property and returns an array of grouped objects |
| groupedByMany | (1:many) Groups an array of objects by a specified property and returns an array of grouped objects |
| pickRandom | Picks random values from an array of numbers or strings |
| shuffle | Shuffles the elements of an array of number, or string values randomly |
| shuffleByProperty | Shuffles an array of plain JavaScript objects by the specified property |
| contains | Checks if an array contains a given value or an array of values |
| uniq | Removes duplicates from an array of numbers or strings |
### Colors
Some utilities to deal with hex color strings.
Read the **[docs](https://ts-utils.sveltin.io/colors/is.html)**.
```javascript
import { ... } from '@sveltinio/ts-utils/colors';
```
| Name | Description |
|:-------------- |:--------------------------------------------------------------------------- |
| isHex | Checks if a given string is a valid hexadecimal color code |
| getHexValue | Returns either the substring after the first character (if the string is a valid hex value) or an error message |
| randomHexColor | Returns a string representing a random hex color |
### Dates
Some utilities to deal with javascript `Date`objects.
Read the **[docs](https://ts-utils.sveltin.io/modules/dates.html)**.
```javascript
import { ... } from '@sveltinio/ts-utils/dates';
```
| Name | Description |
|:------------- |:-------------------------------------------------------------------------- |
| padTo2Digits | Given a number, returns a string that is the number padded to two digits |
| dayOfMonth | Given a date string in the format MM/DD/YYYY, returns the day of the month |
| formatDate | Given a date object, returns a string in the format DD/MM/YYYY |
| formatDateISO | Given a date object, returns a string in the format YYYY-MM-DD |
| monthShort | Given a date string in the format MM/DD/YYYY, returns the short month name |
### Objects
Some utilities to deal with javascript objects, their properties and values.
Read the **[docs](https://ts-utils.sveltin.io/modules/objects.html)**.
```javascript
import { ... } from '@sveltinio/ts-utils/objects';
```
| Name | Description |
|:---------------------- |:--------------------------------------------------------------------------------- |
| hasProperty | Checks if a plain JavaScript object has a specified property |
| hasProperties | Checks if an object has all the specified properties |
| hasPropertyValue | Checks if an object has the specified property with the given value and same type |
| hasPropertiesWithValue | Checks if an object has the specified properties with the given values |
| merge | Recursively merges two objects of compatible types |
| getPropertyValue | Gets the value of a property on an object |
| mapToCssVars | Returns a CSS variable string from a plain object with key-value pairs |
### Paths
Some utilities to deal with path strings. The functions do not interface with the real file system but they are used to extract some information from the given path string. It means not ensuring e.g. a file exists or a folder is a real folder on the disk. For that, simply use what already [exists](https://nodejs.org/api/path.html).
> Some look useless at first glance but they are not for Sveltin project requirements.
Read the **[docs](https://ts-utils.sveltin.io/modules/paths.html)**.
```javascript
import { ... } from '@sveltinio/ts-utils/paths';
```
| Name | Description |
|:----------- |:---------------------------------------------------------------------------------------- |
| isDir | Checks if a given path is a directory |
| isFile | Checks if a given path is a file path |
| dirname | Returns the directory name from a given file path |
| filename | Returns the filename from a given file path |
| isImage | Checks if a given string is a valid image file name (jpg, jpeg, png, gif, webp, or avif) |
| lastSegment | Returns the last segment of a given path string |
### Strings
Some utilities to deal with strings and string conversions.
Read the **[docs](https://ts-utils.sveltin.io/modules/strings.html)**.
```javascript
import { ... } from '@sveltinio/ts-utils/strings';
```
| Name | Description |
|:-------------------- |:------------------------------------------------------------------------------------- |
| normalize | Normalizes a string by replacing non-word characters with a space character |
| capitalize | Capitalizes first letter of the string and lowercase the rest |
| capitalizeAll | Capitalizes first letters of each word in a string |
| uppercase | Converts a string to uppercase |
| lowercase | Converts a string to lowercase |
| removeTrailingSlash | Removes all trailing slashes from a string |
| textBetween | Returns the substring between start and end delimiters |
| toSlug | Removes all non-word characters, and replaces all spaces with dashes |
| toTitle | Replaces all dashes with spaces, and capitalizes all words |
| toSnakeCase | Converts a string to snake_case format |
| toKebabCase | Converts a string to kebab-case format |
| toCamelCase | Converts a string to camelCase format |
| toPascalCase | Converts a string to PascalCase format |
| camelToSnake | Converts a camelCase string to snake_case format |
| camelToKebab | Converts a camelCase string to kebab-case format |
| isCommaSeparated | Checks if a given string contains a comma-separated list |
| toCommaSeparated | Replaces all whitespace and semicolons with commas to return a comma-separated string |
| removeFirstOccurence | Removes the first occurrence of a specified string from a given text. |
### Urls
Some utilities to deal with urls.
Read the **[docs](https://ts-utils.sveltin.io/modules/urls.html)**.
> Some look useless at first glance but they are not for Sveltin project requirements.
```javascript
import { ... } from '@sveltinio/ts-utils/urls';
```
| Name | Description |
|:-------------- |:--------------------------------------------------------------------------------- |
| isUrl | Checks if a given string is a valid URL |
| canonicalUrl | Given a base URL and a pathname, returns a canonical URL |
| makeImagePath | Makes the full qualified path to the image file |
| parentUrl | Given an URL, returns the parent url of it (w/o the last segment of the pathname) |
| parentPathname | Given an URL, returns the parent pathname (w/o the last segment of the it) |
| pathSegments | Extracts the path segments from a valid URL and returns them as an array |
## License
Free and open-source software under the [MIT License](LICENSE)
[Sveltin]: https://github.com/sveltinio/sveltin
[packages]: https://github.com/sveltinio/components-library
[neverthrow]: https://github.com/supermacro/neverthrow
[type-safe error handling]: https://gdelgado.ca/type-safe-error-handling-in-typescript.html
[neverthrow documentation]: https://github.com/supermacro/neverthrow#api-documentation
[truthy]: https://developer.mozilla.org/en-US/docs/Glossary/Truthy
[primitive]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values
[WAI ARIA Patterns]: https://www.w3.org/WAI/ARIA/apg/patterns/