@spinajs/util

Utility functions shared across the @spinajs framework — argument validation, functional/async combinators, a TimeSpan duration type, a Polly-style resilience pipeline, and an assortment of small helpers.

import { TimeSpan, ResiliencePipelineBuilder, _check_arg, sleep } from '@spinajs/util';

Everything is re-exported from the package root; import by name.

Documentation

The full, current documentation is in docs/util. Where the older pages in documentation/ disagree with it, docs/util is correct.

| Scope | Docs | What's inside | |---|---|---| | Args validation | Argument validation, custom checks | _check_arg, the built-in checks, writing your own | | Assertions | Assertions | type-narrowing runtime asserts | | FP / async | Async combinators | _chain, _pipe, _zip, _map, _concurrent, branching and error combinators | | TimeSpan | TimeSpan | immutable duration type: construction, parsing, arithmetic, comparison, Date/Luxon interop, formatting | | Process | Process helpers | sleep/withTimeout, graceful shutdown, typed env parsing | | Resilience | Resilience pipeline, custom strategies | retry, timeout, circuit breaker, fallback, hedging, concurrency limiter; PredicateBuilder; cancellation; writing and sharing strategies | | Per-key backoff | Keyed backoff, Throttle, custom throttle stores | KeyedBackoff, Throttle, MemoryThrottleStore, the ThrottleStore contract | | Core helpers | Collections, objects and JSON, strings, functions and type guards | array, hash, object, json, string, func, types |

Highlights

Resilience — compose strategies into a reusable pipeline:

const pipeline = new ResiliencePipelineBuilder<Buffer>()
  .addTimeout(TimeSpan.fromSeconds(10))
  .addRetry({ MaxRetryAttempts: 3, BackoffType: BackoffType.Exponential, UseJitter: true })
  .build();

const data = await pipeline.execute(() => downloadAsync());

TimeSpan — an immutable duration accepted anywhere a TimeSpanLike is expected:

TimeSpan.fromHours(2).add(TimeSpan.fromMinutes(30)).toString(); // '02:30:00'
TimeSpan.parse('1.02:30:45')?.totalHours;                        // 26.5125

Args — validate and normalize inputs at a boundary:

const email = _check_arg(_is_string(), _trim(), _to_lower(), _is_email())(input, 'email');

Development

npm run build    # compile (tsc) to lib/mjs
npm test         # run the mocha/ts-node test suite

Coverage note: npm run coverage runs nyc, but the repo does not currently configure istanbul instrumentation for the ESM + ts-node test setup, so it reports 0%. The suite itself covers every source module; wiring up @istanbuljs/nyc-config-typescript would restore real numbers.

License

MIT