Initial Commit

openspec/specs/utils/spec.md

@@ -0,0 +1,113 @@
+# @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