@sveltinio/ts-utils NPM

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