Composable TypeScript primitives for production Node.js.
No magic. No framework opinions. Seven focused modules you can import individually or together. Tree-shakeable, typed end-to-end, zero mandatory dependencies.
npm install @resolvx/corechalk is an optional peer dependency for coloured log output. Install it if you want colour, skip it if you don't — the logger works either way.
Stop writing try/catch everywhere. Result<T, E> makes failure visible in function signatures.
import { capture, captureAsync, ok, err, combine, unwrapOr } from "@resolvx/core/result";
// Wrap a throwing function
const parsed = capture(() => JSON.parse(raw));
if (!parsed.ok) {
console.error("Bad JSON:", parsed.error);
return;
}
console.log(parsed.value);
// Async version
const result = await captureAsync(() => fetch(url).then(r => r.json()));
// Combine an array of Results — returns first Err or Ok([...values])
const all = combine([parseA, parseB, parseC]);
// Default on failure
const name = unwrapOr(parseName(input), "anonymous");API: ok err capture captureAsync map mapErr andThen tap tapErr unwrapOr unwrapOrElse unwrap combine partition fromNullable fromThrowable
import { retry, pool, memoize, debounce, throttle, once, withTimeout, sleep } from "@resolvx/core/async";
// Retry with exponential backoff + jitter
const data = await retry(() => fetchFromApi(url), {
attempts: 4,
baseDelayMs: 300,
isNonRetryable: e => e instanceof HttpError && e.status === 404,
onFailedAttempt: (err, attempt, nextDelay) =>
console.warn(`Attempt ${attempt} failed, retrying in ${nextDelay}ms`),
});
// Bounded concurrency — 5 requests at a time, output order preserved
const pages = await pool(urls.map(url => () => fetch(url).then(r => r.json())), 5);
// Memoize with TTL + in-flight deduplication
// Two concurrent calls with the same args share one execution
const getUser = memoize(fetchUser, { ttlMs: 60_000 });
// Timeout
const result = await withTimeout(() => heavyComputation(), 5000, "heavyComputation");API: sleep withTimeout retry pool memoize debounce throttle once
Three implementations, consistent interface.
import { TtlCache, LruCache, DedupeCache } from "@resolvx/core/cache";
// Time-to-live cache — entries expire after ttlMs
const prices = new TtlCache<string, number>(30_000);
const price = await prices.getOrSet("ETH", () => fetchPrice("ETH"));
// LRU cache — evicts least-recently-used when full
const images = new LruCache<string, Buffer>(100);
images.set("logo", buffer);
// Deduplication cache — concurrent callers share one in-flight request
const users = new DedupeCache<string, User>(60_000);
// Called 10 times simultaneously → only 1 fetchUser() call
const user = await users.getOrFetch(userId, id => fetchUser(id));API: TtlCache · LruCache · DedupeCache
Pure functions. No side effects.
import { fmtNum, fmtUsd, fmtMs, fmtDuration, fmtBytes, fmtToken, fmtHex, fmtRelative, renderTable } from "@resolvx/core/fmt";
fmtNum(1_234_567.89, 2) // "1,234,567.89"
fmtUsd(1234.5) // "$1,234.50"
fmtMs(12_345) // "12.35s"
fmtDuration(3725) // "1h 2m 5s"
fmtBytes(1_536) // "1.50 KB"
fmtToken(1_500_000n, 6) // "1.500000" (bigint — no precision loss)
fmtHex("0xabcdef1234", 6, 4) // "0xabcd…3234"
fmtRelative(Date.now() / 1000 - 3700) // "1h 1m ago"
// No-dependency ASCII table
console.log(renderTable(
["Name", "Age"],
[["Alice", "30"], ["Bob", "25"]],
));Named namespaces, child loggers, pluggable transport.
import { createLogger } from "@resolvx/core/log";
const log = createLogger("api");
log.info("Server started", { port: 3000 });
log.warn("Rate limit approaching", { remaining: 5 });
log.error("Request failed", new Error("timeout"), { url: "/api/data" });
// Child logger — inherits level and transport, adds context to every line
const reqLog = log.child("request", { requestId: "abc-123" });
reqLog.info("Processing"); // → ns=request requestId=abc-123
// Measure async operations
const data = await log.time("fetchData", () => fetch(url).then(r => r.json()));
// Control level at runtime
log.setLevel("debug");
// Custom transport (e.g. JSON to stdout for log aggregators)
const log2 = createLogger("worker", {
transport: rec => process.stdout.write(JSON.stringify(rec) + "\n"),
});Set LOG_LEVEL env var to control the default level (debug | info | warn | error | silent).
import { fetchJson, getJson, postJson, RateLimiter, HttpError, NetworkError } from "@resolvx/core/net";
// GET with timeout + retry (3 attempts, backoff, 4xx not retried)
const user = await getJson<User>("https://api.example.com/users/1");
// POST JSON
const created = await postJson<Post>("/api/posts", { title: "Hello" });
// Error types
try {
await getJson("/api/data");
} catch (e) {
if (e instanceof HttpError) console.log(e.status, e.url);
if (e instanceof NetworkError) console.log("DNS/connection failure", e.cause);
}
// Rate limiter — 10 req/s, bursting to 20
const limiter = new RateLimiter({ rps: 10, burst: 20 });
const throttledFetch = limiter.wrap(() => getJson(url));
await Promise.all(Array.from({ length: 100 }, throttledFetch));import { brand, assertUnreachable, hasKeys, isDefined, isString } from "@resolvx/core/types";
// Branded types — prevent mixing structurally identical primitives
type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
const uid = brand<UserId>("user-123");
// processOrder(uid) � type error if OrderId is expected
// Exhaustiveness check — compile error if a union case is unhandled
function describe(status: "ok" | "pending" | "failed"): string {
switch (status) {
case "ok": return "✓";
case "pending": return "…";
case "failed": return "✗";
default: return assertUnreachable(status);
}
}
// Runtime type narrowing
if (hasKeys(data, ["price", "symbol"])) {
console.log(data.price); // data is Record<"price"|"symbol", unknown>
}- Node.js ≥ 18 (native
fetch) - TypeScript ≥ 5.0
Bug reports and PRs welcome. Run npm test before submitting.
MIT