suaveplan/openspec/specs/utils/spec.md

@suaveplan/utils — Specification

Package: @suaveplan/utils
Version at graduation: 0.1.0
Layer: Universal — zero browser/React/Node-specific APIs
Published: 2026-04-20

---

Purpose

Zero-external-dependency utility library covering debugging, object manipulation, platform detection, IEEE 754 float packing, pseudo-random selection, email normalization, audio sprite management, string utilities, hex validation, and byte-size enforcement.

---

Modules

./errors

• UtilsError — typed SuaveplanError<UtilsCode> subclass
• UTILS_CODES — stable code registry keyed by dot-path
• UtilsCode — union type of all code values

./debug

• assertDefined<T>(val, message?) — throws if val is null/undefined
• invariant(condition, message?) — throws if condition is false
• unreachable(message?) — always throws (exhaustiveness check)
• assert(condition, message?) — alias for invariant

./object

• isObject(value) / isPlainObject(value) / isObjectOrArray(value) / isEmpty(obj)
• deepMerge(a, b, skipUndefined?) / deepMergeAll(...objects)
• pick(obj, keys) / omit(obj, keys) / keepKeys / removeKeys
• flattenObject(obj, prefix?, separator?)
• getNestedValue(obj, path, default?) / setNestedValue(obj, path, value) / hasPath(obj, path)
• deepClone(obj)

./platform

• isBrowser() / isNode() / isBun() / isEdge()
• isSSR() / supportsWebWorkers() / supportsServiceWorkers()
• getPlatform() — returns "browser" | "node" | "bun" | "edge" | "unknown"

./number

• Constants: min16, max16, min32, max32, min64, max64
• packFloat16(v) / unpackFloat16(buf) — IEEE 754 half-precision
• packFloat32(v) / unpackFloat32(buf) — IEEE 754 single-precision
• packFloat64(v) / unpackFloat64(buf) — IEEE 754 double-precision
• isInFloat16Range(v) / isInFloat32Range(v) / isInFloat64Range(v)

./random

• pseudoRandom<T>(arr, index, seed?, opts?) — deterministic element selection

./email

• normalizeEmail(email) — provider-aware canonicalization (Gmail/Yahoo/Microsoft/generic)

./sound

• parseSoundVariations(sprites) — group <name>_<n> keys by base name
• getSoundKey(name, variations) — random variation selection; throws SOUND.NO_VARIATIONS
• convertSprites(sprites) — alias for parseSoundVariations
• Types: SoundSprites, SoundVariations

./string

• generateId(opts?) — random hex identifier via crypto.randomUUID()
• parseTextWithLinks(text) — extract HTTP/HTTPS URLs → TextLink[]
• Types: GenerateIdOptions, TextLink

./validate

• isHex(i) — type-guard: non-empty, even-length, hex-only string

./validation

• Constants: SIZE_LIMITS, DEFAULT_MAX_MESSAGE_SIZE
• getDataSize(data) — UTF-8 bytes for string, byteLength for binary, 8 for number
• validateSize(data, maxSize?) — throws VALIDATION.SIZE_EXCEEDED
• isWithinSizeLimit(data, maxSize?) — non-throwing boolean
• formatSize(bytes, decimals?) — "1.50 KB" format
• parseSize(str) — "1.5MB" → integer bytes; throws VALIDATION.PARSE_FAILED
• truncateToSize(data, maxSize) — binary-search string truncation

---

Error Codes

Code	Description
UTILS/OBJECT.PROTOTYPE_POLLUTION	__proto__ / constructor key detected
UTILS/OBJECT.CIRCULAR	Circular reference in deepClone
UTILS/NUMBER.OUT_OF_RANGE	Float value outside target precision range
UTILS/RANDOM.EMPTY_ARRAY	pseudoRandom called with empty array
UTILS/RANDOM.INDEX_OUT_OF_BOUNDS	index >= array.length
UTILS/VALIDATION.SIZE_EXCEEDED	Data exceeds maxSize bytes
UTILS/VALIDATION.PARSE_FAILED	Invalid size string format
UTILS/PLATFORM.UNAVAILABLE	Requested platform feature unavailable
UTILS/SOUND.NO_VARIATIONS	getSoundKey called for unknown sound name

---

Quality Gates (at ship)

• Istanbul coverage: 100% statements / branches / functions / lines
• Docs coverage: 100% (12/12 files)
• Lint: clean (biome, 0 errors)
• TypeScript: clean (noEmit)
• Tests: 169 passing