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.

Installation

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

import { isString, isRegExp } from '@sveltinio/ts-utils/is';
import { contains, uniq } from '@sveltinio/ts-utils/collections';
import { isEmpty, camelToKebab } from '@sveltinio/ts-utils';
// ...

CJS

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.

// from neverthrow docs
type Result<T, E>
  = Ok<T, E>  // contains a success value of type T
  | Err<T, E> // 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:

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.

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.

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.

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 Dateobjects. Read the docs.

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.

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. Read the docs.

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.

Some look useless at first glance but they are not for Sveltin project requirements.

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.

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

Some look useless at first glance but they are not for Sveltin project requirements.

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