@kikiutils/shared

A lightweight, modular TypeScript utility library for Node.js and browser projects. It groups small, focused helpers for binary conversion, hashing, logging, dates, enum extraction, environment variables, numeric formatting, strings, URLs, Vue, web redirects, and typed storage wrappers.

• ✨ Release Notes

Features

• 📦 Modular imports — import only the modules you use via @kikiutils/shared/<module>.
• 🧱 TypeScript-first — ships source and declaration output for strongly typed utility APIs.
• 🔁 General helpers — normalize single-or-array values with extractFirstValue.
• 🧬 Binary helpers — convert Blob, File, ArrayBuffer, Uint8Array, and Buffer to Node Buffer.
• 🔒 Hashing helpers — SHA-3 helpers for universal usage and Node crypto MD5/SHA-3 helpers.
• 📜 Logging helpers — preconfigured Consola and Pino logger instances with env-based levels.
• 📅 Date helpers — format dates and compute common ranges such as today, this week, and last month.
• 🔢 Number and math helpers — compact number display, precise percentages, and fixed-decimal arithmetic.
• 🔤 String/random helpers — random strings and randomized-length value generation.
• 🧾 Object helpers — deterministic nested object serialization for signatures and cache keys.
• 🧭 URL helpers — append or replace redirect query parameters safely.
• 🌱 Environment helpers — read required environment variables with a dedicated missing-env error.
• 🧩 Vue/web helpers — Vue Router redirects, timer ref cleanup, scroll preservation, and browser redirects.
• 🗄️ Storage helpers — typed keyed-store facades for LRU cache and Redis-like storage.
• 🛤️ Class utilities — immutable Path wrapper and chainable PrecisionNumber arithmetic.
• 🧰 Shared types — reusable nullable, readonly, partial-record, binary-input, and filtered-key-path types.

Requirements

• Node.js >=22.12.0
• ESM package ("type": "module")
• Optional peer dependencies are installed only when you use the modules that need them.

Installation

Using pnpm:

pnpm add @kikiutils/shared

You can also use npm, yarn, or bun.

[!NOTE] This package is intentionally modular. Imports such as @kikiutils/shared/datetime or @kikiutils/shared/vue may require their peer dependencies (date-fns, vue, and so on). Install only the peers used by your chosen modules.

Usage and import style

Import individual modules to keep dependency usage explicit:

import { logger } from '@kikiutils/shared/consola';
import { extractFirstValue } from '@kikiutils/shared/general';

const value = extractFirstValue([
    0,
    1,
]);

logger.info(value); // 0

Module guide

| Module | Runtime | Main exports | Use case | | --- | --- | --- | --- | | buffer | Node/browser-compatible inputs, Node output | toBuffer | Convert Blob, File, ArrayBuffer, Uint8Array, or Buffer to Node Buffer. | | clipboard | Browser | copyTextToClipboard, copyBlobToClipboard | Safe result wrappers around the modern Clipboard API. | | consola | Node/browser | consolaLogger, logger | Shared Consola instance with env-based log level. | | crypto-hash | Node | cryptoMd5, cryptoSha3*, *ToBuffer | Node crypto MD5/SHA-3 helpers with text or raw-buffer output. | | datetime | Node/browser | formatDate, getDateRangeFromDate, getMidnightDateFromToday | Date formatting and common date-range calculations via date-fns. | | element-plus | Vue/browser | createElFormItemRuleWithDefaults | Create Element Plus form rules with default required, trigger, and type. | | enum | Any | getEnumValues, getEnumNumberValues, getEnumStringValues | Extract TypeScript enum values while ignoring numeric reverse mappings. | | env | Node | checkAndGetEnvValue, EnvironmentNotFoundError | Read required env vars without treating empty strings as missing. | | event-awaiter | Any | EventAwaiter | Wait/trigger keyed asynchronous events with timeout, abort, strict, and override modes. | | general | Any | extractFirstValue | Normalize a single value or array into the first resolved value. | | hash | Any | sha3224, sha3256, sha3384, sha3512 | SHA-3 helpers backed by @noble/hashes; returns hex strings. | | math | Any | toPercentageString | Precise percentage strings using decimal.js. | | number | Any | toCompactNumberString | Compact display strings using millify. | | object | Any | stringifyObjectDeterministically | Stable flattened object serialization for signatures/cache keys. | | pino | Node | pinoLogger, logger | Shared Pino logger with pretty output and env-based level. | | random | Any | generateWithNestedRandomLength | Generate values with a two-step randomized length. | | string | Any | randomString | Random strings from preset character sets. | | time | Any | abortableDelay | Promise delay that resolves early on abort. | | url | Any | appendRedirectParamToUrl | Add or replace a redirect query parameter. | | vue | Vue/browser | appendRedirectParamFromCurrentRouteToUrl, clearIntervalRef, clearTimeoutRef, usePreserveScroll | Vue Router redirect and ref cleanup helpers. | | web | Browser | appendRedirectParamFromCurrentLocationToUrl, assignUrlWithRedirectParamFromCurrentLocation | Browser redirect helpers based on window.location. | | classes/path | Node | Path | Immutable path wrapper plus common fs/promises delegations. | | classes/precision-number | Any | PrecisionNumber | Chainable fixed-decimal arithmetic powered by decimal.js. | | storages/lru/keyed-store | Any | createLruKeyedStore | Typed key resolver wrapper around lru-cache. | | storages/redis/keyed-store | Node | createRedisKeyedStore | Typed key resolver wrapper around Redis-like storage. | | storages/redis/msgpack | Node | createRedisMsgpackStorage | Redis-like storage facade with MessagePack serialization. | | types | TypeScript | Common utility types | Shared utility and path-filtering types. |

Examples

Required environment variable

import { checkAndGetEnvValue } from '@kikiutils/shared/env';

const apiKey = checkAndGetEnvValue('API_KEY');

Date ranges

import { getDateRangeFromDate } from '@kikiutils/shared/datetime';

const range = getDateRangeFromDate(new Date(), 'thisWeek', { weekStartsOn: 1 });
console.log(range.startDate, range.endDate);

Precise numeric display

import { PrecisionNumber } from '@kikiutils/shared/classes/precision-number';
import { toPercentageString } from '@kikiutils/shared/math';

const amount = new PrecisionNumber('1.239', 2).plus('2.111');
console.log(amount.toString()); // 3.35
console.log(toPercentageString(1, 3, { decimalPlaces: 2 })); // 33.33%

Browser redirect preservation

import { appendRedirectParamToUrl } from '@kikiutils/shared/url';

const loginUrl = appendRedirectParamToUrl('/login', '/dashboard?tab=home');
// /login?redirect=%2Fdashboard%3Ftab%3Dhome

LRU keyed store

import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';
import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, { name: string }>({ max: 100 });
const users = createLruKeyedStore<{ name: string }>(cache)((id: string) => `user:${id}`);

users.setItem({ name: 'Alice' }, '1');
console.log(users.getItem('1')); // { name: 'Alice' }

Optional peer dependencies

Most modules are tiny wrappers around platform APIs or optional peers. If your package manager does not auto-install peers, add the ones you import:

| Module | Peer dependency | | --- | --- | | crypto-hash / hash | @noble/hashes for hash; Node crypto for crypto-hash | | datetime | date-fns | | element-plus | async-validator, element-plus | | classes/precision-number, math | decimal.js | | number | millify | | consola | consola | | pino | pino, pino-pretty | | storages/lru/keyed-store | lru-cache | | storages/redis/msgpack | msgpackr | | vue | vue, vue-router |

Development

pnpm install
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build

License

MIT License