functype 0.11.2 → 0.14.0

package/README.md

@@ -23,6 +23,7 @@ Functype is a lightweight functional programming library for TypeScript, drawing
 - **Either Type**: Express computation results with potential failures using `Left` and `Right`
 - **List, Set, Map**: Immutable collection types with functional operators
 - **Try Type**: Safely execute operations that might throw exceptions
+- **Do-notation**: Scala-like for-comprehensions using JavaScript generators for monadic composition
 - **Task**: Handle synchronous and asynchronous operations with error handling
 - **Lazy**: Deferred computation with memoization
 - **Tuple**: Type-safe fixed-length arrays
@@ -189,40 +190,142 @@ const result = Lazy(() => 10)
   .get() // 30
 ```
 
+### Do-notation (Scala-like For-Comprehensions)
+
+Functype provides generator-based Do-notation for monadic composition, similar to Scala's for-comprehensions:
+
+```typescript
+import { Do, DoAsync, $ } from "functype"
+import { Option, Right, Left, List, Try } from "functype"
+
+// Chain multiple Option operations
+const result = Do(function* () {
+  const x = yield* $(Option(5)) // Extract value from Option
+  const y = yield* $(Option(10)) // Extract value from another Option
+  const z = x + y // Regular computation
+  return z * 2 // Return final result
+})
+// result: Option<number> with value 30
+
+// Mix different monad types (with Reshapeable)
+const mixed = Do(function* () {
+  const a = yield* $(Option(5)) // From Option
+  const b = yield* $(Right<string, number>(10)) // From Either
+  const c = yield* $(List([15])) // From List
+  const d = yield* $(Try(() => 20)) // From Try
+  return a + b + c + d
+})
+// Convert result to desired type
+const asOption = mixed.toOption() // Option<number> with value 50
+
+// Error propagation - short-circuits on failure
+const validation = Do(function* () {
+  const email = yield* $(validateEmail("user@example.com")) // Returns Option
+  const user = yield* $(fetchUser(email)) // Returns Either
+  const profile = yield* $(loadProfile(user.id)) // Returns Try
+  return profile
+})
+// If any step fails, the entire computation short-circuits
+
+// List comprehensions (cartesian products)
+const pairs = Do(function* () {
+  const x = yield* $(List([1, 2, 3]))
+  const y = yield* $(List([10, 20]))
+  return { x, y, product: x * y }
+})
+// pairs: List with 6 elements (all combinations)
+
+// Async operations with DoAsync
+const asyncResult = await DoAsync(async function* () {
+  const user = yield* $(await fetchUserAsync(userId)) // Async Option
+  const score = yield* $(await getScoreAsync(user.id)) // Async Either
+  const bonus = yield* $(await calculateBonus(score)) // Async Try
+  return score + bonus
+})
+```
+
+**Key Differences from Scala:**
+
+- Uses `yield* $(monad)` instead of `x <- monad`
+- No native guard syntax (use conditions with early return)
+- Always returns the type of the first yielded monad
+- Mixed types supported via Reshapeable interface
+
 ### Task
 
+Task v2 provides structured error handling with the **Ok/Err pattern**, returning `TaskOutcome<T>` for all operations:
+
 ```typescript
-import { Task } from "functype"
+import { Task, Ok, Err, type TaskOutcome } from "functype"
 
