@nicolastoulemont/std 0.1.0

package/dist/either-CnOBUH7a.mjs

@@ -0,0 +1,598 @@
+import { t as Result } from "./result-C5tPWR60.mjs";
+import { t as Option } from "./option-CKHDOVea.mjs";
+
+//#region src/either/either.ts
+/**
+* Create a right Either value (success/preferred path).
+*
+* By convention, right represents the correct/preferred outcome.
+*
+* @param value - The right value
+* @returns An Either in the right state
+*
+* @example
+* ```ts
+* const result = right(42)
+* // => { right: true, value: 42 }
+* ```
+*/
+const right = (value) => ({
+	right: true,
+	value,
+	*[Symbol.iterator]() {
+		return value;
+	}
+});
+/**
+* Create a left Either value (alternative path).
+*
+* By convention, left represents the alternative outcome.
+* Unlike Result's err(), left doesn't imply an error.
+*
+* @param value - The left value
+* @returns An Either in the left state
+*
+* @example
+* ```ts
+* const cached = left({ source: "cache", data: cachedValue })
+* // => { right: false, value: { source: "cache", data: cachedValue } }
+* ```
+*/
+const left = (value) => ({
+	right: false,
+	value,
+	*[Symbol.iterator]() {
+		yield value;
+		throw new Error("Unreachable: Do should short-circuit on left");
+	}
+});
+/**
+* Type guard to check if an Either is in the right state.
+*
+* @param either - The Either to check
+* @returns True if right, false if left (with type narrowing)
+*
+* @example
+* ```ts
+* const either = right(42)
+* if (isRight(either)) {
+*   console.log(either.value) // Type: number
+* }
+* ```
+*/
+const isRight = (either) => either.right;
+/**
+* Type guard to check if an Either is in the left state.
+*
+* @param either - The Either to check
+* @returns True if left, false if right (with type narrowing)
+*
+* @example
+* ```ts
+* const either = left("error")
+* if (isLeft(either)) {
+*   console.log(either.value) // Type: string
+* }
+* ```
+*/
+const isLeft = (either) => !either.right;
+/**
+* Transform the right value of an Either.
+* Left values pass through unchanged.
+*
+* Curried for use with pipe(). Supports async functions.
+*
+* @param fn - Transformation function for right values
+* @returns A curried function that transforms an Either
+*
+* @example
+* ```ts
+* // Sync usage
+* pipe(
+*   right(5),
+*   map(x => x * 2)
+* ) // => right(10)
+*
+* pipe(
+*   left("error"),
+*   map(x => x * 2)
+* ) // => left("error")
+*
+* // Async usage
+* await pipe(
+*   right(userId),
+*   map(async id => await fetchUser(id))
+* ) // => Promise<Either<L, User>>
+* ```
+*/
+const map = (fn) => (either) => {
+	if (!either.right) return either;
+	const mapped = fn(either.value);
+	if (mapped instanceof Promise) return mapped.then(right);
+	return right(mapped);
+};
+/**
+* Transform the left value of an Either.
+* Right values pass through unchanged.
+*
+* Curried for use with pipe(). Supports async functions.
+*
+* @param fn - Transformation function for left values
+* @returns A curried function that transforms an Either
+*
+* @example
+* ```ts
+* pipe(
+*   left("error"),
+*   mapLeft(e => e.toUpperCase())
+* ) // => left("ERROR")
+*
+* pipe(
+*   right(42),
+*   mapLeft(e => e.toUpperCase())
+* ) // => right(42)
+* ```
+*/
+const mapLeft = (fn) => (either) => {
+	if (either.right) return either;
+	const mapped = fn(either.value);
+	if (mapped instanceof Promise) return mapped.then(left);
+	return left(mapped);
+};
+/**
+* Transform both sides of an Either simultaneously.
+* Unique to Either - not available in Result/Option.
+*
+* Curried for use with pipe(). Supports async functions.
+*
+* @param fnLeft - Transformation function for left values
+* @param fnRight - Transformation function for right values
+* @returns A curried function that transforms an Either
+*
+* @example
+* ```ts
+* pipe(
+*   right(5),
+*   bimap(
+*     e => e.toUpperCase(),
+*     x => x * 2
+*   )
+* ) // => right(10)
+*
+* pipe(
+*   left("error"),
+*   bimap(
+*     e => e.toUpperCase(),
+*     x => x * 2
+*   )
+* ) // => left("ERROR")
+* ```
+*/
+const bimap = (fnLeft, fnRight) => (either) => {
+	if (either.right) {
+		const mapped$1 = fnRight(either.value);
+		if (mapped$1 instanceof Promise) return mapped$1.then(right);
+		return right(mapped$1);
+	}
+	const mapped = fnLeft(either.value);
+	if (mapped instanceof Promise) return mapped.then(left);
+	return left(mapped);
+};
+/**
+* Chain operations that return Either.
+* Left values short-circuit the chain.
+*
+* Curried for use with pipe(). Supports async functions.
+* Combines left error unions.
+*
+* @param fn - Function that returns an Either
+* @returns A curried function that chains Eithers
+*
+* @example
+* ```ts
+* // Sync usage
+* pipe(
+*   right(5),
+*   flatMap(x => right(x * 2)),
+*   flatMap(x => right(x + 1))
+* ) // => right(11)
+*
+* pipe(
+*   right(5),
+*   flatMap(x => left("error")),
+*   flatMap(x => right(x + 1)) // Not executed
+* ) // => left("error")
+*
+* // Async usage
+* await pipe(
+*   right(userId),
+*   flatMap(async id => right(await fetchUser(id))),
+*   flatMap(async user => right(await enrichProfile(user)))
+* ) // => Promise<Either<L, EnrichedUser>>
+* ```
+*/
+const flatMap = (fn) => (either) => {
+	if (!either.right) return either;
+	return fn(either.value);
+};
+/**
+* Execute a side effect on right values without modifying the Either.
+* Left values pass through unchanged.
+*
+* Curried for use with pipe(). Supports async functions.
+*
+* @param fn - Side effect function for right values
+* @returns A curried function that executes side effects
+*
+* @example
+* ```ts
+* pipe(
+*   right(42),
+*   tap(x => console.log(x)), // Logs: 42
+*   map(x => x * 2)
+* ) // => right(84)
+* ```
+*/
+const tap = (fn) => (either) => {
+	if (!either.right) return either;
+	const result = fn(either.value);
+	if (result instanceof Promise) return result.then(() => either);
+	return either;
+};
+/**
+* Execute a side effect on left values without modifying the Either.
+* Right values pass through unchanged.
+*
+* Curried for use with pipe(). Supports async functions.
+*
+* @param fn - Side effect function for left values
+* @returns A curried function that executes side effects
+*
+* @example
+* ```ts
+* pipe(
+*   left("error"),
+*   tapLeft(e => console.error(e)), // Logs: error
+*   mapLeft(e => e.toUpperCase())
+* ) // => left("ERROR")
+* ```
+*/
+const tapLeft = (fn) => (either) => {
+	if (either.right) return either;
+	const result = fn(either.value);
+	if (result instanceof Promise) return result.then(() => either);
+	return either;
+};
+/**
+* Recover from a left value by providing an alternative Either.
+* Right values pass through unchanged.
+*
+* Curried for use with pipe(). Supports async functions.
+* Combines right value unions.
+*
+* @param fn - Function that returns an alternative Either
+* @returns A curried function that recovers from left
+*
+* @example
+* ```ts
+* pipe(
+*   left("error"),
+*   orElse(() => right(42))
+* ) // => right(42)
+*
+* pipe(
+*   right(10),
+*   orElse(() => right(42))
+* ) // => right(10)
+* ```
+*/
+const orElse = (fn) => (either) => {
+	if (either.right) return either;
+	return fn(either.value);
+};
+/**
+* Swap left and right values.
+* Unique to Either - not available in Result/Option.
+*
+* Curried for use with pipe().
+*
+* @returns A curried function that swaps left and right
+*
+* @example
+* ```ts
+* pipe(
+*   left("error"),
+*   swap()
+* ) // => right("error")
+*
+* pipe(
+*   right(42),
+*   swap()
+* ) // => left(42)
+* ```
+*/
+const swap = () => (either) => either.right ? left(either.value) : right(either.value);
+/**
+* Filter right values based on a predicate.
+* Failed predicates convert to left with onFail callback.
+* Left values pass through unchanged.
+*
+* Curried for use with pipe().
+*
+* @param predicate - Function to test right values
+* @param onFail - Function to produce left value on failure
+* @returns A curried function that filters an Either
+*
+* @example
+* ```ts
+* pipe(
+*   right(5),
+*   filter(x => x > 3, x => `${x} is too small`)
+* ) // => right(5)
+*
+* pipe(
+*   right(2),
+*   filter(x => x > 3, x => `${x} is too small`)
+* ) // => left("2 is too small")
+* ```
+*/
+const filter = (predicate, onFail) => (either) => {
+	if (!either.right) return either;
+	return predicate(either.value) ? either : left(onFail(either.value));
+};
+function all(eithers) {
+	if (Array.isArray(eithers)) {
+		const values = [];
+		for (const either of eithers) {
+			if (!either.right) return either;
+			values.push(either.value);
+		}
+		return right(values);
+	}
+	const result = {};
+	for (const key in eithers) {
+		const either = eithers[key];
+		if (!either.right) return either;
+		result[key] = either.value;
+	}
+	return right(result);
+}
+/**
+* Extract the right value or return a default.
+*
+* Curried for use with pipe().
+*
+* @param defaultValue - Value to return if Either is left
+* @returns A curried function that extracts the value
+*
+* @example
+* ```ts
+* pipe(
+*   right(42),
+*   unwrapOr(0)
+* ) // => 42
+*
+* pipe(
+*   left("error"),
+*   unwrapOr(0)
+* ) // => 0
+* ```
+*/
+const unwrapOr = (defaultValue) => (either) => either.right ? either.value : defaultValue;
+/**
+* Extract the right value or compute one from the left value.
+*
+* Curried for use with pipe().
+*
+* @param fn - Function to compute default from left value
+* @returns A curried function that extracts the value
+*
+* @example
+* ```ts
+* pipe(
+*   right(42),
+*   unwrapOrElse(() => 0)
+* ) // => 42
+*
+* pipe(
+*   left("error"),
+*   unwrapOrElse(e => e.length)
+* ) // => 5
+* ```
+*/
+const unwrapOrElse = (fn) => (either) => either.right ? either.value : fn(either.value);
+/**
+* Pattern match on an Either with handlers for both cases.
+*
+* Curried for use with pipe().
+*
+* @param handlers - Object with left and right handler functions
+* @returns A curried function that pattern matches
+*
+* @example
+* ```ts
+* pipe(
+*   right(42),
+*   match({
+*     left: e => `Error: ${e}`,
+*     right: x => `Success: ${x}`
+*   })
+* ) // => "Success: 42"
+* ```
+*/
+const match = (handlers) => (either) => either.right ? handlers.right(either.value) : handlers.left(either.value);
+/**
+* Convert a Result to an Either.
+* Result's ok becomes right, err becomes left.
+*
+* @param result - The Result to convert
+* @returns An Either with the same semantics
+*
+* @example
+* ```ts
+* fromResult(Result.ok(42)) // => right(42)
+* fromResult(Result.err("error")) // => left("error")
+* ```
+*/
+const fromResult = (result) => result.ok ? right(result.value) : left(result.error);
+/**
+* Convert an Either to a Result.
+* Either's right becomes ok, left becomes err.
+*
+* Curried for use with pipe().
+*
+* @param either - The Either to convert
+* @returns A Result with error semantics
+*
+* @example
+* ```ts
+* pipe(
+*   right(42),
+*   toResult
+* ) // => Result.ok(42)
+*
+* pipe(
+*   left("error"),
+*   toResult
+* ) // => Result.err("error")
+* ```
+*/
+const toResult = (either) => either.right ? Result.ok(either.value) : Result.err(either.value);
+/**
+* Convert an Option to an Either.
+* Option's some becomes right, none becomes left with onNone callback.
+*
+* @param option - The Option to convert
+* @param onNone - Function to produce left value for none
+* @returns An Either
+*
+* @example
+* ```ts
+* fromOption(Option.some(42), () => "not found") // => right(42)
+* fromOption(Option.none(), () => "not found") // => left("not found")
+* ```
+*/
+const fromOption = (option, onNone) => option.some ? right(option.value) : left(onNone());
+/**
+* Convert an Either to an Option.
+* Either's right becomes some, left is discarded.
+*
+* Curried for use with pipe().
+*
+* @param either - The Either to convert
+* @returns An Option (left value is discarded)
+*
+* @example
+* ```ts
+* pipe(
+*   right(42),
+*   toOption
+* ) // => Option.some(42)
+*
+* pipe(
+*   left("error"),
+*   toOption
+* ) // => Option.none()
+* ```
+*/
+const toOption = (either) => either.right ? Option.some(either.value) : Option.none();
+/**
+* Convert a nullable value to an Either.
+* null/undefined becomes left with onNull callback, otherwise right.
+*
+* @param value - The nullable value
+* @param onNull - Function to produce left value for null/undefined
+* @returns An Either
+*
+* @example
+* ```ts
+* fromNullable(42, () => "not found") // => right(42)
+* fromNullable(null, () => "not found") // => left("not found")
+* fromNullable(undefined, () => "not found") // => left("not found")
+* ```
+*/
+const fromNullable = (value, onNull) => value === null || value === void 0 ? left(onNull()) : right(value);
+/**
+* Create an Either from a predicate.
+* Predicate success becomes right, failure becomes left with onFail callback.
+*
+* @param value - The value to test
+* @param predicate - Function to test the value
+* @param onFail - Function to produce left value on failure
+* @returns An Either
+*
+* @example
+* ```ts
+* fromPredicate(5, x => x > 3, x => `${x} is too small`)
+* // => right(5)
+*
+* fromPredicate(2, x => x > 3, x => `${x} is too small`)
+* // => left("2 is too small")
+* ```
+*/
+const fromPredicate = (value, predicate, onFail) => predicate(value) ? right(value) : left(onFail(value));
+/**
+* Either namespace containing all utility functions for working with Either types.
+*
+* Either represents a value that can be one of two types: Left<L> or Right<R>.
+* By convention, Right is the "success" or preferred path, while Left represents
+* an alternative outcome (not necessarily an error, unlike Result).
+*
+* Use Either when both outcomes are valid and meaningful, not just success/failure.
+* For error handling, prefer Result instead.
+*
+* @see {@link Result} for success/error semantics
+* @see {@link Option} for presence/absence semantics
+*
+* @example
+* ```ts
+* import { Either, pipe } from '@repo/std'
+* import type { Either as EitherType } from '@repo/std'
+*
+* // Either for branching logic (cache vs fresh data)
+* const fetchOrCache = (id: number): EitherType<CachedData, FreshData> =>
+*   cache.has(id) ? Either.left(cache.get(id)) : Either.right(fetch(id))
+*
+* const result = pipe(
+*   fetchOrCache(1),
+*   Either.map(data => data.value),
+*   Either.unwrapOr(defaultValue)
+* )
+*
+* // Async example
+* const processed = await pipe(
+*   Either.right(userId),
+*   Either.map(async id => await fetchUser(id)),
+*   Either.flatMap(async user => Either.right(await enrichUser(user)))
+* )
+* ```
+*/
+const Either = {
+	left,
+	right,
+	isLeft,
+	isRight,
+	map,
+	mapLeft,
+	bimap,
+	flatMap,
+	tap,
+	tapLeft,
+	orElse,
+	swap,
+	filter,
+	all,
+	unwrapOr,
+	unwrapOrElse,
+	match,
+	fromResult,
+	toResult,
+	fromOption,
+	toOption,
+	fromNullable,
+	fromPredicate
+};
+
+//#endregion
+export { Either as t };
+//# sourceMappingURL=either-CnOBUH7a.mjs.map

