resultar 3.1.0 → 3.2.1

package/README.md

@@ -170,12 +170,17 @@ const user = ResultAsync.retryOrElse(
   {
     times: 2,
     delayMs: ({ nextAttempt }) => nextAttempt * 100,
+    jittered: 0.5,
     while: (error) => error._tag === 'RateLimitError' || error._tag === 'ServiceUnavailableError',
     orElse: () => readCachedUser(id),
   },
 )
 ```
 
+`jittered` randomizes the computed retry delay by a percentage factor to avoid synchronized retries.
+For example, `delayMs: 100` with `jittered: 0.5` waits between `50ms` and `150ms`; omit it or use
+`0` to keep the exact delay.
+
 Race a primary and replica with cooperative loser abort:
 
 ```ts
@@ -640,6 +645,7 @@ const user = ResultAsync.retry(
   {
     times: 2,
     delayMs: ({ nextAttempt }) => nextAttempt * 100,
+    jittered: 0.2,
     while: (error) => error._tag === 'RateLimitError',
   },
 )
@@ -653,6 +659,9 @@ const withFallback = ResultAsync.retryOrElse(
 )
 ```
 
+Use `jittered` when many callers may retry at the same time. The value is a delay spread factor:
+`jittered: 0.2` applies a random delay from `80%` to `120%` of the computed `delayMs`.
+
 For resourceful async work, use `ResultAsync.withResource` when acquisition and cleanup must stay
 paired. Cleanup is best-effort and always runs after successful acquisition, including when the use
 step returns `Err` or rejects.
@@ -932,8 +941,8 @@ pnpm exec resultar-lint doctor
 pnpm exec resultar-lint unpatch
 ```
 
-For TypeScript 7 native-preview projects, `resultar-tsgo` exposes a `tsgo` wrapper that runs native
-TypeScript and then Resultar lint validation.
+For TypeScript 7 projects using `typescript@rc`, `resultar-tsgo` exposes a `tsgo` wrapper that runs
+native TypeScript and then Resultar lint validation.
 
 ## API Decision Guide
 
@@ -1021,12 +1030,11 @@ This repository is a pnpm workspace:
 
 - `packages/resultar`: Resultar runtime package.
 - `packages/resultar-lint`: TypeScript language-service diagnostics and no-discard CLI.
-- `packages/resultar-tsgo`: TypeScript 7 native-preview `tsgo` wrapper plus Resultar lint
-  validation.
+- `packages/resultar-tsgo`: TypeScript 7 `typescript@rc` wrapper plus Resultar lint validation.
 - `benchmarks`: benchmark package.
 - `examples/resultar`: runnable core Resultar cookbook.
 - `examples/lint`: TypeScript 6 Resultar lint, patched `tsc`, and Vite+ / Oxlint smoke example.
-- `examples/tsgo-lint`: TypeScript 7 native-preview Resultar lint smoke example.
+- `examples/tsgo-lint`: TypeScript 7 `typescript@rc` Resultar lint smoke example.
 
 Common commands:
 

package/dist/index.d.ts

@@ -432,6 +432,7 @@ type ResultAsyncRetryTaskErr<Task> = Task extends ResultAsyncRetryTask<unknown,
 type ResultAsyncRetryDelay = number | ((context: ResultAsyncRetryContext) => number);
 interface ResultAsyncRetryOptions<E> {
   readonly delayMs?: ResultAsyncRetryDelay;
+  readonly jittered?: number;
   readonly onRetry?: (error: E, context: ResultAsyncRetryContext) => void | Promise<void>;
   readonly signal?: ResultAsyncAbortSignal;
   readonly times: number;

package/dist/index.js

@@ -743,13 +743,34 @@ const validateResultAsyncRetryTimes = (times) => {
 const validateResultAsyncRetryDelayValue = (delayMs) => {
 	if (!Number.isFinite(delayMs) || delayMs < 0) throw createIllegalArgumentException("ResultAsync retry delayMs must be a non-negative finite number");
 };
+const validateResultAsyncRetryJittered = (jittered) => {
+	if (!Number.isFinite(jittered) || jittered < 0) throw createIllegalArgumentException("ResultAsync retry jittered must be a non-negative finite number");
+};
+const validateResultAsyncRetryJitterRandomValue = (value) => {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw createIllegalArgumentException("ResultAsync retry jitter random value must be a finite number between 0 and 1");
+};
+const validateResultAsyncRetryStaticJittered = (jittered) => {
+	if (jittered !== void 0) validateResultAsyncRetryJittered(jittered);
+};
 const validateResultAsyncRetryStaticDelay = (delay) => {
 	if (typeof delay === "number") validateResultAsyncRetryDelayValue(delay);
 };
-const normalizeResultAsyncRetryDelay = (delay, context) => {
+const getResultAsyncRetryJitterRandom = () => {
+	const value = Math.random();
+	validateResultAsyncRetryJitterRandomValue(value);
+	return value;
+};
+const applyResultAsyncRetryJitter = (delayMs, jittered) => {
+	if (jittered === void 0 || jittered === 0 || delayMs === 0) return delayMs;
+	const random = getResultAsyncRetryJitterRandom();
+	const range = delayMs * jittered;
+	const min = Math.max(0, delayMs - range);
+	return min + (delayMs + range - min) * random;
+};
+const normalizeResultAsyncRetryDelay = (delay, jittered, context) => {
 	const delayMs = typeof delay === "function" ? delay(context) : delay ?? 0;
 	validateResultAsyncRetryDelayValue(delayMs);
-	return delayMs;
+	return applyResultAsyncRetryJitter(delayMs, jittered);
 };
 const waitResultAsyncRetryDelay = async (delayMs, signal) => {
 	if (signal.aborted) return Result.err(createResultAsyncRetryAbortError(signal));
@@ -776,6 +797,7 @@ const resolveResultAsyncRetryRecovery = async (recovered) => recovered instanceo
 const runResultAsyncRetryAttempts = async (task, options, recover) => {
 	validateResultAsyncRetryTimes(options.times);
 	validateResultAsyncRetryStaticDelay(options.delayMs);
+	validateResultAsyncRetryStaticJittered(options.jittered);
 	const signal = options.signal ?? new AbortController().signal;
 	let attempt = 0;
 	while (true) {
@@ -785,7 +807,7 @@ const runResultAsyncRetryAttempts = async (task, options, recover) => {
 		const context = createResultAsyncRetryContext(attempt, options.times);
 		if (!await shouldRetryResultAsyncError(options, result.error, context) || attempt >= options.times) return resolveResultAsyncRetryRecovery(recover(result.error, context));
 		await callResultAsyncRetryOnRetry(options, result.error, context);
-		const delayResult = await waitResultAsyncRetryDelay(normalizeResultAsyncRetryDelay(options.delayMs, context), signal);
+		const delayResult = await waitResultAsyncRetryDelay(normalizeResultAsyncRetryDelay(options.delayMs, options.jittered, context), signal);
 		if (delayResult.isErr()) return Result.err(delayResult.error);
 		attempt += 1;
 	}