@suaveplan/utils - Universal utility library: debug, object, platform, number, random, string, email, sound, validate
Summary
Zero-external-dependency utility library for Suaveplan. Covers debug helpers, deep object manipulation, platform detection, IEEE 754 float packing, pseudo-random selection, email normalization, audio sprite management, string generation, hex validation, and byte-size enforcement.
Documentation tree
- debug — (no submodules)
- debug — (no submodules)
- email — (no submodules)
- email — (no submodules)
- errors — (no submodules)
- utils-error — (no submodules)
- number — (no submodules)
- number — (no submodules)
- object — (no submodules)
- object — (no submodules)
- platform — (no submodules)
- platform — (no submodules)
- random — (no submodules)
- pseudo — (no submodules)
- sound — (no submodules)
- sound — (no submodules)
- string — (no submodules)
- string — (no submodules)
- types — (no submodules)
- types — (no submodules)
- validate — (no submodules)
- validate — (no submodules)
- validation — (no submodules)
- size — (no submodules)
Install
bun add @suaveplan/utils
Quick Start
// Object utilities
import { deepMerge, pick, omit } from "@suaveplan/utils/object";
const merged = deepMerge({ a: 1, b: { x: 1 } }, { b: { y: 2 } });
// { a: 1, b: { x: 1, y: 2 } }
// Email normalization
import { normalizeEmail } from "@suaveplan/utils/email";
normalizeEmail("Jane.Doe+promo@gmail.com"); // "janedoe@gmail.com"
// Sound sprites
import { parseSoundVariations, getSoundKey } from "@suaveplan/utils/sound";
const variations = parseSoundVariations({ step_1: [0,100], step_2: [100,100] });
const key = getSoundKey("step", variations); // "step_1" or "step_2"
// String generation
import { generateId, parseTextWithLinks } from "@suaveplan/utils/string";
const id = generateId({ length: 12 }); // 12-char hex string
const links = parseTextWithLinks("See https://example.com for details");
// Hex validation
import { isHex } from "@suaveplan/utils/validate";
isHex("deadbeef"); // true
isHex("gg"); // false
// Size validation
import { validateSize, formatSize, parseSize, SIZE_LIMITS } from "@suaveplan/utils/validation";
validateSize(payload, SIZE_LIMITS.MEDIUM); // throws if > 100KB
formatSize(1536); // "1.50 KB"
parseSize("2MB"); // 2097152
Modules
| Module | Description | Docs |
|---|---|---|
@suaveplan/utils/debug |
Debug utilities: assertDefined, invariant, unreachable, assert |
debug.md |
@suaveplan/utils/object |
Deep object manipulation: merge, clone, pick, omit, flatten, nested get/set | object.md |
@suaveplan/utils/platform |
Runtime environment detection: browser/Node/Bun/Edge/SSR flags | platform.md |
@suaveplan/utils/number |
IEEE 754 float packing/unpacking: Float16/32/64, range checks | number.md |
@suaveplan/utils/random |
Pseudo-random selection with seed: pseudoRandom |
pseudo.md |
@suaveplan/utils/email |
Provider-aware email normalization: Gmail/Yahoo/Microsoft/generic | email.md |
@suaveplan/utils/sound |
Howler.js sprite variation management: parse, select, convert | sound.md |
@suaveplan/utils/string |
String utilities: generateId, parseTextWithLinks |
string.md |
@suaveplan/utils/validate |
Type-guard validators: isHex |
validate.md |
@suaveplan/utils/validation |
Byte-size enforcement: validateSize, formatSize, parseSize, truncateToSize |
size.md |
@suaveplan/utils/errors |
Error class and code registry: UtilsError, UTILS_CODES |
utils-error.md |
Benchmarks
Measured on Intel Xeon E5-2696 v4 @ 2.20GHz, Bun 1.3.13.
Object
| Benchmark | avg |
|---|---|
| deepMerge small | 3.61 µs/iter |
| deepMerge medium | 705 ns/iter |
| deepClone small | 897 ns/iter |
| deepClone medium | 5.16 µs/iter |
Number (float packing)
| Benchmark | avg |
|---|---|
| packFloat16 | 88 ns/iter |
| packFloat32 | 1.29 µs/iter |
| packFloat64 | 589 ns/iter |
Run benchmarks locally:
bun benchmarks/object.bench.ts
bun benchmarks/number.bench.ts