package/dist/either-CnOBUH7a.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"either-CnOBUH7a.mjs","names":["mapped"],"sources":["../src/either/either.ts"],"sourcesContent":["import { Option } from \"../option\"\nimport type { Option as OptionType } from \"../option/option.types\"\nimport { Result } from \"../result\"\nimport type { Result as ResultType } from \"../result/result.types\"\nimport type {\n  AllArrayReturn,\n  AllObjectReturn,\n  Either as EitherType,\n  EitherBimap,\n  EitherFilter,\n  EitherFlatMap,\n  EitherMap,\n  EitherMapLeft,\n  EitherOrElse,\n  EitherTap,\n  EitherTapLeft,\n} from \"./either.types\"\n\n// ============================================================================\n// Constructors\n// ============================================================================\n\n/**\n * Create a right Either value (success/preferred path).\n *\n * By convention, right represents the correct/preferred outcome.\n *\n * @param value - The right value\n * @returns An Either in the right state\n *\n * @example\n * ```ts\n * const result = right(42)\n * // => { right: true, value: 42 }\n * ```\n */\nexport const right = <R>(value: R): EitherType<never, R> => ({\n  right: true,\n  value,\n  // oxlint-disable-next-line require-yield\n  *[Symbol.iterator](): Generator<never, R, unknown> {\n    return value\n  },\n})\n\n/**\n * Create a left Either value (alternative path).\n *\n * By convention, left represents the alternative outcome.\n * Unlike Result's err(), left doesn't imply an error.\n *\n * @param value - The left value\n * @returns An Either in the left state\n *\n * @example\n * ```ts\n * const cached = left({ source: \"cache\", data: cachedValue })\n * // => { right: false, value: { source: \"cache\", data: cachedValue } }\n * ```\n */\nexport const left = <L>(value: L): EitherType<L, never> => ({\n  right: false,\n  value,\n  *[Symbol.iterator](): Generator<L, never, unknown> {\n    yield value\n    throw new Error(\"Unreachable: Do should short-circuit on left\")\n  },\n})\n\n// ============================================================================\n// Type Guards\n// ============================================================================\n\n/**\n * Type guard to check if an Either is in the right state.\n *\n * @param either - The Either to check\n * @returns True if right, false if left (with type narrowing)\n *\n * @example\n * ```ts\n * const either = right(42)\n * if (isRight(either)) {\n *   console.log(either.value) // Type: number\n * }\n * ```\n */\nexport const isRight = <L, R>(either: EitherType<L, R>): either is Extract<EitherType<L, R>, { right: true }> =>\n  either.right\n\n/**\n * Type guard to check if an Either is in the left state.\n *\n * @param either - The Either to check\n * @returns True if left, false if right (with type narrowing)\n *\n * @example\n * ```ts\n * const either = left(\"error\")\n * if (isLeft(either)) {\n *   console.log(either.value) // Type: string\n * }\n * ```\n */\nexport const isLeft = <L, R>(either: EitherType<L, R>): either is Extract<EitherType<L, R>, { right: false }> =>\n  !either.right\n\n// ============================================================================\n// Right-biased Transformations\n// ============================================================================\n\n/**\n * Transform the right value of an Either.\n * Left values pass through unchanged.\n *\n * Curried for use with pipe(). Supports async functions.\n *\n * @param fn - Transformation function for right values\n * @returns A curried function that transforms an Either\n *\n * @example\n * ```ts\n * // Sync usage\n * pipe(\n *   right(5),\n *   map(x => x * 2)\n * ) // => right(10)\n *\n * pipe(\n *   left(\"error\"),\n *   map(x => x * 2)\n * ) // => left(\"error\")\n *\n * // Async usage\n * await pipe(\n *   right(userId),\n *   map(async id => await fetchUser(id))\n * ) // => Promise<Either<L, User>>\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const map: EitherMap = (fn) => (either) => {\n  if (!either.right) return either as any\n  const mapped = fn(either.value)\n  if (mapped instanceof Promise) {\n    return mapped.then(right) as any\n  }\n  return right(mapped) as any\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n\n/**\n * Transform the left value of an Either.\n * Right values pass through unchanged.\n *\n * Curried for use with pipe(). Supports async functions.\n *\n * @param fn - Transformation function for left values\n * @returns A curried function that transforms an Either\n *\n * @example\n * ```ts\n * pipe(\n *   left(\"error\"),\n *   mapLeft(e => e.toUpperCase())\n * ) // => left(\"ERROR\")\n *\n * pipe(\n *   right(42),\n *   mapLeft(e => e.toUpperCase())\n * ) // => right(42)\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const mapLeft: EitherMapLeft = (fn) => (either) => {\n  if (either.right) return either as any\n  const mapped = fn(either.value)\n  if (mapped instanceof Promise) {\n    return mapped.then(left) as any\n  }\n  return left(mapped) as any\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n/**\n * Transform both sides of an Either simultaneously.\n * Unique to Either - not available in Result/Option.\n *\n * Curried for use with pipe(). Supports async functions.\n *\n * @param fnLeft - Transformation function for left values\n * @param fnRight - Transformation function for right values\n * @returns A curried function that transforms an Either\n *\n * @example\n * ```ts\n * pipe(\n *   right(5),\n *   bimap(\n *     e => e.toUpperCase(),\n *     x => x * 2\n *   )\n * ) // => right(10)\n *\n * pipe(\n *   left(\"error\"),\n *   bimap(\n *     e => e.toUpperCase(),\n *     x => x * 2\n *   )\n * ) // => left(\"ERROR\")\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const bimap: EitherBimap = (fnLeft, fnRight) => (either) => {\n  if (either.right) {\n    const mapped = fnRight(either.value)\n    if (mapped instanceof Promise) {\n      return mapped.then(right) as any\n    }\n    return right(mapped) as any\n  }\n  const mapped = fnLeft(either.value)\n  if (mapped instanceof Promise) {\n    return mapped.then(left) as any\n  }\n  return left(mapped) as any\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n/**\n * Chain operations that return Either.\n * Left values short-circuit the chain.\n *\n * Curried for use with pipe(). Supports async functions.\n * Combines left error unions.\n *\n * @param fn - Function that returns an Either\n * @returns A curried function that chains Eithers\n *\n * @example\n * ```ts\n * // Sync usage\n * pipe(\n *   right(5),\n *   flatMap(x => right(x * 2)),\n *   flatMap(x => right(x + 1))\n * ) // => right(11)\n *\n * pipe(\n *   right(5),\n *   flatMap(x => left(\"error\")),\n *   flatMap(x => right(x + 1)) // Not executed\n * ) // => left(\"error\")\n *\n * // Async usage\n * await pipe(\n *   right(userId),\n *   flatMap(async id => right(await fetchUser(id))),\n *   flatMap(async user => right(await enrichProfile(user)))\n * ) // => Promise<Either<L, EnrichedUser>>\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const flatMap: EitherFlatMap = (fn) => (either) => {\n  if (!either.right) return either as any\n  const result = fn(either.value)\n  return result as any\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n/**\n * Execute a side effect on right values without modifying the Either.\n * Left values pass through unchanged.\n *\n * Curried for use with pipe(). Supports async functions.\n *\n * @param fn - Side effect function for right values\n * @returns A curried function that executes side effects\n *\n * @example\n * ```ts\n * pipe(\n *   right(42),\n *   tap(x => console.log(x)), // Logs: 42\n *   map(x => x * 2)\n * ) // => right(84)\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const tap: EitherTap = (fn) => (either) => {\n  if (!either.right) return either as any\n  const result = fn(either.value)\n  if (result instanceof Promise) {\n    return result.then(() => either) as any\n  }\n  return either as any\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n/**\n * Execute a side effect on left values without modifying the Either.\n * Right values pass through unchanged.\n *\n * Curried for use with pipe(). Supports async functions.\n *\n * @param fn - Side effect function for left values\n * @returns A curried function that executes side effects\n *\n * @example\n * ```ts\n * pipe(\n *   left(\"error\"),\n *   tapLeft(e => console.error(e)), // Logs: error\n *   mapLeft(e => e.toUpperCase())\n * ) // => left(\"ERROR\")\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const tapLeft: EitherTapLeft = (fn) => (either) => {\n  if (either.right) return either as any\n  const result = fn(either.value)\n  if (result instanceof Promise) {\n    return result.then(() => either) as any\n  }\n  return either as any\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n// ============================================================================\n// Recovery/Fallback\n// ============================================================================\n\n/**\n * Recover from a left value by providing an alternative Either.\n * Right values pass through unchanged.\n *\n * Curried for use with pipe(). Supports async functions.\n * Combines right value unions.\n *\n * @param fn - Function that returns an alternative Either\n * @returns A curried function that recovers from left\n *\n * @example\n * ```ts\n * pipe(\n *   left(\"error\"),\n *   orElse(() => right(42))\n * ) // => right(42)\n *\n * pipe(\n *   right(10),\n *   orElse(() => right(42))\n * ) // => right(10)\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const orElse: EitherOrElse = (fn) => (either) => {\n  if (either.right) return either as any\n  const result = fn(either.value)\n  return result as any\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n/**\n * Swap left and right values.\n * Unique to Either - not available in Result/Option.\n *\n * Curried for use with pipe().\n *\n * @returns A curried function that swaps left and right\n *\n * @example\n * ```ts\n * pipe(\n *   left(\"error\"),\n *   swap()\n * ) // => right(\"error\")\n *\n * pipe(\n *   right(42),\n *   swap()\n * ) // => left(42)\n * ```\n */\nexport const swap =\n  <L, R>() =>\n  (either: EitherType<L, R>): EitherType<R, L> =>\n    either.right ? left(either.value) : right(either.value)\n\n// ============================================================================\n// Filtering\n// ============================================================================\n\n/**\n * Filter right values based on a predicate.\n * Failed predicates convert to left with onFail callback.\n * Left values pass through unchanged.\n *\n * Curried for use with pipe().\n *\n * @param predicate - Function to test right values\n * @param onFail - Function to produce left value on failure\n * @returns A curried function that filters an Either\n *\n * @example\n * ```ts\n * pipe(\n *   right(5),\n *   filter(x => x > 3, x => `${x} is too small`)\n * ) // => right(5)\n *\n * pipe(\n *   right(2),\n *   filter(x => x > 3, x => `${x} is too small`)\n * ) // => left(\"2 is too small\")\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion -- Required for overloaded return types in curried functions */\nexport const filter: EitherFilter = (predicate, onFail) => (either) => {\n  if (!either.right) return either as any\n  return predicate(either.value) ? (either as any) : left(onFail(either.value))\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-type-assertion */\n// ============================================================================\n// Combinators\n// ============================================================================\n\n/**\n * Combine multiple Eithers into a single Either.\n * Short-circuits on the first left value.\n *\n * Supports both array and object inputs with full type preservation.\n *\n * @param eithers - Array or object of Eithers to combine\n * @returns Either with all right values or first left\n *\n * @example\n * ```ts\n * // Array form (with const assertion for tuple typing)\n * all([right(1), right(\"hello\")] as const)\n * // => right([1, \"hello\"])\n *\n * all([right(1), left(\"error\"), right(3)])\n * // => left(\"error\")\n *\n * // Object form\n * all({ a: right(1), b: right(\"hello\") })\n * // => right({ a: 1, b: \"hello\" })\n * ```\n */\n/* oxlint-disable no-explicit-any, no-unsafe-return, no-unsafe-member-access, strict-boolean-expressions, no-unsafe-assignment -- Required for handling union types in overloaded function */\nexport function all<const T extends readonly EitherType<unknown, unknown>[]>(eithers: T): AllArrayReturn<T>\nexport function all<const T extends Record<string, EitherType<unknown, unknown>>>(eithers: T): AllObjectReturn<T>\nexport function all(eithers: any): any {\n  // Array case\n  if (Array.isArray(eithers)) {\n    const values: unknown[] = []\n    for (const either of eithers) {\n      if (!either.right) return either\n      values.push(either.value)\n    }\n    return right(values)\n  }\n\n  // Object case\n  const result: Record<string, unknown> = {}\n  for (const key in eithers) {\n    const either = eithers[key]\n    if (!either.right) return either\n    result[key] = either.value\n  }\n  return right(result)\n}\n/* oxlint-enable no-explicit-any, no-unsafe-return, no-unsafe-member-access, strict-boolean-expressions, no-unsafe-assignment */\n// ============================================================================\n// Extraction\n// ============================================================================\n\n/**\n * Extract the right value or return a default.\n *\n * Curried for use with pipe().\n *\n * @param defaultValue - Value to return if Either is left\n * @returns A curried function that extracts the value\n *\n * @example\n * ```ts\n * pipe(\n *   right(42),\n *   unwrapOr(0)\n * ) // => 42\n *\n * pipe(\n *   left(\"error\"),\n *   unwrapOr(0)\n * ) // => 0\n * ```\n */\nexport const unwrapOr =\n  <R>(defaultValue: R) =>\n  <L>(either: EitherType<L, R>): R =>\n    either.right ? either.value : defaultValue\n\n/**\n * Extract the right value or compute one from the left value.\n *\n * Curried for use with pipe().\n *\n * @param fn - Function to compute default from left value\n * @returns A curried function that extracts the value\n *\n * @example\n * ```ts\n * pipe(\n *   right(42),\n *   unwrapOrElse(() => 0)\n * ) // => 42\n *\n * pipe(\n *   left(\"error\"),\n *   unwrapOrElse(e => e.length)\n * ) // => 5\n * ```\n */\nexport const unwrapOrElse =\n  <L, R>(fn: (left: L) => R) =>\n  (either: EitherType<L, R>): R =>\n    either.right ? either.value : fn(either.value)\n\n/**\n * Pattern match on an Either with handlers for both cases.\n *\n * Curried for use with pipe().\n *\n * @param handlers - Object with left and right handler functions\n * @returns A curried function that pattern matches\n *\n * @example\n * ```ts\n * pipe(\n *   right(42),\n *   match({\n *     left: e => `Error: ${e}`,\n *     right: x => `Success: ${x}`\n *   })\n * ) // => \"Success: 42\"\n * ```\n */\nexport const match =\n  <L, R, U>(handlers: { left: (value: L) => U; right: (value: R) => U }) =>\n  (either: EitherType<L, R>): U =>\n    either.right ? handlers.right(either.value) : handlers.left(either.value)\n\n// ============================================================================\n// Conversions\n// ============================================================================\n\n/**\n * Convert a Result to an Either.\n * Result's ok becomes right, err becomes left.\n *\n * @param result - The Result to convert\n * @returns An Either with the same semantics\n *\n * @example\n * ```ts\n * fromResult(Result.ok(42)) // => right(42)\n * fromResult(Result.err(\"error\")) // => left(\"error\")\n * ```\n */\nexport const fromResult = <R, E>(result: ResultType<R, E>): EitherType<E, R> =>\n  result.ok ? right(result.value) : left(result.error)\n\n/**\n * Convert an Either to a Result.\n * Either's right becomes ok, left becomes err.\n *\n * Curried for use with pipe().\n *\n * @param either - The Either to convert\n * @returns A Result with error semantics\n *\n * @example\n * ```ts\n * pipe(\n *   right(42),\n *   toResult\n * ) // => Result.ok(42)\n *\n * pipe(\n *   left(\"error\"),\n *   toResult\n * ) // => Result.err(\"error\")\n * ```\n */\nexport const toResult = <L, R>(either: EitherType<L, R>): ResultType<R, L> =>\n  either.right ? Result.ok(either.value) : Result.err(either.value)\n\n/**\n * Convert an Option to an Either.\n * Option's some becomes right, none becomes left with onNone callback.\n *\n * @param option - The Option to convert\n * @param onNone - Function to produce left value for none\n * @returns An Either\n *\n * @example\n * ```ts\n * fromOption(Option.some(42), () => \"not found\") // => right(42)\n * fromOption(Option.none(), () => \"not found\") // => left(\"not found\")\n * ```\n */\nexport const fromOption = <R, L>(option: OptionType<R>, onNone: () => L): EitherType<L, R> =>\n  option.some ? right(option.value) : left(onNone())\n\n/**\n * Convert an Either to an Option.\n * Either's right becomes some, left is discarded.\n *\n * Curried for use with pipe().\n *\n * @param either - The Either to convert\n * @returns An Option (left value is discarded)\n *\n * @example\n * ```ts\n * pipe(\n *   right(42),\n *   toOption\n * ) // => Option.some(42)\n *\n * pipe(\n *   left(\"error\"),\n *   toOption\n * ) // => Option.none()\n * ```\n */\nexport const toOption = <L, R>(either: EitherType<L, R>): OptionType<R> =>\n  either.right ? Option.some(either.value) : Option.none<R>()\n\n/**\n * Convert a nullable value to an Either.\n * null/undefined becomes left with onNull callback, otherwise right.\n *\n * @param value - The nullable value\n * @param onNull - Function to produce left value for null/undefined\n * @returns An Either\n *\n * @example\n * ```ts\n * fromNullable(42, () => \"not found\") // => right(42)\n * fromNullable(null, () => \"not found\") // => left(\"not found\")\n * fromNullable(undefined, () => \"not found\") // => left(\"not found\")\n * ```\n */\nexport const fromNullable = <R, L>(value: R | null | undefined, onNull: () => L): EitherType<L, R> =>\n  value === null || value === undefined ? left(onNull()) : right(value)\n\n/**\n * Create an Either from a predicate.\n * Predicate success becomes right, failure becomes left with onFail callback.\n *\n * @param value - The value to test\n * @param predicate - Function to test the value\n * @param onFail - Function to produce left value on failure\n * @returns An Either\n *\n * @example\n * ```ts\n * fromPredicate(5, x => x > 3, x => `${x} is too small`)\n * // => right(5)\n *\n * fromPredicate(2, x => x > 3, x => `${x} is too small`)\n * // => left(\"2 is too small\")\n * ```\n */\nexport const fromPredicate = <R, L>(\n  value: R,\n  predicate: (value: R) => boolean,\n  onFail: (value: R) => L,\n): EitherType<L, R> => (predicate(value) ? right(value) : left(onFail(value)))\n\n// ============================================================================\n// Namespace Export\n// ============================================================================\n\n/**\n * Either namespace containing all utility functions for working with Either types.\n *\n * Either represents a value that can be one of two types: Left<L> or Right<R>.\n * By convention, Right is the \"success\" or preferred path, while Left represents\n * an alternative outcome (not necessarily an error, unlike Result).\n *\n * Use Either when both outcomes are valid and meaningful, not just success/failure.\n * For error handling, prefer Result instead.\n *\n * @see {@link Result} for success/error semantics\n * @see {@link Option} for presence/absence semantics\n *\n * @example\n * ```ts\n * import { Either, pipe } from '@repo/std'\n * import type { Either as EitherType } from '@repo/std'\n *\n * // Either for branching logic (cache vs fresh data)\n * const fetchOrCache = (id: number): EitherType<CachedData, FreshData> =>\n *   cache.has(id) ? Either.left(cache.get(id)) : Either.right(fetch(id))\n *\n * const result = pipe(\n *   fetchOrCache(1),\n *   Either.map(data => data.value),\n *   Either.unwrapOr(defaultValue)\n * )\n *\n * // Async example\n * const processed = await pipe(\n *   Either.right(userId),\n *   Either.map(async id => await fetchUser(id)),\n *   Either.flatMap(async user => Either.right(await enrichUser(user)))\n * )\n * ```\n */\nexport const Either = {\n  // Constructors\n  left,\n  right,\n\n  // Type guards\n  isLeft,\n  isRight,\n\n  // Transformations\n  map,\n  mapLeft,\n  bimap,\n  flatMap,\n  tap,\n  tapLeft,\n\n  // Recovery\n  orElse,\n  swap,\n\n  // Filtering\n  filter,\n\n  // Combinators\n  all,\n\n  // Extraction\n  unwrapOr,\n  unwrapOrElse,\n  match,\n\n  // Conversions\n  fromResult,\n  toResult,\n  fromOption,\n  toOption,\n  fromNullable,\n  fromPredicate,\n} as const\n"],"mappings":"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"}