resultar 3.1.0-beta.1 → 3.2.0

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;
 	}
@@ -1097,7 +1119,7 @@ var DisposableResultAsync = class {
 */
 var ResultAsync = class ResultAsync extends Pipeable {
 	static okAsync(value) {
-		return new ResultAsync(Promise.resolve(Result.ok(value)));
+		return new ResultAsync(Promise.resolve(ok(value)));
 	}
 	/**
 	* Returns a ResultAsync that is immediately resolved with a Result.ok(undefined) value.
@@ -1108,19 +1130,19 @@ var ResultAsync = class ResultAsync extends Pipeable {
 		return new ResultAsync(Promise.resolve(Result.unit()));
 	}
 	static errAsync(error) {
-		return new ResultAsync(Promise.resolve(Result.err(error)));
+		return new ResultAsync(Promise.resolve(err(error)));
 	}
 	static tryCatch(fn, errorFn) {
-		return new ResultAsync((typeof fn === "function" ? Promise.try(fn) : fn).then((value) => Result.ok(value)).catch((error) => {
-			if (errorFn) return Result.err(errorFn(error));
-			return Result.err(error);
+		return new ResultAsync((typeof fn === "function" ? Promise.try(fn) : fn).then((value) => ok(value)).catch((error) => {
+			if (errorFn) return err(errorFn(error));
+			return err(error);
 		}));
 	}
 	static fromSafePromise(promise) {
-		return new ResultAsync(promise.then((value) => Result.ok(value)));
+		return new ResultAsync(promise.then((value) => ok(value)));
 	}
 	static fromPromise(promise, errorFn) {
-		return new ResultAsync(promise.then((value) => Result.ok(value)).catch((error) => Result.err(errorFn(error))));
+		return new ResultAsync(promise.then((value) => ok(value)).catch((error) => err(errorFn(error))));
 	}
 	static combine(input) {
 		if (Array.isArray(input)) return combineResultAsyncList(input);
@@ -1244,11 +1266,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 	static fromThrowable(fn, errorFn) {
 		return (...args) => new ResultAsync((async () => {
 			try {
-				const v = await fn(...args);
-				return Result.ok(v);
+				return ok(await fn(...args));
 			} catch (error) {
-				const e = errorFn ? errorFn(error) : error;
-				return Result.err(e);
+				return err(errorFn ? errorFn(error) : error);
 			}
 		})());
 	}
@@ -1262,32 +1282,32 @@ var ResultAsync = class ResultAsync extends Pipeable {
 	}
 	mapErr(f) {
 		return new ResultAsync(this.innerPromise.then(async (res) => {
-			if (res.isOk()) return Result.ok(res.value);
-			return Result.err(await f(res.error));
+			if (res.isOk()) return ok(res.value);
+			return err(await f(res.error));
 		}));
 	}
 	map(f) {
 		return new ResultAsync(this.innerPromise.then(async (res) => {
-			if (res.isErr()) return Result.err(res.error);
-			return Result.ok(await f(res.value));
+			if (res.isErr()) return err(res.error);
+			return ok(await f(res.value));
 		}));
 	}
 	as(value) {
 		return new ResultAsync(this.innerPromise.then((res) => {
-			if (res.isErr()) return Result.err(res.error);
-			return Result.ok(value);
+			if (res.isErr()) return err(res.error);
+			return ok(value);
 		}));
 	}
 	filterOrElse(predicate, onFalse) {
 		return new ResultAsync(this.innerPromise.then(async (res) => {
-			if (res.isErr()) return Result.err(res.error);
-			if (await predicate(res.value)) return Result.ok(res.value);
-			return Result.err(await onFalse(res.value));
+			if (res.isErr()) return err(res.error);
+			if (await predicate(res.value)) return ok(res.value);
+			return err(await onFalse(res.value));
 		}));
 	}
 	andThen(f) {
 		return new ResultAsync(this.innerPromise.then((res) => {
-			if (res.isErr()) return Result.err(res.error);
+			if (res.isErr()) return err(res.error);
 			const next = f(res.value);
 			return next instanceof ResultAsync ? next.innerPromise : next;
 		}));
@@ -1304,7 +1324,7 @@ var ResultAsync = class ResultAsync extends Pipeable {
 				const next = f(res.error);
 				return next instanceof ResultAsync ? next.innerPromise : next;
 			}
-			return Result.ok(res.value);
+			return ok(res.value);
 		}));
 	}
 	catchTag(tag, f) {