ok-fp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paweł Maciejewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# OKFP
+
+![npm (scoped)](https://img.shields.io/npm/v/okfp?color=orange&label=npm) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+> Essential typed effects for TypeScript.
+
+OKFP is a small, focused functional programming toolkit for TypeScript.
+
+It provides a minimal set of **typed effects**: composable, type-safe wrappers for optional values, errors, and async computations.
+
+## Status
+
+OKFP is pre-1.0.
+
+- ✅ Implemented: `Option`, `Either`
+- 🚧 Planned before `v1.0.0`: `Validation`, `Task`, `TaskEither`
+
+See: [ROADMAP.md](./ROADMAP.md)
+
+## Installation
+
+Install with your package manager of choice:
+
+```bash
+npm install okfp
+# or
+# pnpm add okfp
+# yarn add okfp
+```
+
+### Basic example
+
+This example shows a small pipeline using `Option`.
+
+```ts
+import { type Option, some, none } from "okfp/option";
+
+const parseNumber = (input: string): Option<number> => {
+  const n = Number(input);
+  return Number.isFinite(n) ? some(n) : none();
+};
+
+const nonZero = (n: number): Option<number> => (n !== 0 ? some(n) : none());
+
+const positive = (n: number): Option<number> => (n > 0 ? some(n) : none());
+
+const reciprocal = (n: number): Option<number> => some(1 / n);
+
+const compute = (input: string): Option<number> =>
+  parseNumber(input)
+    .flatMap(positive) // must be > 0
+    .flatMap(nonZero) // must not be 0
+    .flatMap(reciprocal) // compute 1 / n
+    .map((n) => n * 100); // scale result
+
+// Usage (returns Option instances)
+compute("4"); // returns Option.some(25)
+compute("0"); // returns Option.none() (fails nonZero)
+compute("-3"); // returns Option.none() (fails positive)
+compute("abc"); // returns Option.none() (fails parsing)
+```
+
+## Documentation
+
+Full documentation and API reference are available in the docs site or the `docs/` folder.
+
+[API docs](https://pwlmc.github.io/okfp/)
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

package/dist/either.d.mts

@@ -0,0 +1,2 @@
+import { a as fromOption, c as tryCatch, d as Left, f as Right, i as fromNullable, l as Either, n as map3, o as left, r as sequence, s as right, t as map2, u as EitherV } from "./helpers-BGxhvbJN.mjs";
+export { type Either, EitherV, Left, Right, fromNullable, fromOption, left, map2, map3, right, sequence, tryCatch };

package/dist/either.mjs

@@ -0,0 +1,204 @@
+//#region src/either/either.ts
+function createEither(value) {
+	const either = {
+		filterOrElse: (predicate, onLeft) => either.flatMap((right) => predicate(right) ? either : createEither({ left: onLeft() })),
+		map: (mapper) => either.flatMap((right) => createEither({ right: mapper(right) })),
+		orElse: (fallback) => either.match((left) => forceCast(fallback(left)), () => forceCast(either)),
+		ap: function(arg) {
+			return this.flatMap((fn) => arg.map((right) => fn(right)));
+		},
+		swap: () => either.match((left) => createEither({ right: left }), (right) => createEither({ left: right })),
+		zip: (eitherA) => either.map((value) => (a) => [value, a]).ap(eitherA),
+		flatten: function() {
+			return this.flatMap((value) => value);
+		},
+		flatMap: (mapper) => either.match(() => forceCast(either), (right) => forceCast(mapper(right))),
+		tap: (sideEffect) => {
+			either.match(() => {}, sideEffect);
+			return either;
+		},
+		match: (onLeft, onRight) => isLeft(value) ? onLeft(value.left) : onRight(value.right),
+		getOrElse: (fallback) => either.match((error) => fallback(error), (value) => value),
+		toResult: () => either.match((error) => ({
+			ok: false,
+			error
+		}), (value) => ({
+			ok: true,
+			value
+		}))
+	};
+	return either;
+}
+function isLeft(value) {
+	return typeof value === "object" && "left" in value;
+}
+function forceCast(either) {
+	return either;
+}
+
+//#endregion
+//#region src/either/constructors.ts
+/**
+* Creates an Either containing an error value (Left).
+*
+* @typeParam E - The type of the error value
+* @typeParam T - The type of the success value (defaults to never since this is an error)
+* @param left - The error value to wrap
+* @returns Either containing the error value on the Left side
+*
+* @example
+* ```typescript
+* const error = left("Something went wrong"); // Either<string, never>
+* ```
+*/
+function left(left) {
+	return createEither({ left });
+}
+/**
+* Creates an Either containing a success value (Right).
+*
+* @typeParam T - The type of the success value
+* @typeParam E - The type of the error value (defaults to never since this is a success)
+* @param right - The success value to wrap
+* @returns Either containing the success value on the Right side
+*
+* @example
+* ```typescript
+* const success = right(42); // Either<never, number>
+* ```
+*/
+function right(right) {
+	return createEither({ right });
+}
+/**
+* Creates an Either from a potentially nullable value.
+* If the value is null or undefined, creates a Left with the provided error.
+* If the value is present, creates a Right with the value.
+*
+* @typeParam E - The type of the error value
+* @typeParam T - The type of the success value
+* @param nullable - The potentially null/undefined value
+* @param onNullish - Function that provides the error value when nullable is null/undefined
+* @returns Either containing the value if present, or the error if null/undefined
+*
+* @example
+* ```typescript
+* fromNullable("hello", () => "empty") // Right("hello")
+* fromNullable(null, () => "empty")    // Left("empty")
+* fromNullable(undefined, () => "empty") // Left("empty")
+* ```
+*/
+function fromNullable(nullable, onNullish) {
+	return nullable != null ? right(nullable) : left(onNullish());
+}
+/**
+* Safely executes a function that might throw, converting exceptions to Either.
+*
+* @typeParam E - The type of the processed error value
+* @typeParam T - The type of the success value
+* @param fn - The function to execute that might throw
+* @param onThrow - Function that processes the caught error into the desired error type
+* @returns Either containing the result if successful, or the processed error if thrown
+*
+* @example
+* ```typescript
+* const parseNumber = (str: string) =>
+*   tryCatch(
+*     () => JSON.parse(str),
+*     (err) => `Parse error: ${err.message}`
+*   );
+*
+* parseNumber("42")     // Right(42)
+* parseNumber("invalid") // Left("Parse error: ...")
+* ```
+*/
+function tryCatch(fn, onThrow) {
+	try {
+		return right(fn());
+	} catch (err) {
+		return left(onThrow(err));
+	}
+}
+/**
+* Creates an Either from an Option by providing an error value for the None case.
+*
+* @typeParam E - The type of the error value
+* @typeParam T - The type of the success value
+* @param opt - The Option to convert
+* @param onNone - Function that provides the error value when Option is None
+* @returns Either containing the Option's value if Some, or the error if None
+*
+* @example
+* ```typescript
+* fromOption(some(42), () => "empty")   // Right(42)
+* fromOption(none(), () => "empty")     // Left("empty")
+* ```
+*/
+function fromOption(opt, onNone) {
+	return opt.match(() => left(onNone()), (value) => right(value));
+}
+
+//#endregion
+//#region src/either/helpers.ts
+/**
+* Combines two Eithers using a mapping function.
+* Returns the mapped result if both Eithers are Right, otherwise the first Left.
+*
+* @param eitherA - First Either to combine
+* @param eitherB - Second Either to combine
+* @param mapper - Function to combine both Right values
+* @returns Either containing the mapped result, or the first Left
+*
+* @example
+* ```typescript
+* map2(right("John"), right("Doe"), (first, last) => `${first} ${last}`)
+* // Right("John Doe")
+* ```
+*/
+function map2(eitherA, eitherB, mapper) {
+	return eitherA.map((a) => (b) => mapper(a, b)).ap(eitherB);
+}
+/**
+* Combines three Eithers using a mapping function.
+* Returns the mapped result if all Eithers are Right, otherwise the first Left.
+*
+* @param eitherA - First Either to combine
+* @param eitherB - Second Either to combine
+* @param eitherC - Third Either to combine
+* @param mapper - Function to combine all three Right values
+* @returns Either containing the mapped result, or the first Left
+*
+* @example
+* ```typescript
+* map3(right(1), right(2), right(3), (a, b, c) => a + b + c)
+* // Right(6)
+* ```
+*/
+function map3(eitherA, eitherB, eitherC, mapper) {
+	return eitherA.map((a) => (b) => (c) => mapper(a, b, c)).ap(eitherB).ap(eitherC);
+}
+/**
+* Converts an array of Eithers into an Either of array.
+* Returns Right with all values if all Eithers are Right, otherwise the first Left.
+*
+* @param eithers - Array of Eithers to sequence
+* @returns Either containing array of all values, or the first Left
+*
+* @example
+* ```typescript
+* sequence([right(1), right(2), right(3)]) // Right([1, 2, 3])
+* sequence([right(1), left("error")])      // Left("error")
+* ```
+*/
+function sequence(eithers) {
+	const out = [];
+	for (const either of eithers) {
+		const result = either.toResult();
+		if (!result.ok) return left(result.error);
+		out.push(result.value);
+	}
+	return right(out);
+}
+
+//#endregion
+export { fromNullable, fromOption, left, map2, map3, right, sequence, tryCatch };

package/dist/helpers-BGxhvbJN.d.mts

@@ -0,0 +1,665 @@
+//#region src/option/model.d.ts
+type Some<T> = {
+  some: T;
+};
+type None = symbol;
+type OptionV<T> = Some<T> | None;
+declare const NONE: unique symbol;
+//#endregion
+//#region src/option/option.d.ts
+type Option<T> = {
+  /**
+   * Filters the Option based on a predicate function.
+   * If this Option is Some and the predicate returns true, returns this Option.
+   * Otherwise, returns None.
+   *
+   * @param predicate - Function that tests the contained value
+   * @returns The same Option if predicate passes, None otherwise
+   *
+   * @example
+   * ```typescript
+   * some(5).filter(x => x > 3) // Some(5)
+   * some(2).filter(x => x > 3) // None
+   * none().filter(x => x > 3)  // None
+   * ```
+   */
+  filter: (predicate: (value: T) => boolean) => Option<T>;
+  /**
+   * Transforms the value inside the Option using a mapping function.
+   * If this Option is None, returns None without calling the mapper.
+   *
+   * @param mapper - Function to transform the contained value
+   * @returns New Option containing the transformed value, or None
+   *
+   * @example
+   * ```typescript
+   * some(5).map(x => x * 2)     // Some(10)
+   * none<number>().map(x => x * 2) // None
+   * ```
+   */
+  map: <U>(mapper: (value: T) => U) => Option<U>;
+  /**
+   * Returns this Option if it contains a value, otherwise returns the fallback Option.
+   * The fallback is lazily evaluated to avoid unnecessary computation.
+   *
+   * @param fallback - Function that provides the alternative Option
+   * @returns This Option if Some, otherwise the fallback Option
+   *
+   * @example
+   * ```typescript
+   * some(5).orElse(() => some(10))  // Some(5)
+   * none().orElse(() => some(10))   // Some(10)
+   * ```
+   */
+  orElse: (fallback: () => Option<T>) => Option<T>;
+  /**
+   * Applies a function wrapped in an Option to a value wrapped in an Option.
+   * This is useful for applying functions that are also optional.
+   *
+   * @param optA - Option containing the argument to apply the function to
+   * @returns Option containing the result, or None if either Option is None
+   *
+   * @example
+   * ```typescript
+   * const add = (x: number) => (y: number) => x + y;
+   * some(add(5)).ap(some(3)) // Some(8)
+   * some(add(5)).ap(none())  // None
+   * none().ap(some(3))       // None
+   * ```
+   */
+  ap: <A, U>(this: Option<(arg: A) => U>, optA: Option<A>) => Option<U>;
+  /**
+   * Combines this Option with another Option into a tuple.
+   * If both Options contain values, returns Some containing a tuple of both values.
+   * If either Option is None, returns None.
+   *
+   * @param optA - The Option to combine with this one
+   * @returns Option containing a tuple of both values, or None if either is None
+   *
+   * @example
+   * ```typescript
+   * const name = some("Alice");
+   * const age = some(30);
+   * name.zip(age) // Some(["Alice", 30])
+   *
+   * const missing = none<number>();
+   * name.zip(missing) // None
+   * none().zip(age)   // None
+   * ```
+   */
+  zip: <A>(optA: Option<A>) => Option<readonly [T, A]>;
+  /**
+   * Flattens a nested Option structure by removing one level of nesting.
+   * If this Option contains another Option, returns the inner Option.
+   * If this Option is None, returns None.
+   *
+   * @returns The inner Option if this Option contains one, or None
+   *
+   * @example
+   * ```typescript
+   * some(some(5)).flatten() // Some(5)
+   * some(none<number>()).flatten() // None
+   * ```
+   */
+  flatten: <U>(this: Option<Option<U>>) => Option<U>;
+  /**
+   * Chains Option-returning operations together (monadic bind).
+   * If this Option is Some, applies the mapper and returns the result.
+   * If this Option is None, returns None without calling the mapper.
+   *
+   * @param mapper - Function that returns an Option
+   * @returns The Option returned by mapper, or None
+   *
+   * @example
+   * ```typescript
+   * const safeDivide = (x: number) => x === 0 ? none() : some(10 / x);
+   * some(2).flatMap(safeDivide)  // Some(5)
+   * some(0).flatMap(safeDivide)  // None
+   * none().flatMap(safeDivide)   // None
+   * ```
+   */
+  flatMap: <U>(mapper: (value: T) => Option<U>) => Option<U>;
+  /**
+   * Performs a side effect if this Option contains a value.
+   * Returns the original Option unchanged.
+   *
+   * @returns The same Option instance
+   *
+   * @example
+   * ```typescript
+   * some(5).tap((value) => console.log("Has value", value)) // Some(5), logs message
+   * none().tap((value) => console.log("Has value", value))  // None, no log
+   * ```
+   */
+  tap: (sideEffect: (value: T) => unknown) => Option<T>;
+  /**
+   * Performs a side effect if this Option is None.
+   * Returns the original Option unchanged.
+   *
+   * @returns The same Option instance
+   *
+   * @example
+   * ```typescript
+   * some(5).tapNone(() => console.log("No value")) // Some(5), no log
+   * none().tapNone(() => console.log("No value"))  // None, logs message
+   * ```
+   */
+  tapNone: (sideEffect: () => unknown) => Option<T>;
+  /**
+   * Pattern matches on the Option, executing different functions based on its state.
+   *
+   * @param onNone - Function to execute if Option is None
+   * @param onSome - Function to execute if Option is Some
+   * @returns The result of the executed function
+   *
+   * @example
+   * ```typescript
+   * some(5).match(() => "empty", x => `value: ${x}`) // "value: 5"
+   * none().match(() => "empty", x => `value: ${x}`)  // "empty"
+   * ```
+   */
+  match: <U>(onNone: () => U, onSome: (value: T) => U) => U;
+  /**
+   * Extracts the value from the Option, or returns a fallback value if None.
+   *
+   * @param fallback - Function that provides the default value
+   * @returns The value or the fallback value
+   *
+   * @example
+   * ```typescript
+   * some(5).getOrElse(() => 0)  // 5
+   * none().getOrElse(() => 0)   // 0
+   * ```
+   */
+  getOrElse: (fallback: () => T) => T;
+  /**
+   * Converts the Option to a nullable value.
+   * Returns the contained value if Some, or null if None.
+   *
+   * @returns The value or null
+   *
+   * @example
+   * ```typescript
+   * some(5).toNullable()  // 5
+   * none().toNullable()   // null
+   * ```
+   */
+  toNullable: () => T | null;
+  /**
+   * Converts the Option to an array.
+   * If this Option contains a value, returns an array with that single value.
+   * If this Option is None, returns an empty array.
+   *
+   * @returns Array containing the value if Some, or empty array if None
+   *
+   * @example
+   * ```typescript
+   * some(42).toArray()    // [42]
+   * none().toArray()      // []
+   * ```
+   */
+  toArray: () => readonly T[];
+};
+//#endregion
+//#region src/option/constructors.d.ts
+/**
+ * Creates an {@link Option} that contains a value.
+ *
+ * Use this to wrap an existing value into an `Option<T>` representing presence
+ * (as opposed to `none`, which represents absence).
+ *
+ * @typeParam T - Type of the wrapped value.
+ * @param some - The value to store in the option.
+ * @returns An {@link Option} containing the provided value.
+ */
+declare function some<T>(some: T): Option<T>;
+/**
+ * Creates an {@link Option} representing the absence of a value.
+ *
+ * @typeParam T - The type of the value that would be contained if present.
+ * @returns An {@link Option} in the `None` state.
+ *
+ * @example
+ * ```ts
+ * const value = none<number>();
+ * ```
+ */
+declare function none<T>(): Option<T>;
+/**
+ * Creates an {@link Option} from a nullable value.
+ *
+ * If {@link nullable} is `null` or `undefined`, returns {@link none}.
+ * Otherwise, wraps the provided value in {@link some}.
+ *
+ * @example
+ * fromNullable(0).getOrElse(() => 123); // 0
+ * fromNullable(null).toNullable(); // null
+ *
+ * @typeParam T - The non-null value type to wrap.
+ * @param nullable - A value that may be `null` or `undefined`.
+ * @returns An {@link Option} that is `Some` when the value is present, otherwise `None`.
+ */
+declare function fromNullable$1<T>(nullable: null | undefined | T): Option<T>;
+/**
+ * Creates an {@link Option} from an {@link Either} by extracting the Right value.
+ *
+ * If the Either is Right, returns Some containing the Right value.
+ * If the Either is Left, returns None (discarding the Left value).
+ *
+ * @typeParam L - The type of the Left value (error type) that will be discarded
+ * @typeParam R - The type of the Right value that will be preserved in the Option
+ * @param either - The Either to convert to an Option
+ * @returns Some containing the Right value, or None if the Either was Left
+ *
+ * @example
+ * ```typescript
+ * const success = right(42);
+ * fromEither(success) // Some(42)
+ *
+ * const failure = left("error message");
+ * fromEither(failure) // None
+ * ```
+ */
+declare function fromEither<L, R>(either: Either<L, R>): Option<R>;
+//#endregion
+//#region src/option/helpers.d.ts
+/**
+ * Combines two Options using a mapping function.
+ * Only applies the mapper if both Options contain values.
+ *
+ * @param optA - First Option to combine
+ * @param optB - Second Option to combine
+ * @param mapper - Function that combines both values
+ * @returns Option containing the combined result, or None if either Option is None
+ *
+ * @example
+ * ```typescript
+ * const greet = (first, last) => `Hi ${first} ${last}!`
+ * map2(some("John"), some("Doe"), greet) // Some("John Doe")
+ * map2(some("John"), none<string>(), greet) // None
+ * ```
+ */
+declare function map2$1<A, B, C>(optA: Option<A>, optB: Option<B>, mapper: (a: A, b: B) => C): Option<C>;
+/**
+ * Combines three Options using a mapping function.
+ * Only applies the mapper if all three Options contain values.
+ *
+ * @param optA - First Option to combine
+ * @param optB - Second Option to combine
+ * @param optC - Third Option to combine
+ * @param mapper - Function that combines all three values
+ * @returns Option containing the combined result, or None if any Option is None
+ *
+ * @example
+ * ```typescript
+ * const toDateString = (d, m, y) => `${d}/${m}/${y}`
+ * map3(some(15), some(6), some(2023), toDateString) // Some("15/6/2023")
+ * map3(some(15), some(6), none<number>(), toDateString) // None
+ * ```
+ */
+declare function map3$1<A, B, C, D>(optA: Option<A>, optB: Option<B>, optC: Option<C>, mapper: (a: A, b: B, c: C) => D): Option<D>;
+/**
+ * Converts an array of Options into an Option of array.
+ * If all Options in the array contain values, returns Some containing an array of all values.
+ * If any Option in the array is None, returns None.
+ *
+ * @param opts - Array of Options to sequence
+ * @returns Some containing array of all values if all Options are Some, otherwise None
+ *
+ * @example
+ * ```typescript
+ * sequence([some(1), some(2), some(3)]) // Some([1, 2, 3])
+ * sequence([some(1), none(), some(3)]) // None
+ * ```
+ */
+declare function sequence$1<T>(opts: Option<T>[]): Option<T[]>;
+//#endregion
+//#region src/either/model.d.ts
+type Left<E> = {
+  readonly left: E;
+};
+type Right<T> = {
+  readonly right: T;
+};
+type EitherV<E, T> = Left<E> | Right<T>;
+//#endregion
+//#region src/either/either.d.ts
+type Result<E, T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: E;
+};
+type Either<E, T> = {
+  /**
+   * Filters the Either based on a predicate function applied to the Right value.
+   *
+   * @param predicate - Function that tests the Right value
+   * @param onLeft - Function that provides the error value when predicate fails
+   * @returns The same Either if Left or predicate passes, otherwise Left with the provided error
+   *
+   * @example
+   * ```typescript
+   * const isPositive = (n: number) => n > 0;
+   * right(5).filterOrElse(isPositive, () => "Must be positive")  // Right(5)
+   * right(-3).filterOrElse(isPositive, () => "Must be positive") // Left("Must be positive")
+   * left("error").filterOrElse(isPositive, () => "Must be positive") // Left("error")
+   * ```
+   */
+  filterOrElse: (predicate: (right: T) => boolean, onLeft: () => E) => Either<E, T>;
+  /**
+   * Transforms the Right value using a mapping function.
+   *
+   * @typeParam U - The type of the transformed value
+   * @param mapper - Function to transform the Right value
+   * @returns New Either with the transformed Right value, or the same Left if error
+   *
+   * @example
+   * ```typescript
+   * right(5).map(x => x * 2)        // Right(10)
+   * left("error").map(x => x * 2)   // Left("error")
+   * ```
+   */
+  map: <U>(mapper: (right: T) => U) => Either<E, U>;
+  /**
+   * Returns this Either if it's Right, otherwise returns the result of the fallback function.
+   *
+   * @typeParam EE - The type of the error in the fallback Either
+   * @param fallback - Function that takes the Left value and returns an alternative Either
+   * @returns This Either if Right, otherwise the Either returned by the fallback function
+   *
+   * @example
+   * ```typescript
+   * right(42).orElse((err) => right(0))           // Right(42)
+   * left("error").orElse((err) => right(0))       // Right(0)
+   * ```
+   */
+  orElse: <EE>(fallback: (left: E) => Either<EE, T>) => Either<E | EE, T>;
+  /**
+   * Applies a function wrapped in an Either to a value wrapped in an Either.
+   *
+   * @typeParam A - The type of the argument value
+   * @typeParam U - The type of the function's return value
+   * @param arg - Either containing the argument to apply the function to
+   * @returns Either containing the function result, or the first Left if any Either is Left
+   *
+   * @example
+   * ```typescript
+   * const add = (x: number) => (y: number) => x + y;
+   * right(add(5)).ap(right(3))     // Right(8)
+   * right(add(5)).ap(left("err"))  // Left("err")
+   * left("err").ap(right(3))       // Left("err")
+   * ```
+   */
+  ap: <EE, A, U>(this: Either<E, (a: A) => U>, arg: Either<EE, A>) => Either<E | EE, U>;
+  /**
+   * Swaps the Left and Right sides of the Either.
+   *
+   * @returns Either with Left and Right sides swapped
+   *
+   * @example
+   * ```typescript
+   * right(42).swap()        // Left(42)
+   * left("error").swap()    // Right("error")
+   * ```
+   */
+  swap: () => Either<T, E>;
+  /**
+   * Combines this Either with another Either into a tuple.
+   *
+   * @typeParam EE - Left type of the Either to combine with
+   * @typeParam A - Right type of the Either to combine with
+   * @param eitherA - The Either to combine with this one
+   * @returns Either containing a tuple of both Right values, or the first Left if any Either is Left
+   *
+   * @example
+   * ```typescript
+   * right("Alice").zip(right(30))        // Right(["Alice", 30])
+   * right("Alice").zip(left("No age"))   // Left("No age")
+   * left("No name").zip(right(30))       // Left("No name")
+   * ```
+   */
+  zip: <EE, A>(eitherA: Either<EE, A>) => Either<E | EE, readonly [T, A]>;
+  /**
+   * Flattens a nested Either structure by removing one level of nesting.
+   *
+   * @typeParam EE - Left type of the inner Either
+   * @typeParam U - Right type of the inner Either
+   * @returns The inner Either if this Either is Right, otherwise this Either unchanged
+   *
+   * @example
+   * ```typescript
+   * right(right(42)).flatten() // Right(42)
+   * right(left("inner error")).flatten() // Left("inner error")
+   *
+   * ```
+   */
+  flatten: <EE, U>(this: Either<E, Either<EE, U>>) => Either<E | EE, U>;
+  /**
+   * Chains Either-returning operations together (monadic bind).
+   *
+   * @typeParam EE - The error type of the Either returned by the mapper
+   * @typeParam U - The success type of the Either returned by the mapper
+   * @param mapper - Function that takes a Right value and returns an Either
+   * @returns The Either returned by mapper if this Either is Right, otherwise this Either unchanged
+   *
+   * @example
+   * ```typescript
+   * const safeDivide = (x: number, y: number) =>
+   *   y === 0 ? left("Division by zero") : right(x / y);
+   *
+   * right(10).flatMap(x => safeDivide(x, 2))  // Right(5)
+   * right(10).flatMap(x => safeDivide(x, 0))  // Left("Division by zero")
+   * left("error").flatMap(x => safeDivide(x, 2)) // Left("error") - mapper not called
+   * ```
+   */
+  flatMap: <EE, U>(mapper: (right: T) => Either<EE, U>) => Either<E | EE, U>;
+  /**
+   * Performs a side effect if this Either is Right, returning the original Either unchanged.
+   * If this Either is Left, the side effect is not executed and the Either is returned as-is.
+   *
+   * @param sideEffect - Function to execute with the Right value (return value is ignored)
+   * @returns The same Either instance unchanged
+   *
+   * @example
+   * ```typescript
+   * right(42)
+   *   .tap(value => console.log(`Got value: ${value}`)) // Logs: "Got value: 42"
+   * left("error")
+   *   .tap(value => console.log(`Got value: ${value}`)) // No log output
+   *
+   * ```
+   */
+  tap: (sideEffect: (right: T) => void) => Either<E, T>;
+  /**
+   * Pattern matches on the Either, executing different functions based on its state.
+   *
+   * @typeParam U - The return type of both matcher functions
+   * @param onLeft - Function to execute if Either is Left, receives the Left value
+   * @param onRight - Function to execute if Either is Right, receives the Right value
+   * @returns The result of the executed function
+   *
+   * @example
+   * ```typescript
+   * right(42).match(
+   *   (err) => `Error: ${err}`,
+   *   (val) => `Value: ${val}`
+   * ) // "Value: 42"
+   *
+   * left("Not a number").match(
+   *   (err) => `Error: ${err}`,
+   *   (val) => `Value: ${val}`
+   * ) // "Error: Not a number"
+   * ```
+   */
+  match: <U>(onLeft: (left: E) => U, onRight: (right: T) => U) => U;
+  /**
+   * Extracts the Right value from the Either, or returns a fallback value if Left.
+   *
+   * @param fallback - Function that takes the Left value and returns a default value of type T
+   * @returns The Right value if present, otherwise the result of the fallback function
+   *
+   * @example
+   * ```typescript
+   * right(42).getOrElse((err) => 0)           // 42
+   * left("error").getOrElse((err) => 0)       // 0
+   * ```
+   */
+  getOrElse: (fallback: (left: E) => T) => T;
+  /**
+   * Converts the Either to a Result type, which is an object with `ok` and `error` or `value` properties.
+   *
+   * @returns A Result object representing the Either's state
+   *
+   * @example
+   * ```typescript
+   * const result = right(42).toResult();
+   * console.log(result.ok); // true
+   * console.log(result.value); // 42
+   *
+   * const errorResult = left("error").toResult();
+   * console.log(errorResult.ok); // false
+   * console.log(errorResult.error); // "error"
+   * ```
+   */
+  toResult: () => Result<E, T>;
+};
+//#endregion
+//#region src/either/constructors.d.ts
+/**
+ * Creates an Either containing an error value (Left).
+ *
+ * @typeParam E - The type of the error value
+ * @typeParam T - The type of the success value (defaults to never since this is an error)
+ * @param left - The error value to wrap
+ * @returns Either containing the error value on the Left side
+ *
+ * @example
+ * ```typescript
+ * const error = left("Something went wrong"); // Either<string, never>
+ * ```
+ */
+declare function left<E, T = never>(left: E): Either<E, T>;
+/**
+ * Creates an Either containing a success value (Right).
+ *
+ * @typeParam T - The type of the success value
+ * @typeParam E - The type of the error value (defaults to never since this is a success)
+ * @param right - The success value to wrap
+ * @returns Either containing the success value on the Right side
+ *
+ * @example
+ * ```typescript
+ * const success = right(42); // Either<never, number>
+ * ```
+ */
+declare function right<T, E = never>(right: T): Either<E, T>;
+/**
+ * Creates an Either from a potentially nullable value.
+ * If the value is null or undefined, creates a Left with the provided error.
+ * If the value is present, creates a Right with the value.
+ *
+ * @typeParam E - The type of the error value
+ * @typeParam T - The type of the success value
+ * @param nullable - The potentially null/undefined value
+ * @param onNullish - Function that provides the error value when nullable is null/undefined
+ * @returns Either containing the value if present, or the error if null/undefined
+ *
+ * @example
+ * ```typescript
+ * fromNullable("hello", () => "empty") // Right("hello")
+ * fromNullable(null, () => "empty")    // Left("empty")
+ * fromNullable(undefined, () => "empty") // Left("empty")
+ * ```
+ */
+declare function fromNullable<E, T>(nullable: T | null | undefined, onNullish: () => E): Either<E, T>;
+/**
+ * Safely executes a function that might throw, converting exceptions to Either.
+ *
+ * @typeParam E - The type of the processed error value
+ * @typeParam T - The type of the success value
+ * @param fn - The function to execute that might throw
+ * @param onThrow - Function that processes the caught error into the desired error type
+ * @returns Either containing the result if successful, or the processed error if thrown
+ *
+ * @example
+ * ```typescript
+ * const parseNumber = (str: string) =>
+ *   tryCatch(
+ *     () => JSON.parse(str),
+ *     (err) => `Parse error: ${err.message}`
+ *   );
+ *
+ * parseNumber("42")     // Right(42)
+ * parseNumber("invalid") // Left("Parse error: ...")
+ * ```
+ */
+declare function tryCatch<E, T>(fn: () => T, onThrow: (err: unknown) => E): Either<E, T>;
+/**
+ * Creates an Either from an Option by providing an error value for the None case.
+ *
+ * @typeParam E - The type of the error value
+ * @typeParam T - The type of the success value
+ * @param opt - The Option to convert
+ * @param onNone - Function that provides the error value when Option is None
+ * @returns Either containing the Option's value if Some, or the error if None
+ *
+ * @example
+ * ```typescript
+ * fromOption(some(42), () => "empty")   // Right(42)
+ * fromOption(none(), () => "empty")     // Left("empty")
+ * ```
+ */
+declare function fromOption<E, T>(opt: Option<T>, onNone: () => E): Either<E, T>;
+//#endregion
+//#region src/either/helpers.d.ts
+/**
+ * Combines two Eithers using a mapping function.
+ * Returns the mapped result if both Eithers are Right, otherwise the first Left.
+ *
+ * @param eitherA - First Either to combine
+ * @param eitherB - Second Either to combine
+ * @param mapper - Function to combine both Right values
+ * @returns Either containing the mapped result, or the first Left
+ *
+ * @example
+ * ```typescript
+ * map2(right("John"), right("Doe"), (first, last) => `${first} ${last}`)
+ * // Right("John Doe")
+ * ```
+ */
+declare function map2<EA, A, EB, B, C>(eitherA: Either<EA, A>, eitherB: Either<EB, B>, mapper: (a: A, b: B) => C): Either<EA | EB, C>;
+/**
+ * Combines three Eithers using a mapping function.
+ * Returns the mapped result if all Eithers are Right, otherwise the first Left.
+ *
+ * @param eitherA - First Either to combine
+ * @param eitherB - Second Either to combine
+ * @param eitherC - Third Either to combine
+ * @param mapper - Function to combine all three Right values
+ * @returns Either containing the mapped result, or the first Left
+ *
+ * @example
+ * ```typescript
+ * map3(right(1), right(2), right(3), (a, b, c) => a + b + c)
+ * // Right(6)
+ * ```
+ */
+declare function map3<EA, A, EB, B, EC, C, D>(eitherA: Either<EA, A>, eitherB: Either<EB, B>, eitherC: Either<EC, C>, mapper: (a: A, b: B, c: C) => D): Either<EA | EB | EC, D>;
+/**
+ * Converts an array of Eithers into an Either of array.
+ * Returns Right with all values if all Eithers are Right, otherwise the first Left.
+ *
+ * @param eithers - Array of Eithers to sequence
+ * @returns Either containing array of all values, or the first Left
+ *
+ * @example
+ * ```typescript
+ * sequence([right(1), right(2), right(3)]) // Right([1, 2, 3])
+ * sequence([right(1), left("error")])      // Left("error")
+ * ```
+ */
+declare function sequence<E, T>(eithers: Either<E, T>[]): Either<E, T[]>;
+//#endregion
+export { OptionV as C, None as S, fromNullable$1 as _, fromOption as a, Option as b, tryCatch as c, Left as d, Right as f, fromEither as g, sequence$1 as h, fromNullable as i, Either as l, map3$1 as m, map3 as n, left as o, map2$1 as p, sequence as r, right as s, map2 as t, EitherV as u, none as v, Some as w, NONE as x, some as y };

package/dist/option.d.mts

@@ -0,0 +1,2 @@
+import { C as OptionV, S as None, _ as fromNullable, b as Option, g as fromEither, h as sequence, m as map3, p as map2, v as none, w as Some, x as NONE, y as some } from "./helpers-BGxhvbJN.mjs";
+export { NONE, None, type Option, OptionV, Some, fromEither, fromNullable, map2, map3, none, sequence, some };

package/dist/option.mjs

@@ -0,0 +1,177 @@
+//#region src/option/model.ts
+const NONE = Symbol("None");
+
+//#endregion
+//#region src/option/option.ts
+function createOption(optionValue) {
+	const option = {
+		filter: (predicate) => option.flatMap((value) => predicate(value) ? option : createOption(NONE)),
+		map: (mapper) => option.flatMap((value) => createOption({ some: mapper(value) })),
+		orElse: (fallback) => option.match(fallback, () => option),
+		ap: function(optA) {
+			return this.flatMap((fn) => optA.match(() => createOption(NONE), (arg) => createOption({ some: fn(arg) })));
+		},
+		zip: (optA) => option.map((value) => (a) => [value, a]).ap(optA),
+		flatten: function() {
+			return this.flatMap((value) => value);
+		},
+		flatMap: (mapper) => option.match(() => forceCast(option), (value) => mapper(value)),
+		tap: (sideEffect) => {
+			option.match(() => {}, sideEffect);
+			return option;
+		},
+		tapNone: (sideEffect) => {
+			option.match(sideEffect, () => {});
+			return option;
+		},
+		match: (onNone, onSome) => isSome(optionValue) ? onSome(optionValue.some) : onNone(),
+		getOrElse: (fallback) => option.match(fallback, (value) => value),
+		toNullable: () => option.match(() => null, (value) => value),
+		toArray: () => option.match(() => [], (val) => [val])
+	};
+	return option;
+}
+function isSome(option) {
+	return typeof option === "object" && "some" in option;
+}
+function forceCast(option) {
+	return option;
+}
+
+//#endregion
+//#region src/option/constructors.ts
+/**
+* Creates an {@link Option} that contains a value.
+*
+* Use this to wrap an existing value into an `Option<T>` representing presence
+* (as opposed to `none`, which represents absence).
+*
+* @typeParam T - Type of the wrapped value.
+* @param some - The value to store in the option.
+* @returns An {@link Option} containing the provided value.
+*/
+function some(some) {
+	return createOption({ some });
+}
+/**
+* Creates an {@link Option} representing the absence of a value.
+*
+* @typeParam T - The type of the value that would be contained if present.
+* @returns An {@link Option} in the `None` state.
+*
+* @example
+* ```ts
+* const value = none<number>();
+* ```
+*/
+function none() {
+	return createOption(NONE);
+}
+/**
+* Creates an {@link Option} from a nullable value.
+*
+* If {@link nullable} is `null` or `undefined`, returns {@link none}.
+* Otherwise, wraps the provided value in {@link some}.
+*
+* @example
+* fromNullable(0).getOrElse(() => 123); // 0
+* fromNullable(null).toNullable(); // null
+*
+* @typeParam T - The non-null value type to wrap.
+* @param nullable - A value that may be `null` or `undefined`.
+* @returns An {@link Option} that is `Some` when the value is present, otherwise `None`.
+*/
+function fromNullable(nullable) {
+	return nullable == null ? none() : some(nullable);
+}
+/**
+* Creates an {@link Option} from an {@link Either} by extracting the Right value.
+*
+* If the Either is Right, returns Some containing the Right value.
+* If the Either is Left, returns None (discarding the Left value).
+*
+* @typeParam L - The type of the Left value (error type) that will be discarded
+* @typeParam R - The type of the Right value that will be preserved in the Option
+* @param either - The Either to convert to an Option
+* @returns Some containing the Right value, or None if the Either was Left
+*
+* @example
+* ```typescript
+* const success = right(42);
+* fromEither(success) // Some(42)
+*
+* const failure = left("error message");
+* fromEither(failure) // None
+* ```
+*/
+function fromEither(either) {
+	return either.match(() => none(), (right) => some(right));
+}
+
+//#endregion
+//#region src/option/helpers.ts
+/**
+* Combines two Options using a mapping function.
+* Only applies the mapper if both Options contain values.
+*
+* @param optA - First Option to combine
+* @param optB - Second Option to combine
+* @param mapper - Function that combines both values
+* @returns Option containing the combined result, or None if either Option is None
+*
+* @example
+* ```typescript
+* const greet = (first, last) => `Hi ${first} ${last}!`
+* map2(some("John"), some("Doe"), greet) // Some("John Doe")
+* map2(some("John"), none<string>(), greet) // None
+* ```
+*/
+function map2(optA, optB, mapper) {
+	return optA.map((a) => (b) => mapper(a, b)).ap(optB);
+}
+/**
+* Combines three Options using a mapping function.
+* Only applies the mapper if all three Options contain values.
+*
+* @param optA - First Option to combine
+* @param optB - Second Option to combine
+* @param optC - Third Option to combine
+* @param mapper - Function that combines all three values
+* @returns Option containing the combined result, or None if any Option is None
+*
+* @example
+* ```typescript
+* const toDateString = (d, m, y) => `${d}/${m}/${y}`
+* map3(some(15), some(6), some(2023), toDateString) // Some("15/6/2023")
+* map3(some(15), some(6), none<number>(), toDateString) // None
+* ```
+*/
+function map3(optA, optB, optC, mapper) {
+	return optA.map((a) => (b) => (c) => mapper(a, b, c)).ap(optB).ap(optC);
+}
+/**
+* Converts an array of Options into an Option of array.
+* If all Options in the array contain values, returns Some containing an array of all values.
+* If any Option in the array is None, returns None.
+*
+* @param opts - Array of Options to sequence
+* @returns Some containing array of all values if all Options are Some, otherwise None
+*
+* @example
+* ```typescript
+* sequence([some(1), some(2), some(3)]) // Some([1, 2, 3])
+* sequence([some(1), none(), some(3)]) // None
+* ```
+*/
+function sequence(opts) {
+	const out = [];
+	for (const opt of opts) {
+		const [value] = opt.toArray();
+		if (!value) return none();
+		out.push(value);
+	}
+	return some(out);
+}
+
+//#endregion
+export { NONE, fromEither, fromNullable, map2, map3, none, sequence, some };

package/dist/task.d.mts

@@ -0,0 +1,16 @@
+//#region src/task.d.ts
+type TaskV<T> = () => Promise<T>;
+type Task<_T> = {
+  map: never;
+  ap: never;
+  flatMap: never;
+  tap: never;
+  run: never;
+};
+declare function task<T>(): Task<T>;
+declare function fromPromise<T>(_thunk: () => Promise<T>): void;
+declare function all(): void;
+declare function traverse(): void;
+declare function sequence(): void;
+//#endregion
+export { Task, TaskV, all, fromPromise, sequence, task, traverse };

package/dist/task.mjs

@@ -0,0 +1,19 @@
+//#region src/task.ts
+function task() {
+	throw new Error("Not implemented");
+}
+function fromPromise(_thunk) {
+	throw new Error("Not implemented");
+}
+function all() {
+	throw new Error("Not implemented");
+}
+function traverse() {
+	throw new Error("Not implemented");
+}
+function sequence() {
+	throw new Error("Not implemented");
+}
+
+//#endregion
+export { all, fromPromise, sequence, task, traverse };

package/dist/validation.d.mts

@@ -0,0 +1,16 @@
+import { l as Either } from "./helpers-BGxhvbJN.mjs";
+
+//#region src/validation.d.ts
+type ValidationV<_E, _T> = object;
+type Validation<_E, _T> = {
+  ap: unknown;
+  map: unknown;
+  map3: unknown;
+};
+declare function valid<T, E = never>(): Validation<E, T>;
+declare function invalid<E, T = never>(): Validation<E, T>;
+declare function fromEither<E, T>(_either: Either<E, T>): Validation<E, T>;
+declare function traverse(): void;
+declare function sequence(): void;
+//#endregion
+export { Validation, ValidationV, fromEither, invalid, sequence, traverse, valid };

package/dist/validation.mjs

@@ -0,0 +1,19 @@
+//#region src/validation.ts
+function valid() {
+	throw new Error("Not implemented");
+}
+function invalid() {
+	throw new Error("Not implemented");
+}
+function fromEither(_either) {
+	throw new Error("Not implemented");
+}
+function traverse() {
+	throw new Error("Not implemented");
+}
+function sequence() {
+	throw new Error("Not implemented");
+}
+
+//#endregion
+export { fromEither, invalid, sequence, traverse, valid };

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "ok-fp",
+	"version": "0.0.1",
+	"description": "Essential typed effects for TypeScript.",
+	"keywords": [
+		"typescript",
+		"fp",
+		"functional-programming",
+		"effects",
+		"algebraic-data-types",
+		"monads",
+		"option",
+		"either",
+		"validation",
+		"task",
+		"taskEither"
+	],
+	"homepage": "https://github.com/pwlmc/okfp#readme",
+	"bugs": {
+		"url": "https://github.com/pwlmc/okfp/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pwlmc/okfp.git"
+	},
+	"license": "MIT",
+	"author": "pwlmc",
+	"type": "module",
+	"main": "dist/",
+	"exports": {
+		"./either": {
+			"types": "./dist/either.d.mts",
+			"default": "./dist/either.mjs"
+		},
+		"./option": {
+			"types": "./dist/option.mts",
+			"default": "./dist/option.mjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"lint": "biome check src/",
+		"test": "vitest",
+		"typecheck": "tsc --noEmit",
+		"build": "tsdown  --format esm --dts",
+		"dev": "tsdown --format esm --dts --watch",
+		"docs:dev": "vitepress dev docs",
+		"docs:build": "vitepress build docs",
+		"docs:preview": "vitepress preview docs"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.4",
+		"@vitest/coverage-v8": "^4.0.18",
+		"tsdown": "^0.20.3",
+		"typescript": "^5.9.3",
+		"vitepress": "^1.6.4",
+		"vitest": "^4.0.18"
+	}
+}