JS Helpers

Framework-agnostic TypeScript helper utilities used across @lipemat projects.

Each helper is small, dependency-light, and tree-shakeable. The package ships compiled ESM (.js) plus type declarations (.d.ts).

Installation

yarn add @lipemat/js-helpers
# or
npm install @lipemat/js-helpers

Usage

Every framework-agnostic helper is importable from the package root:

import {debounce, hexToRGB, domReady} from '@lipemat/js-helpers';

React hooks live under a separate subpath so the package root never loads React:

import {useMobile, useAsync} from '@lipemat/js-helpers/react';

Helpers

| Helper | Description | Docs | |------------------------------------------------------------|-------------------------------------------------------|----------------------------------------------| | classNameAmend, sanitizeCssModuleClass | Manipulate CSS class name strings. | classes | | hexToRGB, RGBToHex, getLightness | Convert between hex/RGB colors and measure lightness. | colors | | csvExport | Generate a CSV file and trigger a browser download. | csvExport | | getFormattedDate | Format a Date using mm/dd/yyyy tokens. | date | | debounce | Lodash-free debounce with immediate and cancel. | debounce | | delay | Resolve a promise after a set amount of time. | delay | | isDesktop, isMobile, hasMobileUserAgent | Detect desktop vs mobile clients. | device | | domReady | Run a callback once the DOM is ready. | dom-ready | | ErrorWithFields | Error subclass carrying per-field messages. | error | | decodeEntities, stripTags | Decode HTML entities or strip HTML tags from a string. | escaping | | injectScript | Inject an external script into the DOM once. | injectScript | | memoize | Lodash-free memoization with an inspectable cache. | memoize | | noop | A no-operation function. | noop | | keysOf, entriesOf | Type-safe Object.keys/Object.entries. | objects | | once | Run a function a single time and cache the result. | once | | generateRandomKey, add/removeLeading/TrailingSlash | Random keys and slash management. | string | | throttle | Lodash-free throttle with immediate and cancel. | throttle | | getUrlParam, getQueryArg, getQueryArgs, getQueryString, addQueryArgs, getFragment, buildQueryString | Read and append URL query arguments. | url | | useAsync | Run an async function and track its loading state. | useAsync | | useDebounce | Debounce a value for use as an effect dependency. | useDebounce | | useDebouncedInput | Manage an input value alongside a debounced copy. | useDebouncedInput | | useEffectOnce | Run an effect a single time on mount. | useEffectOnce | | useEffectOnChange | Run an effect on dependency change, skipping mount. | useEffectOnChange | | useMobile | Track whether the client is a mobile device. | useMobile |

The use* helpers are React hooks imported from @lipemat/js-helpers/react and require React >=18 (declared as an optional peer dependency). All other helpers are framework-agnostic and importable from the package root.

Development

yarn install      # install dependencies
yarn build        # compile src -> dist via tsc
yarn watch        # compile in watch mode
yarn validate-ts  # type-check with no emit
yarn lint         # ESLint (@lipemat/eslint-config)
yarn test         # Jest (jsdom)

See AGENTS.md for conventions on adding and documenting helpers.

License

MIT © Mat Lipe