@dstny/stan-utils

Standard crossplatform utility library for TypeScript. Works in browser, React Native (mobile), and Node.js — no DOM or platform-specific dependencies.

Installation

npm install @dstny/stan-utils

Usage

All exports are available from the package root:

import { toList, yesNoToBoolean, booleanToYesNo, undefinedToNull, protectedEventListener } from '@dstny/stan-utils'

CJS (require) is also supported:

const { toList } = require('@dstny/stan-utils')

API

Parsers

toList(value)

Normalises a single value or an array into a filtered array. Falsy values are removed.

toList('a')           // ['a']
toList(['a', 'b'])    // ['a', 'b']
toList(null)          // []
toList([0, '', 'x'])  // ['x']

yesNoToBoolean(value)

Converts a 'yes'/'no' string or a boolean to a boolean. Case-insensitive. Returns undefined for any other type.

yesNoToBoolean('yes')  // true
yesNoToBoolean('NO')   // false
yesNoToBoolean(true)   // true
yesNoToBoolean(42)     // undefined

booleanToYesNo(value, defaultValue?)

Converts a boolean to 'yes'/'no'. Returns defaultValue (or null) when the value is undefined or null.

booleanToYesNo(true)            // 'yes'
booleanToYesNo(false)           // 'no'
booleanToYesNo(undefined)       // null
booleanToYesNo(undefined, 'no') // 'no'

undefinedToNull(value)

Converts undefined to null. All other values are returned unchanged.

undefinedToNull(undefined)  // null
undefinedToNull(null)       // null
undefinedToNull('hello')    // 'hello'
undefinedToNull(0)          // 0

Guards

protectedEventListener(onError)(fn)

Wraps an async event-listener function so that any thrown error is caught and forwarded to onError instead of propagating. Useful for attaching safe listeners to event emitters.

const safeListener = protectedEventListener((err) => console.error(err))

emitter.on('event', safeListener(async (payload) => {
  // errors here are caught and passed to onError
}))

| Parameter | Type | Description | |-----------|------|-------------| | onError | (err: unknown) => void | Called when the wrapped function throws | | fn | (...args: any[]) => Promise<unknown> | The async listener to protect |

Development

npm install

# build CJS + ESM + type declarations
npm run build

# watch mode
npm run dev

# type-check only (no emit)
npm run typecheck

# run tests
npm test

# run tests in watch mode
npm run test:watch

# remove build artefacts
npm run clean

Build output is placed in dist/:

| File | Format | |------|--------| | dist/index.js | CommonJS | | dist/index.mjs | ESM | | dist/index.d.ts | TypeScript declarations |

License

ISC