Skip to content

README.md

Latest commit

 

History

History
79 lines (60 loc) · 4.48 KB

README.md

File metadata and controls

79 lines (60 loc) · 4.48 KB
Raw

Documentation

Per-module documentation for @brmorillo/utils. Each module has its own folder with a complete README.md (overview, every public method, parameters, return values, examples, and errors thrown).

For architecture, design conventions and contributor guidance, see CLAUDE.md.

Conventions used throughout the library:

  • Static utility classes (e.g. ArrayUtils, StringUtils) expose only static methods — no instances. The configurable services (HttpService, LogService, StorageService) are singletons with a method-style API instead.
  • Single object argument: utility methods take one destructured object, e.g. StringUtils.toCamelCase({ input }).
  • Non-mutating by default: methods that transform data return a new value and leave the input untouched. In-place mutation is opt-in via inPlace: true (on SortUtils.* and ObjectUtils.unflattenObject). The sole exception is ObjectUtils.deepFreeze, which freezes its input in place by design.
  • is* vs isValid*: property predicates are is* (isEven, isPrime); format validators are isValid* (isValidEmail, isValidCPF).
  • Typed errors: failures throw ValidationError, StorageError, HttpError, QueueFullError, or BaseError (with a machine-readable code). See Errors.

Core data

Module Class Description
array ArrayUtils Deduplicate, intersect, flatten, group, shuffle, sort, subset checks
object ObjectUtils Deep clone/merge, pick/omit, flatten, diff, compare, freeze
string StringUtils Case conversion, truncate, palindrome, occurrences, templating
number NumberUtils Rounding, parity, ranges, factorial, clamp, cents
math MathUtils Percentage, gcd/lcm, clamp, primality, random ranges

Data & validation

Module Class Description
convert ConvertUtils Unit conversion (space/weight/volume) and value/type conversion
date DateUtils Date/interval/duration handling and time zones (Luxon)
validation ValidationUtils Email, URL, phone, JSON, hex color, CPF/CNPJ/RG

Security & cryptography

Module Class Description
crypt CryptUtils AES-256-GCM, ChaCha20-Poly1305, RSA (OAEP), ECC
hash HashUtils bcrypt, SHA-256/512, random tokens
jwt JWTUtils Sign, verify (algorithm allowlist), decode, refresh

Identifiers

Module Class Description
uuid UUIDUtils UUID v1/v4/v5 generation and validation
cuid CuidUtils CUID2 generation and format checking
snowflake SnowflakeUtils Twitter-style Snowflake IDs (custom epoch)

Data structures & algorithms

Module Class Description
sort SortUtils 18 sorting algorithms
queue QueueUtils Queue, stack, priority queue, delay queue, circular buffer, multi-queue
cache CacheUtils, Cache In-memory caching (LRU/LFU/FIFO) with TTL
benchmark BenchmarkUtils Execution-time and memory benchmarking

System & I/O

Module Class Description
file FileUtils File-system read/write/copy/move/hash helpers
request RequestUtils Extract request metadata (IP, user-agent parsing)
http HttpService HTTP client (Axios or native), configurable
log LogService Structured logging (Pino, Winston, Console)
storage StorageService File storage (local filesystem or AWS S3)

Events & control flow

Module Class Description
event EventUtils Type-safe event emitter / observer pattern
retry RetryUtils Retry with capped exponential backoff and jitter
lazy-loader LazyLoader Lazy, cached, one-time value creation

Shared

Module Description
errors Typed error hierarchy (BaseError and subclasses)