Shared TypeScript utilities for Borela Tech projects.
A lightweight, zero-runtime-dependency collection of runtime functions and type-level utilities.
npm install @borela-tech/ts-toolboxRequires TypeScript ~5.9.3 as a peer dependency.
Capitalize the first letter of a string or template literal. When used as a
template tag, the first line (after the opening `) and last line (before
the closing `) are stripped.
import {capitalize} from '@borela-tech/ts-toolbox'
capitalize('hello') // => 'Hello'
// Template tag — first/last lines from formatting are stripped:
capitalize`
hello world
`
// => 'hello world'Create a debounced function. Each call cancels the previous pending call. The
target function automatically receives an AbortSignal as the last argument,
but does not need to declare it if it is not used. Canceled calls resolve to
debouncedCallCancelled.
import {
debounce,
debouncedCallCancelled,
} from '@borela-tech/ts-toolbox'
const DELAY = 100
const fn = async (x: number) => x * 2
const debouncedFn = debounce(fn)
const a = debouncedFn(DELAY, 1) // Cancelled.
const b = await debouncedFn(DELAY, 2) // Executed.
console.log(a === debouncedCallCancelled) // => true
console.log(b) // => 4
const fnWithSignal = async (x: number, signal: AbortSignal) => {
if (signal.aborted)
return
return x * 2
}
const debouncedFnWithSignal = debounce(fnWithSignal)
const c = debouncedFnWithSignal(DELAY, 3) // Cancelled.
const d = await debouncedFnWithSignal(DELAY, 4) // Executed.
console.log(c === debouncedCallCancelled) // => true
console.log(d) // => 8Remove common leading whitespace from all lines. The first and last lines for template literals are always stripped.
import {dedent} from '@borela-tech/ts-toolbox'
dedent`
hello
indented
world
`
// => 'hello\n indented\nworld'
dedent(' hello\n indented\n world')
// => 'hello\n indented\nworld'Like dedent, but also strips leading and trailing empty lines from the
content itself (not just the template formatting lines).
import {dedentAndStrip} from '@borela-tech/ts-toolbox'
// The empty lines around hello/world are stripped:
dedentAndStrip`
hello
world
`
// => 'hello\nworld'Recursively freeze an object, making it deeply immutable. Uses a WeakSet for cycle detection.
import {deepFreeze} from '@borela-tech/ts-toolbox'
const obj = deepFreeze({a: 1, b: {c: 2}})
obj.a = 42 // TypeError (in strict mode)
obj.b.c = 3 // TypeError (in strict mode)Return the first line of a string.
import {firstLine} from '@borela-tech/ts-toolbox'
firstLine('hello\nworld\nfoo') // => 'hello'
firstLine('hello') // => 'hello'Add indentation to each line of a string. Works on both plain strings and template literals. When used as a template tag, the first and last formatting lines are stripped.
import {indent} from '@borela-tech/ts-toolbox'
// Template tag mode — indent by 2 spaces (default):
indent`hello\nworld`
// => ' hello\n world'
// Template tag with custom count and unit:
indent(1, '\t')`hello\nworld`
// => '\thello\n\tworld'
// Plain string mode:
indent('hello\nworld', 1, ' ')
// => ' hello\n world'Template literal tag that aligns continuation lines of multiline interpolated values to match the indentation of the interpolation site. Leading and trailing empty lines in the template literal are stripped.
import {interpolate} from '@borela-tech/ts-toolbox'
// The line after the opening backtick and the line before the closing backtick
// are always stripped (they come from formatting the template across lines):
const value = 'Alice\nBob'
interpolate`
hello ${value}!
`
// => ' hello Alice\n Bob!'
const code = 'fn() {\n return 1\n}'
interpolate`
${code}
`
// => ' fn() {\n return 1\n }'Return the last line of a string.
import {lastLine} from '@borela-tech/ts-toolbox'
lastLine('hello\nworld\nfoo') // => 'foo'
lastLine('hello') // => 'hello'Walk up the directory tree to find the nearest package.json.
import {getNearestParentPackageJson} from '@borela-tech/ts-toolbox'
getNearestParentPackageJson('/home/user/projects/my-app/src')
// => '/home/user/projects/my-app/package.json'
// or undefined if not foundAny function signature.
import type {AnyFunction} from '@borela-tech/ts-toolbox'
function wrap<T extends AnyFunction>(fn: T) {
return (...args: Parameters<T>) => fn(...args)
}Types associated with the debounce runtime function.
import type {
DebouncedCallResult,
DebouncedFunction,
DebouncedFunctionParameters,
} from '@borela-tech/ts-toolbox'
type Fn = (x: number) => Promise<number>
type Params = DebouncedFunctionParameters<Fn> // [x: number]
type Debounced = DebouncedFunction<Fn>
// (delay: number, ...args: [x: number]) => Promise<DebouncedCallResult<Fn>>
type Result = DebouncedCallResult<Fn>
// number | typeof debouncedCallCancelled
// If the function declares AbortSignal as its last param, it's stripped:
type FnWithSignal = (x: number, signal: AbortSignal) => Promise<number>
type StrippedParams = DebouncedFunctionParameters<FnWithSignal> // [x: number]Evaluate to true when two types are structurally equal, false otherwise.
import type {Equals} from '@borela-tech/ts-toolbox'
type A = Equals<{a: number}, {a: number}> // true
type B = Equals<{a: number}, {b: string}> // falseReturns true if T is an abstract constructor.
import type {IsAbstract} from '@borela-tech/ts-toolbox'
abstract class Animal {}
class Dog extends Animal {}
type A = IsAbstract<typeof Animal> // true
type B = IsAbstract<typeof Dog> // falseA type that may be synchronous or asynchronous.
import type {MaybePromise} from '@borela-tech/ts-toolbox'
type A = MaybePromise<number> // number | PromiseLike<number>Null-handling utility types.
import type {
NotNullable,
NotNullish,
NotUndefinable,
Nullish,
} from '@borela-tech/ts-toolbox'
type A = NotNullable<string | null> // string
type B = NotNullish<string | null | undefined> // string
type C = NotUndefinable<string | undefined> // string
type D = Nullish<string> // string | null | undefined