-// Synchronous operations with error handling
-const syncResult = Task().Sync(
-  () => "success",
-  (error) => new Error(`Failed: ${error}`),
+// Task v2: All operations return TaskOutcome<T>
+const syncResult = Task().Sync(() => "success")
+// Returns: TaskSuccess<string> (extends TaskOutcome<string>)
+
+const asyncResult = await Task().Async(async () => "value")
+// Returns: TaskOutcome<string>
+
+// Explicit Ok/Err returns for precise control
+const explicitResult = await Task().Async(async (): Promise<TaskOutcome<string>> => {
+  if (Math.random() > 0.5) {
+    return Ok("success") // Explicit success
+  }
+  return Err<string>("failed") // Explicit failure
+})
+
+// Auto-wrapping: raw values become Ok, thrown errors become Err
+const autoWrapped = await Task().Async(async () => {
+  if (condition) {
+    return "raw value" // Auto-wrapped as Ok("raw value")
+  }
+  throw new Error("failed") // Auto-wrapped as Err(error)
+})
+
+// Error recovery: error handlers can return Ok
+const recovered = await Task().Async(
+  async () => {
+    throw new Error("initial error")
+  },
+  async (error) => Ok("recovered from error"), // Recovery!
 )
 
-// Asynchronous operations
-const asyncTask = async () => {
-  const result = await Task().Async(
-    async () => await fetchData(),
-    async (error) => new Error(`Fetch failed: ${error}`),
-  )
-  return result
+// Working with results
+if (asyncResult.isSuccess()) {
+  console.log(asyncResult.value) // Access the success value
+} else {
+  console.error(asyncResult.error) // Access the error (Throwable)
 }
 
+// Chaining with TaskOutcome
+const chainedResult = await Task().Async(async () => {
+  const firstResult = await Task().Async(async () => "first")
+  if (firstResult.isFailure()) {
+    return firstResult // Propagate failure
+  }
+
+  const secondResult = await Task().Async(async () => "second")
+  if (secondResult.isFailure()) {
+    return secondResult
+  }
+
+  return Ok(`${firstResult.value} + ${secondResult.value}`)
+})
+
 // Converting promise-based functions to Task
 const fetchUserAPI = (userId: string): Promise<User> => fetch(`/api/users/${userId}`).then((r) => r.json())
 
-// Use the adapter pattern for seamless integration
-const fetchUser = Task({ name: "UserFetch" }).fromPromise(fetchUserAPI)
+const fetchUser = Task.fromPromise(fetchUserAPI)
+// Returns: (userId: string) => FPromise<TaskOutcome<User>>
 
-// Later use it with standard promise patterns
-fetchUser("user123")
-  .then((user) => console.log(user))
-  .catch((error) => console.error(error))
+const userResult = await fetchUser("user123")
+if (userResult.isSuccess()) {
+  console.log(userResult.value) // User object
+}
 
-// Or convert Task results back to promises
-const taskResult = Task().Sync(() => "hello world")
-const promise = Task().toPromise(taskResult) // Promise<string>
+// Convert TaskOutcome back to Promise (for interop)
+const promise = Task.toPromise(asyncResult)
+// Success → resolves with value
+// Failure → rejects with error
 ```
 
 ### Branded Types

package/dist/{Either-DgkP4DUw.d.ts → Either-D4P39LPj.d.ts}

@@ -1,4 +1,85 @@
-import { T as Type, a as Typeable, S as Serializable, F as Foldable, P as Pipe } from './Serializable-CK9upOU0.js';
+import { T as Type, P as Pipe, a as Typeable, S as Serializable, F as Foldable } from './Typeable-CitTP1ay.js';
+
+/**
+ * Protocol definitions for Do-notation
+ * Separated from main Do module to avoid circular dependencies
+ */
+/**
+ * Protocol symbol for Do-notation unwrapping
+ * All monads that support Do-notation should implement this protocol
+ */
+declare const DO_PROTOCOL: unique symbol;
+/**
+ * Result type for Do-notation unwrapping
+ * Indicates whether unwrapping succeeded and provides the value or error
+ */
+type DoResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    empty: true;
+} | {
+    ok: false;
+    empty: false;
+    error: unknown;
+};
+/**
+ * Interface for types that support Do-notation
+ * Implementing this interface allows a type to be yielded in Do-comprehensions
+ */
+interface DoProtocol<T> {
+    [DO_PROTOCOL](): DoResult<T>;
+}
+
+/**
+ * Extractable type class for data structures that can extract their values
+ * with various fallback strategies.
+ *
+ * This interface is implemented by Option, Either, and other types that
+ * wrap values and need safe extraction methods.
+ */
+interface Extractable<T extends Type> {
+    /**
+     * Extracts the value unsafely
+     * @throws Error if the container is empty
+     * @returns The contained value
+     */
+    get(): T;
+    /**
+     * Returns the contained value or a default value
+     * @param defaultValue - The value to return if extraction fails
+     * @returns The contained value or defaultValue
+     */
+    getOrElse(defaultValue: T): T;
+    /**
+     * Returns the contained value or throws an error
+     * @param error - Optional error to throw (implementations may have defaults)
+     * @returns The contained value
+     * @throws The specified error if extraction fails
+     */
+    getOrThrow(error?: Error): T;
+    /**
+     * Returns this container if it has a value, otherwise returns the alternative
+     * @param alternative - The alternative container
+     * @returns This container or the alternative
+     */
+    orElse(alternative: Extractable<T>): Extractable<T>;
+    /**
+     * Returns the contained value or null
+     * @returns The contained value or null
+     */
+    orNull(): T | null;
+    /**
+     * Returns the contained value or undefined
+     * @returns The contained value or undefined
+     */
+    orUndefined(): T | undefined;
+}
+/**
+ * Type guard to check if a value implements ExtractableOption
+ */
+declare function isExtractable<T extends Type>(value: unknown): value is Extractable<T>;
 
 /**
  * Universal operations that work on any container (single-value or collection).
@@ -144,6 +225,164 @@ interface Promisable<A extends Type> {
     toPromise(): Promise<A>;
 }
 
+/**
+ * Possible types of Try instances
+ */
+type TypeNames = "Success" | "Failure";
+interface Try<T> extends FunctypeBase<T, TypeNames>, Extractable<T>, Pipe<T>, Promisable<T>, DoProtocol<T>, Reshapeable<T> {
+    readonly _tag: TypeNames;
+    readonly error: Error | undefined;
+    isSuccess(): this is Try<T> & {
+        readonly _tag: "Success";
+        error: undefined;
+    };
+    isFailure(): this is Try<T> & {
+        readonly _tag: "Failure";
+        error: Error;
+    };
+    get: () => T;
+    getOrElse: (defaultValue: T) => T;
+    getOrThrow: (error?: Error) => T;
+    orElse: (alternative: Try<T>) => Try<T>;
+    orNull: () => T | null;
+    orUndefined: () => T | undefined;
+    orThrow: (error: Error) => T;
+    toOption: () => Option<T>;
+    toEither: <E extends Type>(leftValue: E) => Either<E, T>;
+    toList: () => List<T>;
+    toTry: () => Try<T>;
+    map: <U>(f: (value: T) => U) => Try<U>;
+    ap: <U>(ff: Try<(value: T) => U>) => Try<U>;
+    flatMap: <U>(f: (value: T) => Try<U>) => Try<U>;
+    flatMapAsync: <U>(f: (value: T) => Promise<Try<U>>) => Promise<Try<U>>;
+    /**
+     * Pattern matches over the Try, applying onFailure if Failure and onSuccess if Success
+     * @param onFailure - Function to apply if the Try is Failure
+     * @param onSuccess - Function to apply if the Try is Success
+     * @returns The result of applying the appropriate function
+     */
+    fold: <U extends Type>(onFailure: (error: Error) => U, onSuccess: (value: T) => U) => U;
+    toString: () => string;
+    /**
+     * Pattern matches over the Try, applying a handler function based on the variant
+     * @param patterns - Object with handler functions for Success and Failure variants
+     * @returns The result of applying the matching handler function
+     */
+    match<R>(patterns: {
+        Success: (value: T) => R;
+        Failure: (error: Error) => R;
+    }): R;
+    toValue(): {
+        _tag: TypeNames;
+        value: T | Error;
+    };
+}
+declare const Try: (<T>(f: () => T) => Try<T>) & {
+    /**
+     * Creates a Try from JSON string
+     * @param json - The JSON string
+     * @returns Try instance
+     */
+    fromJSON: <T>(json: string) => Try<T>;
+    /**
+     * Creates a Try from YAML string
+     * @param yaml - The YAML string
+     * @returns Try instance
+     */
+    fromYAML: <T>(yaml: string) => Try<T>;
+    /**
+     * Creates a Try from binary string
+     * @param binary - The binary string
+     * @returns Try instance
+     */
+    fromBinary: <T>(binary: string) => Try<T>;
+};
+
+/**
+ * Interface for types that can be reshaped (converted) between different monadic containers.
+ * Provides standard conversion methods to transform between Option, Either, List, and Try types.
+ *
+ * @typeParam T - The type of the value contained in the monad
+ *
+ * @example
+ * // Convert Option to Either
+ * const opt = Option(5)
+ * const either = opt.toEither("None value")  // Right(5)
+ *
+ * @example
+ * // Convert Either to Option
+ * const right = Right(10)
+ * const option = right.toOption()  // Some(10)
+ *
+ * @example
+ * // Convert List to Try
+ * const list = List([1, 2, 3])
+ * const tryVal = list.toTry()  // Success(1) - uses first element
+ *
+ * @example
+ * // Use with Do comprehensions
+ * const result = Do(function* () {
+ *   const x = yield* $(Option(5))
+ *   const y = yield* $(Right<string, number>(10))
+ *   return x + y
+ * })
+ *
+ * // Convert to desired type for chaining
+ * const asOption = result.toOption()
+ * asOption.map(x => x * 2).getOrElse(0)
+ */
+interface Reshapeable<T extends Type> {
+    /**
+     * Converts this monad to an Option.
+     *
+     * Conversion rules:
+     * - Option: returns self
+     * - Either: Right → Some, Left → None
+     * - List: non-empty → Some(head), empty → None
+     * - Try: Success → Some, Failure → None
+     *
+     * @returns An Option containing the value if present, None otherwise
+     */
+    toOption(): Option<T>;
+    /**
+     * Converts this monad to an Either.
+     *
+     * Conversion rules:
+     * - Option: Some → Right, None → Left(leftValue)
+     * - Either: returns self
+     * - List: non-empty → Right(head), empty → Left(leftValue)
+     * - Try: Success → Right, Failure → Left(error)
+     *
+     * @param leftValue - The value to use for the Left case when the source is empty/none/failure
+     * @returns An Either with the value as Right or the provided leftValue as Left
+     */
+    toEither<E extends Type>(leftValue: E): Either<E, T>;
+    /**
+     * Converts this monad to a List.
+     *
+     * Conversion rules:
+     * - Option: Some → List([value]), None → List([])
+     * - Either: Right → List([value]), Left → List([])
+     * - List: returns self
+     * - Try: Success → List([value]), Failure → List([])
+     *
+     * @returns A List containing the value(s) if present, empty List otherwise
+     */
+    toList(): List<T>;
+    /**
+     * Converts this monad to a Try.
+     *
+     * Conversion rules:
+     * - Option: Some → Success, None → Failure(Error("None"))
+     * - Either: Right → Success, Left → Failure(Error(leftValue))
+     * - List: non-empty → Success(head), empty → Failure(Error("Empty list"))
+     * - Try: returns self
+     *
+     * @returns A Try containing Success with the value or Failure with an appropriate error
+     */
+    toTry(): Try<T>;
+}
+
 /**
  * Creates a Some variant of Option containing a value.
  * @param value - The value to wrap in Some
@@ -175,7 +414,7 @@ declare const OptionConstructor: <T extends Type>(value: T | null | undefined) =
  * It's used to handle potentially null or undefined values in a type-safe way.
  * @typeParam T - The type of the value contained in the Option
  */
-interface Option<T extends Type> extends Functype<T, "Some" | "None">, Promisable<T> {
+interface Option<T extends Type> extends Functype<T, "Some" | "None">, Promisable<T>, DoProtocol<T>, Reshapeable<T> {
     /** The contained value (undefined for None) */
     readonly value: T | undefined;
     /** Whether this Option contains no value */
@@ -368,7 +607,7 @@ declare const Option: (<T extends Type>(value: T | null | undefined) => Option<T
     fromBinary: <T>(binary: string) => Option<T>;
 };
 
-interface List<A> extends FunctypeCollection<A, "List"> {
+interface List<A> extends FunctypeCollection<A, "List">, DoProtocol<A>, Reshapeable<A> {
     readonly length: number;
     readonly [Symbol.iterator]: () => Iterator<A>;
     map: <B>(f: (a: A) => B) => List<B>;
@@ -464,55 +703,6 @@ interface Collection<A> {
     toString(): string;
 }
 
-/**
- * Extractable type class for data structures that can extract their values
- * with various fallback strategies.
- *
- * This interface is implemented by Option, Either, and other types that
- * wrap values and need safe extraction methods.
- */
-interface Extractable<T extends Type> {
-    /**
-     * Extracts the value unsafely
-     * @throws Error if the container is empty
-     * @returns The contained value
-     */
-    get(): T;
-    /**
-     * Returns the contained value or a default value
-     * @param defaultValue - The value to return if extraction fails
-     * @returns The contained value or defaultValue
-     */
-    getOrElse(defaultValue: T): T;
-    /**
-     * Returns the contained value or throws an error
-     * @param error - Optional error to throw (implementations may have defaults)
-     * @returns The contained value
-     * @throws The specified error if extraction fails
-     */
-    getOrThrow(error?: Error): T;
-    /**
-     * Returns this container if it has a value, otherwise returns the alternative
-     * @param alternative - The alternative container
-     * @returns This container or the alternative
-     */
-    orElse(alternative: Extractable<T>): Extractable<T>;
-    /**
-     * Returns the contained value or null
-     * @returns The contained value or null
-     */
-    orNull(): T | null;
-    /**
-     * Returns the contained value or undefined
-     * @returns The contained value or undefined
-     */
-    orUndefined(): T | undefined;
-}
-/**
- * Type guard to check if a value implements ExtractableOption
- */
-declare function isExtractable<T extends Type>(value: unknown): value is Extractable<T>;
-
 /**
  * Pattern matching interface for functional data types.
  *
@@ -628,7 +818,7 @@ declare const tryCatchAsync: <L extends Type, R extends Type>(f: () => Promise<R
  * @module Either
  * @category Core
  */
-interface Either<L extends Type, R extends Type> extends FunctypeBase<R, "Left" | "Right">, Promisable<R> {
+interface Either<L extends Type, R extends Type> extends FunctypeBase<R, "Left" | "Right">, Promisable<R>, DoProtocol<R>, Reshapeable<R> {
     readonly _tag: "Left" | "Right";
     value: L | R;
     isLeft(): this is Either<L, R> & {
@@ -713,4 +903,4 @@ declare const Either: {
     fromBinary: <L extends Type, R extends Type>(binary: string) => Either<L, R>;
 };
 
-export { type Applicative as A, type Collection as C, Either as E, type FunctypeBase as F, List as L, type Matchable as M, None as N, Option as O, type Promisable as P, Right as R, Some as S, type Traversable as T, type Extractable as a, type TestEither as b, Left as c, isLeft as d, TypeCheckRight as e, TypeCheckLeft as f, tryCatchAsync as g, isExtractable as h, isRight as i, type Functype as j, type FunctypeCollection as k, MatchableUtils as l, OptionConstructor as m, Set as n, type CollectionOps as o, type ContainerOps as p, type AsyncMonad as q, type Functor as r, type Monad as s, tryCatch as t };
+export { type Applicative as A, type Collection as C, DO_PROTOCOL as D, Either as E, type FunctypeBase as F, List as L, type Matchable as M, None as N, Option as O, type Promisable as P, Right as R, Some as S, Try as T, type DoResult as a, type Extractable as b, type Traversable as c, type DoProtocol as d, type TestEither as e, Left as f, isLeft as g, TypeCheckRight as h, isRight as i, TypeCheckLeft as j, tryCatchAsync as k, isExtractable as l, type Functype as m, type FunctypeCollection as n, MatchableUtils as o, OptionConstructor as p, Set as q, type TypeNames as r, type CollectionOps as s, tryCatch as t, type ContainerOps as u, type AsyncMonad as v, type Functor as w, type Monad as x, type Reshapeable as y };