@donb/utils

A collection of useful utility functions and types that help carrying out some basic (but specific) JavaScript operations and getting around some limitations in native ECMAScript methods, TypeScript generic types, or in other libraries such as file-system APIs.

---

Installation

Add package with Deno

deno add jsr:@donb/utils

Import Symbol

import*asutilsfrom"@donb/utils";

---

Exported sub-modules

arrays

Utilities for working with iterables of any type.

Functions from this module always return new objects (Array or Map objects) and do not mutate the input iterables.

Usage:

Sorting

import{sort}from"@donb/utils/arrays/sort";constiterable=[{id: 3},4,{id: 2},1];console.log(sort(iterable));// [ 1, 4, { id: 2 }, { id: 3 } ]

Sorting with callback

import{sort}from"@donb/utils/arrays/sort";constiterable=[{id: 3},4,{id: 2},1];console.log(sort(iterable,element=>typeofelement==="number" ? element : element.id,),);// [ 1, { id: 2 }, { id: 3 }, 4 ]

Matching

import{match}from"@donb/utils/arrays/match";constinputs=["abbbc","baaac","acccb"];constcandidates=["a","b","c","cccb"];console.log(match(inputs,candidates));// Map(3) { "abbbc" => "b", "baaac" => "a", "acccb" => "cccb" }

Matching with callbacks

import{match}from"@donb/utils/arrays/match";constinputs=[{inputProp: "abbbc"},{inputProp: "baaac"}];constcandidates=[{candidateProp: "a"},{candidateProp: "b"}];console.log(match({iterable: inputs,callback: input=>input.inputProp,},{iterable: candidates,callback: candidate=>candidate.candidateProp,},),);// Map(2) {// { inputProp: "abbbc" } => { candidateProp: "b" },// { inputProp: "baaac" } => { candidateProp: "a" }// }

numbers

Utilities for working with number values or digit-characters in a string.

Usage:

Padding

import{toPadded}from"@donb/utils/numbers/to-padded";constnum1=2;console.log(toPadded(num1,2));// "02"constnum2=100;console.log(toPadded(num2,3));// "100" (no padding)conststr="index 2 - title";console.log(toPadded(str,3));// "index 002 - title"

strings

Utilities for working with string values and for converting other values to string.

Usage:

Character matching

import{matchChars}from"@donb/utils/strings/match-chars";constfirst="aabbccddeeff";constsecond="ghbiej";console.log(matchChars(first,second));// ["b", "b", "e", "e"]

Substring matching

import{matchSubstrings}from"@donb/utils/strings/match-substrings";constfirst="aaa bbb ccc ddd";constsecond="eee ccc fff aaa";console.log(matchSubstrings(first,second));// ["aaa", "ccc"]

Stringifying values

import{stringifyAll}from"@donb/utils/strings/stringify-all";constobj={a: 100000000000000000000n,b: true,c: functionfunc(){},d: null,e: 20.3,f: {id: 4},g: "bar",h: Symbol("foobar"),i: undefined,};console.log(stringifyAll(obj));// {"a":"100000000000000000000","b":"true","c":"function func() {}","d":"null","e":"20.3","f":{"id":"4"},"g":"bar","h":"Symbol(foobar)","i":"undefined"}

fs

Utilities for working with file-system APIs.

Usage:

Reading from a directory with type-filter

// Asynchronousimport{readDirWithTypes}from"@donb/utils/fs/read-dir-with-types";import{extname}from"@std/path/extname";constdirEntries=awaitreadDirWithTypes("/",[".ts",".js"]);console.log(dirEntries.every(entry=>[".ts",".js"].includes(extname(entry.name))),);// trueconstdirsOnly=awaitreadDirWithTypes("/",["directory"]);console.log(dirsOnly.every(entry=>entry.isDirectory));// true

// Synchronousimport{readDirSyncWithTypes}from"@donb/utils/fs/read-dir-sync-with-types";import{extname}from"@std/path/extname";constdirEntries=readDirSyncWithTypes("/",[".ts",".js"]);console.log(dirEntries.every(entry=>[".ts",".js"].includes(extname(entry.name))),);// trueconstdirsOnly=readDirSyncWithTypes("/",["directory"]);console.log(dirsOnly.every(entry=>entry.isDirectory));// true

propchecker

Utilities for verifying the compatibility of object properties specifically and/or variable values in general.

Usage:

Non-nullability checking

import{isNonNullable}from"@donb/utils/propchecker/is-non-nullable";constobj={prop1: 0,prop2: null,prop3: undefined};console.log(isNonNullable(obj.prop1));// trueconsole.log(isNonNullable(obj.prop2));// falseconsole.log(isNonNullable(obj.prop3));// false// with throwErrorfunctionfunc(){isNonNullable(obj.prop2,{objectType: obj,key: "prop2",caller: func});}func();// Throws PropertyRequiredTypeError

Type checking

import{isOfType}from"@donb/utils/propchecker/is-of-type";constobj={prop1: "1",prop2: 2};console.log(isOfType(obj.prop1,"string"));// trueconsole.log(isOfType(obj.prop2,"string"));// falseconsole.log(isOfType(obj.prop2,["string","number"]));// true// with throwErrorisOfType(obj.prop1,["number","bigint"],{objectType: obj,key: "prop1"});// Throws PropertyTypeError

types

Utilites for working with types in Typescript including extracting and building types from other types as well as narrowing types via constraints.