@backendkit-labs/result 0.1.0 → 0.1.2

package/README.md

@@ -587,7 +587,7 @@ const result = await retry(
 
 ### `retryWithBackoff(fn, options)`
 
-Exponential backoff: delay doubles on each retry, capped at `maxDelayMs`.
+Exponential backoff: delay doubles on each retry, capped at `maxDelayMs`. Supports **jitter** to prevent thundering herd when multiple instances retry simultaneously.
 
 ```typescript
 import { retryWithBackoff, run } from '@backendkit-labs/result';
@@ -616,6 +616,37 @@ const result = await retryWithBackoff(
 );
 ```
 
+#### Jitter
+
+When many instances of your service fail at the same time (e.g. a downstream goes down), they all retry on the same schedule — creating a synchronized spike that can overwhelm the recovering service. Jitter spreads those retries across time.
+
+```typescript
+// Full jitter — delay = random(0, computedDelay)
+// Maximum spread. Best for high-concurrency scenarios (many parallel clients).
+await retryWithBackoff(() => run(() => callApi()), {
+  attempts:   4,
+  delayMs:    500,
+  maxDelayMs: 10_000,
+  jitter:     true,
+});
+
+// Partial jitter — delay ± (computedDelay × factor)
+// Keeps delays close to the backoff curve while adding noise.
+// 0.25 = ±25%: a computed 1000ms delay becomes 750ms–1250ms.
+await retryWithBackoff(() => run(() => callApi()), {
+  attempts:   4,
+  delayMs:    500,
+  maxDelayMs: 10_000,
+  jitter:     0.25,
+});
+```
+
+| `jitter` value | Behaviour | Use when |
+|---|---|---|
+| `false` / omitted | No randomness — deterministic delays | Tests, single-instance services |
+| `true` | Full jitter: `random(0, delay)` | Many parallel clients retrying the same service |
+| `0.0–1.0` | Partial jitter: `delay ± (delay × factor)` | You want backoff shape preserved with light noise |
+
 ### `withTimeout(fn, ms, timeoutError)`
 
 Races a Result-returning function against a deadline.

package/dist/chunk-GCGL2Y6D.cjs

@@ -0,0 +1,100 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/result/constructors.ts
+var ok = (value) => ({ ok: true, value });
+var fail = (error) => ({ ok: false, error });
+function fromThrowable(fn, errorTransform) {
+  try {
+    return ok(fn());
+  } catch (caught) {
+    return fail(errorTransform ? errorTransform(caught) : caught);
+  }
+}
+async function fromPromise(promise, errorTransform) {
+  try {
+    return ok(await promise);
+  } catch (caught) {
+    return fail(errorTransform ? errorTransform(caught) : caught);
+  }
+}
+function fromNullable(value, error) {
+  return value != null ? ok(value) : fail(error);
+}
+
+// src/result/guards.ts
+function isOk(result) {
+  return result.ok === true;
+}
+function isFail(result) {
+  return result.ok === false;
+}
+function isRich(result) {
+  return "durationMs" in result;
+}
+
+// src/result/run.ts
+async function run(fn, errorTransform) {
+  try {
+    return ok(await fn());
+  } catch (caught) {
+    return fail(errorTransform ? errorTransform(caught) : caught);
+  }
+}
+async function track(fn, options) {
+  const start = performance.now();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const meta = {
+    durationMs: 0,
+    timestamp,
+    operation: options?.operation,
+    correlationId: options?.correlationId,
+    tags: options?.tags
+  };
+  try {
+    const value = await fn();
+    return { ok: true, value, ...meta, durationMs: Math.round(performance.now() - start) };
+  } catch (caught) {
+    const error = options?.errorTransform ? options.errorTransform(caught) : caught;
+    return { ok: false, error, ...meta, durationMs: Math.round(performance.now() - start) };
+  }
+}
+function enrich(result, options) {
+  return {
+    ...result,
+    durationMs: 0,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    operation: options?.operation,
+    correlationId: options?.correlationId,
+    tags: options?.tags
+  };
+}
+function simplify(rich) {
+  return rich.ok ? { ok: true, value: rich.value } : { ok: false, error: rich.error };
+}
+
+exports.__decorateClass = __decorateClass;
+exports.enrich = enrich;
+exports.fail = fail;
+exports.fromNullable = fromNullable;
+exports.fromPromise = fromPromise;
+exports.fromThrowable = fromThrowable;
+exports.isFail = isFail;
+exports.isOk = isOk;
+exports.isRich = isRich;
+exports.ok = ok;
+exports.run = run;
+exports.simplify = simplify;
+exports.track = track;
+//# sourceMappingURL=chunk-GCGL2Y6D.cjs.map
+//# sourceMappingURL=chunk-GCGL2Y6D.cjs.map

package/dist/chunk-GCGL2Y6D.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/result/constructors.ts","../src/result/guards.ts","../src/result/run.ts"],"names":[],"mappings":"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","file":"chunk-GCGL2Y6D.cjs","sourcesContent":["import type { Result } from './types.js';\n\n/** Creates a successful Result. */\nexport const ok = <T, E = never>(value: T): Result<T, E> =>\n  ({ ok: true, value });\n\n/** Creates a failed Result. */\nexport const fail = <T = never, E = Error>(error: E): Result<T, E> =>\n  ({ ok: false, error });\n\n/**\n * Wraps a synchronous throwable function. Catches any thrown value and\n * passes it through `errorTransform` (defaults to identity cast).\n *\n * @example\n * const result = fromThrowable(() => JSON.parse(raw), (e) => new ParseError(e));\n */\nexport function fromThrowable<T, E = Error>(\n  fn: () => T,\n  errorTransform?: (caught: unknown) => E,\n): Result<T, E> {\n  try {\n    return ok(fn());\n  } catch (caught) {\n    return fail(errorTransform ? errorTransform(caught) : (caught as E));\n  }\n}\n\n/**\n * Converts a Promise to a `Promise<Result<T, E>>`, catching rejections.\n *\n * @example\n * const result = await fromPromise(fetch(url), (e) => new NetworkError(e));\n */\nexport async function fromPromise<T, E = Error>(\n  promise: Promise<T>,\n  errorTransform?: (caught: unknown) => E,\n): Promise<Result<T, E>> {\n  try {\n    return ok(await promise);\n  } catch (caught) {\n    return fail(errorTransform ? errorTransform(caught) : (caught as E));\n  }\n}\n\n/**\n * Converts a nullable value to a Result.\n * Returns `ok(value)` if non-null/undefined, `fail(error)` otherwise.\n *\n * @example\n * const result = fromNullable(user, new NotFoundError('user'));\n */\nexport function fromNullable<T, E>(\n  value: T | null | undefined,\n  error: E,\n): Result<T, E> {\n  return value != null ? ok(value) : fail(error);\n}\n","import type { Result, RichResult } from './types.js';\n\ntype OkResult<T, E>   = Extract<Result<T, E>, { ok: true }>;\ntype FailResult<T, E> = Extract<Result<T, E>, { ok: false }>;\n\n/** Narrows a `Result<T, E>` to its success branch. */\nexport function isOk<T, E>(result: Result<T, E>): result is OkResult<T, E> {\n  return result.ok === true;\n}\n\n/** Narrows a `Result<T, E>` to its failure branch. */\nexport function isFail<T, E>(result: Result<T, E>): result is FailResult<T, E> {\n  return result.ok === false;\n}\n\n/** Returns `true` if the result carries observability metadata (`track()` output). */\nexport function isRich<T, E>(result: Result<T, E>): result is RichResult<T, E> {\n  return 'durationMs' in result;\n}\n","import type { Result, RichResult, TrackOptions } from './types.js';\nimport { ok, fail } from './constructors.js';\n\n/**\n * Executes an async (or sync) function and captures any thrown exception,\n * returning a `Result<T, E>` instead of propagating the error.\n *\n * @example\n * const result = await run(() => fetchUser(id));\n * const result = await run(() => fetchUser(id), (e) => new UserError(e));\n */\nexport async function run<T, E = Error>(\n  fn: () => T | Promise<T>,\n  errorTransform?: (caught: unknown) => E,\n): Promise<Result<T, E>> {\n  try {\n    return ok(await fn());\n  } catch (caught) {\n    return fail(errorTransform ? errorTransform(caught) : (caught as E));\n  }\n}\n\n/**\n * Like `run()` but also captures timing and metadata, returning a `RichResult<T, E>`.\n *\n * @example\n * const result = await track(() => fetchUser(id), { operation: 'user.fetch', tags: ['db'] });\n */\nexport async function track<T, E = Error>(\n  fn: () => T | Promise<T>,\n  options?: TrackOptions & { errorTransform?: (caught: unknown) => E },\n): Promise<RichResult<T, E>> {\n  const start     = performance.now();\n  const timestamp = new Date().toISOString();\n  const meta = {\n    durationMs:    0,\n    timestamp,\n    operation:     options?.operation,\n    correlationId: options?.correlationId,\n    tags:          options?.tags,\n  };\n\n  try {\n    const value = await fn();\n    return { ok: true, value, ...meta, durationMs: Math.round(performance.now() - start) };\n  } catch (caught) {\n    const error = options?.errorTransform ? options.errorTransform(caught) : (caught as E);\n    return { ok: false, error, ...meta, durationMs: Math.round(performance.now() - start) };\n  }\n}\n\n/**\n * Promotes a plain `Result<T, E>` to a `RichResult<T, E>` with a zero-duration snapshot.\n * Useful when you already have a Result and want to attach metadata.\n */\nexport function enrich<T, E>(result: Result<T, E>, options?: TrackOptions): RichResult<T, E> {\n  return {\n    ...result,\n    durationMs:    0,\n    timestamp:     new Date().toISOString(),\n    operation:     options?.operation,\n    correlationId: options?.correlationId,\n    tags:          options?.tags,\n  };\n}\n\n/**\n * Strips observability metadata from a `RichResult`, returning a plain `Result<T, E>`.\n */\nexport function simplify<T, E>(rich: RichResult<T, E>): Result<T, E> {\n  return rich.ok\n    ? { ok: true,  value: rich.value }\n    : { ok: false, error: rich.error };\n}\n"]}

package/dist/chunk-XLOUAMAH.js

@@ -0,0 +1,86 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/result/constructors.ts
+var ok = (value) => ({ ok: true, value });
+var fail = (error) => ({ ok: false, error });
+function fromThrowable(fn, errorTransform) {
+  try {
+    return ok(fn());
+  } catch (caught) {
+    return fail(errorTransform ? errorTransform(caught) : caught);
+  }
+}
+async function fromPromise(promise, errorTransform) {
+  try {
+    return ok(await promise);
+  } catch (caught) {
+    return fail(errorTransform ? errorTransform(caught) : caught);
+  }
+}
+function fromNullable(value, error) {
+  return value != null ? ok(value) : fail(error);
+}
+
+// src/result/guards.ts
+function isOk(result) {
+  return result.ok === true;
+}
+function isFail(result) {
+  return result.ok === false;
+}
+function isRich(result) {
+  return "durationMs" in result;
+}
+
+// src/result/run.ts
+async function run(fn, errorTransform) {
+  try {
+    return ok(await fn());
+  } catch (caught) {
+    return fail(errorTransform ? errorTransform(caught) : caught);
+  }
+}
+async function track(fn, options) {
+  const start = performance.now();
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const meta = {
+    durationMs: 0,
+    timestamp,
+    operation: options?.operation,
+    correlationId: options?.correlationId,
+    tags: options?.tags
+  };
+  try {
+    const value = await fn();
+    return { ok: true, value, ...meta, durationMs: Math.round(performance.now() - start) };
+  } catch (caught) {
+    const error = options?.errorTransform ? options.errorTransform(caught) : caught;
+    return { ok: false, error, ...meta, durationMs: Math.round(performance.now() - start) };
+  }
+}
+function enrich(result, options) {
+  return {
+    ...result,
+    durationMs: 0,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    operation: options?.operation,
+    correlationId: options?.correlationId,
+    tags: options?.tags
+  };
+}
+function simplify(rich) {
+  return rich.ok ? { ok: true, value: rich.value } : { ok: false, error: rich.error };
+}
+
+export { __decorateClass, enrich, fail, fromNullable, fromPromise, fromThrowable, isFail, isOk, isRich, ok, run, simplify, track };
+//# sourceMappingURL=chunk-XLOUAMAH.js.map
+//# sourceMappingURL=chunk-XLOUAMAH.js.map

package/dist/chunk-XLOUAMAH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/result/constructors.ts","../src/result/guards.ts","../src/result/run.ts"],"names":[],"mappings":"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","file":"chunk-XLOUAMAH.js","sourcesContent":["import type { Result } from './types.js';\n\n/** Creates a successful Result. */\nexport const ok = <T, E = never>(value: T): Result<T, E> =>\n  ({ ok: true, value });\n\n/** Creates a failed Result. */\nexport const fail = <T = never, E = Error>(error: E): Result<T, E> =>\n  ({ ok: false, error });\n\n/**\n * Wraps a synchronous throwable function. Catches any thrown value and\n * passes it through `errorTransform` (defaults to identity cast).\n *\n * @example\n * const result = fromThrowable(() => JSON.parse(raw), (e) => new ParseError(e));\n */\nexport function fromThrowable<T, E = Error>(\n  fn: () => T,\n  errorTransform?: (caught: unknown) => E,\n): Result<T, E> {\n  try {\n    return ok(fn());\n  } catch (caught) {\n    return fail(errorTransform ? errorTransform(caught) : (caught as E));\n  }\n}\n\n/**\n * Converts a Promise to a `Promise<Result<T, E>>`, catching rejections.\n *\n * @example\n * const result = await fromPromise(fetch(url), (e) => new NetworkError(e));\n */\nexport async function fromPromise<T, E = Error>(\n  promise: Promise<T>,\n  errorTransform?: (caught: unknown) => E,\n): Promise<Result<T, E>> {\n  try {\n    return ok(await promise);\n  } catch (caught) {\n    return fail(errorTransform ? errorTransform(caught) : (caught as E));\n  }\n}\n\n/**\n * Converts a nullable value to a Result.\n * Returns `ok(value)` if non-null/undefined, `fail(error)` otherwise.\n *\n * @example\n * const result = fromNullable(user, new NotFoundError('user'));\n */\nexport function fromNullable<T, E>(\n  value: T | null | undefined,\n  error: E,\n): Result<T, E> {\n  return value != null ? ok(value) : fail(error);\n}\n","import type { Result, RichResult } from './types.js';\n\ntype OkResult<T, E>   = Extract<Result<T, E>, { ok: true }>;\ntype FailResult<T, E> = Extract<Result<T, E>, { ok: false }>;\n\n/** Narrows a `Result<T, E>` to its success branch. */\nexport function isOk<T, E>(result: Result<T, E>): result is OkResult<T, E> {\n  return result.ok === true;\n}\n\n/** Narrows a `Result<T, E>` to its failure branch. */\nexport function isFail<T, E>(result: Result<T, E>): result is FailResult<T, E> {\n  return result.ok === false;\n}\n\n/** Returns `true` if the result carries observability metadata (`track()` output). */\nexport function isRich<T, E>(result: Result<T, E>): result is RichResult<T, E> {\n  return 'durationMs' in result;\n}\n","import type { Result, RichResult, TrackOptions } from './types.js';\nimport { ok, fail } from './constructors.js';\n\n/**\n * Executes an async (or sync) function and captures any thrown exception,\n * returning a `Result<T, E>` instead of propagating the error.\n *\n * @example\n * const result = await run(() => fetchUser(id));\n * const result = await run(() => fetchUser(id), (e) => new UserError(e));\n */\nexport async function run<T, E = Error>(\n  fn: () => T | Promise<T>,\n  errorTransform?: (caught: unknown) => E,\n): Promise<Result<T, E>> {\n  try {\n    return ok(await fn());\n  } catch (caught) {\n    return fail(errorTransform ? errorTransform(caught) : (caught as E));\n  }\n}\n\n/**\n * Like `run()` but also captures timing and metadata, returning a `RichResult<T, E>`.\n *\n * @example\n * const result = await track(() => fetchUser(id), { operation: 'user.fetch', tags: ['db'] });\n */\nexport async function track<T, E = Error>(\n  fn: () => T | Promise<T>,\n  options?: TrackOptions & { errorTransform?: (caught: unknown) => E },\n): Promise<RichResult<T, E>> {\n  const start     = performance.now();\n  const timestamp = new Date().toISOString();\n  const meta = {\n    durationMs:    0,\n    timestamp,\n    operation:     options?.operation,\n    correlationId: options?.correlationId,\n    tags:          options?.tags,\n  };\n\n  try {\n    const value = await fn();\n    return { ok: true, value, ...meta, durationMs: Math.round(performance.now() - start) };\n  } catch (caught) {\n    const error = options?.errorTransform ? options.errorTransform(caught) : (caught as E);\n    return { ok: false, error, ...meta, durationMs: Math.round(performance.now() - start) };\n  }\n}\n\n/**\n * Promotes a plain `Result<T, E>` to a `RichResult<T, E>` with a zero-duration snapshot.\n * Useful when you already have a Result and want to attach metadata.\n */\nexport function enrich<T, E>(result: Result<T, E>, options?: TrackOptions): RichResult<T, E> {\n  return {\n    ...result,\n    durationMs:    0,\n    timestamp:     new Date().toISOString(),\n    operation:     options?.operation,\n    correlationId: options?.correlationId,\n    tags:          options?.tags,\n  };\n}\n\n/**\n * Strips observability metadata from a `RichResult`, returning a plain `Result<T, E>`.\n */\nexport function simplify<T, E>(rich: RichResult<T, E>): Result<T, E> {\n  return rich.ok\n    ? { ok: true,  value: rich.value }\n    : { ok: false, error: rich.error };\n}\n"]}

package/dist/index.cjs

@@ -1,43 +1,13 @@
 'use strict';
 
-// src/result/constructors.ts
-var ok = (value) => ({ ok: true, value });
-var fail = (error) => ({ ok: false, error });
-function fromThrowable(fn, errorTransform) {
-  try {
-    return ok(fn());
-  } catch (caught) {
-    return fail(errorTransform ? errorTransform(caught) : caught);
-  }
-}
-async function fromPromise(promise, errorTransform) {
-  try {
-    return ok(await promise);
-  } catch (caught) {
-    return fail(errorTransform ? errorTransform(caught) : caught);
-  }
-}
-function fromNullable(value, error) {
-  return value != null ? ok(value) : fail(error);
-}
-
-// src/result/guards.ts
-function isOk(result) {
-  return result.ok === true;
-}
-function isFail(result) {
-  return result.ok === false;
-}
-function isRich(result) {
-  return "durationMs" in result;
-}
+var chunkGCGL2Y6D_cjs = require('./chunk-GCGL2Y6D.cjs');
 
 // src/result/operations.ts
 function map(result, fn) {
-  return result.ok ? ok(fn(result.value)) : result;
+  return result.ok ? chunkGCGL2Y6D_cjs.ok(fn(result.value)) : result;
 }
 function mapError(result, fn) {
-  return result.ok ? result : fail(fn(result.error));
+  return result.ok ? result : chunkGCGL2Y6D_cjs.fail(fn(result.error));
 }
 function flatMap(result, fn) {
   return result.ok ? fn(result.value) : result;
@@ -47,7 +17,7 @@ async function flatMapAsync(result, fn) {
 }
 async function mapAsync(result, fn) {
   if (!result.ok) return Promise.resolve(result);
-  return ok(await fn(result.value));
+  return chunkGCGL2Y6D_cjs.ok(await fn(result.value));
 }
 function match(result, handlers) {
   return result.ok ? handlers.ok(result.value) : handlers.fail(result.error);
@@ -89,46 +59,6 @@ function toUndefined(result) {
   return result.ok ? result.value : void 0;
 }
 
-// src/result/run.ts
-async function run(fn, errorTransform) {
-  try {
-    return ok(await fn());
-  } catch (caught) {
-    return fail(errorTransform ? errorTransform(caught) : caught);
-  }
-}
-async function track(fn, options) {
-  const start = performance.now();
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-  const meta = {
-    durationMs: 0,
-    timestamp,
-    operation: options?.operation,
-    correlationId: options?.correlationId,
-    tags: options?.tags
-  };
-  try {
-    const value = await fn();
-    return { ok: true, value, ...meta, durationMs: Math.round(performance.now() - start) };
-  } catch (caught) {
-    const error = options?.errorTransform ? options.errorTransform(caught) : caught;
-    return { ok: false, error, ...meta, durationMs: Math.round(performance.now() - start) };
-  }
-}
-function enrich(result, options) {
-  return {
-    ...result,
-    durationMs: 0,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    operation: options?.operation,
-    correlationId: options?.correlationId,
-    tags: options?.tags
-  };
-}
-function simplify(rich) {
-  return rich.ok ? { ok: true, value: rich.value } : { ok: false, error: rich.error };
-}
-
 // src/result/resilience.ts
 async function retry(fn, options) {
   let last;
@@ -150,20 +80,27 @@ async function retryWithBackoff(fn, options) {
     if (attempt === options.attempts) break;
     if (options.shouldRetry && !options.shouldRetry(last.error, attempt)) break;
     options.onRetry?.(last.error, attempt);
-    const delay = Math.min(
-      (options.delayMs ?? 100) * Math.pow(2, attempt - 1),
-      options.maxDelayMs ?? 3e4
-    );
-    await sleep(delay);
+    await sleep(computeBackoffDelay(attempt, options));
   }
   return last;
 }
 async function withTimeout(fn, ms, timeoutError) {
   const timer = new Promise(
-    (resolve) => setTimeout(() => resolve(fail(timeoutError)), ms)
+    (resolve) => setTimeout(() => resolve(chunkGCGL2Y6D_cjs.fail(timeoutError)), ms)
   );
   return Promise.race([fn(), timer]);
 }
+function computeBackoffDelay(attempt, options) {
+  const base = (options.delayMs ?? 100) * Math.pow(2, attempt - 1);
+  const capped = Math.min(base, options.maxDelayMs ?? 3e4);
+  const { jitter } = options;
+  if (!jitter) return capped;
+  if (jitter === true) {
+    return Math.random() * capped;
+  }
+  const noise = (Math.random() * 2 - 1) * capped * jitter;
+  return Math.max(0, Math.min(capped + noise, options.maxDelayMs ?? 3e4));
+}
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/result/combinators.ts
@@ -173,7 +110,7 @@ function all(results) {
     if (!r.ok) return r;
     values.push(r.value);
   }
-  return ok(values);
+  return chunkGCGL2Y6D_cjs.ok(values);
 }
 async function any(operations) {
   let last;
@@ -210,13 +147,13 @@ function traverse(items, fn) {
 function combine2(r1, r2) {
   if (!r1.ok) return r1;
   if (!r2.ok) return r2;
-  return ok([r1.value, r2.value]);
+  return chunkGCGL2Y6D_cjs.ok([r1.value, r2.value]);
 }
 function combine3(r1, r2, r3) {
   if (!r1.ok) return r1;
   if (!r2.ok) return r2;
   if (!r3.ok) return r3;
-  return ok([r1.value, r2.value, r3.value]);
+  return chunkGCGL2Y6D_cjs.ok([r1.value, r2.value, r3.value]);
 }
 
 // src/result/flow.ts
@@ -231,17 +168,17 @@ var Flow = class _Flow {
   }
   /** Start an empty pipeline (value is `undefined`). */
   static start() {
-    return new _Flow(ok(void 0));
+    return new _Flow(chunkGCGL2Y6D_cjs.ok(void 0));
   }
   /** Maps the success value. Skipped on failure. */
   map(fn) {
     if (!this._result.ok) return new _Flow(this._result);
-    return new _Flow(ok(fn(this._result.value)));
+    return new _Flow(chunkGCGL2Y6D_cjs.ok(fn(this._result.value)));
   }
   /** Maps the error value. Skipped on success. */
   mapError(fn) {
     if (this._result.ok) return new _Flow(this._result);
-    return new _Flow(fail(fn(this._result.error)));
+    return new _Flow(chunkGCGL2Y6D_cjs.fail(fn(this._result.error)));
   }
   /** Chains a Result-returning function. Skipped on failure. */
   flatMap(fn) {
@@ -251,7 +188,7 @@ var Flow = class _Flow {
   /** Filters the success value. Becomes `fail(error)` if predicate is false. */
   filter(pred, error) {
     if (!this._result.ok) return this;
-    return pred(this._result.value) ? this : new _Flow(fail(error));
+    return pred(this._result.value) ? this : new _Flow(chunkGCGL2Y6D_cjs.fail(error));
   }
   /** Runs a side effect on success; returns `this` unchanged. */
   tap(fn) {
@@ -269,7 +206,7 @@ var Flow = class _Flow {
    */
   recover(fn) {
     if (this._result.ok) return new _Flow(this._result);
-    return new _Flow(ok(fn(this._result.error)));
+    return new _Flow(chunkGCGL2Y6D_cjs.ok(fn(this._result.error)));
   }
   /** Exhaustive pattern match — always produces a value. */
   match(handlers) {
@@ -284,7 +221,7 @@ var Flow = class _Flow {
    * Throws if the result has no observability metadata.
    */
   getRichResult() {
-    if (!isRich(this._result)) throw new Error("Result is not a RichResult");
+    if (!chunkGCGL2Y6D_cjs.isRich(this._result)) throw new Error("Result is not a RichResult");
     return this._result;
   }
   isOk() {
@@ -295,41 +232,77 @@ var Flow = class _Flow {
   }
 };
 
+Object.defineProperty(exports, "enrich", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.enrich; }
+});
+Object.defineProperty(exports, "fail", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.fail; }
+});
+Object.defineProperty(exports, "fromNullable", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.fromNullable; }
+});
+Object.defineProperty(exports, "fromPromise", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.fromPromise; }
+});
+Object.defineProperty(exports, "fromThrowable", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.fromThrowable; }
+});
+Object.defineProperty(exports, "isFail", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.isFail; }
+});
+Object.defineProperty(exports, "isOk", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.isOk; }
+});
+Object.defineProperty(exports, "isRich", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.isRich; }
+});
+Object.defineProperty(exports, "ok", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.ok; }
+});
+Object.defineProperty(exports, "run", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.run; }
+});
+Object.defineProperty(exports, "simplify", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.simplify; }
+});
+Object.defineProperty(exports, "track", {
+  enumerable: true,
+  get: function () { return chunkGCGL2Y6D_cjs.track; }
+});
 exports.Flow = Flow;
 exports.all = all;
 exports.any = any;
 exports.collect = collect;
 exports.combine2 = combine2;
 exports.combine3 = combine3;
-exports.enrich = enrich;
 exports.expect = expect;
-exports.fail = fail;
 exports.flatMap = flatMap;
 exports.flatMapAsync = flatMapAsync;
 exports.fold = fold;
-exports.fromNullable = fromNullable;
-exports.fromPromise = fromPromise;
-exports.fromThrowable = fromThrowable;
-exports.isFail = isFail;
-exports.isOk = isOk;
-exports.isRich = isRich;
 exports.map = map;
 exports.mapAsync = mapAsync;
 exports.mapError = mapError;
 exports.match = match;
-exports.ok = ok;
 exports.parallel = parallel;
 exports.partition = partition;
 exports.retry = retry;
 exports.retryWithBackoff = retryWithBackoff;
-exports.run = run;
-exports.simplify = simplify;
 exports.tap = tap;
 exports.tapError = tapError;
 exports.toNullable = toNullable;
 exports.toPromise = toPromise;
 exports.toUndefined = toUndefined;
-exports.track = track;
 exports.traverse = traverse;
 exports.unwrap = unwrap;
 exports.unwrapError = unwrapError;