functype 0.11.2 → 0.14.0

package/dist/do/index.d.ts

@@ -0,0 +1,240 @@
+import { O as Option, E as Either, L as List, T as Try, y as Reshapeable, d as DoProtocol } from '../Either-D4P39LPj.js';
+export { D as DO_PROTOCOL, a as DoResult } from '../Either-D4P39LPj.js';
+import '../Typeable-CitTP1ay.js';
+
+/**
+ * Generator-based Do-notation for monadic comprehensions
+ * Provides Scala-like for-comprehension syntax using JavaScript generators
+ *
+ * ## Scala Equivalents
+ *
+ * Functype:  `const x = yield* $(Option(5))`
+ * Scala:     `x <- Some(5)`
+ *
+ * Functype:  `return x + y`
+ * Scala:     `yield x + y`
+ *
+ * ## Core Concepts
+ *
+ * - **Generators**: Use `yield* $(monad)` to extract values from monads
+ * - **Short-circuiting**: None/Left/Failure automatically propagates
+ * - **Type inference**: The $ helper provides proper TypeScript types
+ * - **First monad wins**: Return type matches the first yielded monad
+ * - **Cartesian products**: Multiple List yields create all combinations
+ *
+ * ## Usage Rules
+ *
+ * 1. All yielded values MUST be monadic (Option, Either, List, Try)
+ * 2. Use the $ helper for type inference: `yield* $(Option(value))`
+ * 3. Raw values should be assigned directly without yielding
+ * 4. Mixed monad types are supported via Reshapeable interface
+ *
+ * @example
+ * // Basic Option chaining (Scala: for { x <- Some(5); y <- Some(10) } yield x + y)
+ * const result = Do(function* () {
+ *   const x = yield* $(Option(5))        // Extract from Option
+ *   const y = yield* $(Option(10))       // Extract from another Option
+ *   return x + y                         // Return final value
+ * })
+ * // result: Option<number> with value 15
+ *
+ * @example
+ * // List comprehension (Scala: for { x <- List(1,2); y <- List(10,20) } yield (x,y))
+ * const pairs = Do(function* () {
+ *   const x = yield* $(List([1, 2]))     // Iterates: 1, 2
+ *   const y = yield* $(List([10, 20]))   // Iterates: 10, 20
+ *   return { x, y }                      // All combinations
+ * })
+ * // pairs: List([{x:1,y:10}, {x:1,y:20}, {x:2,y:10}, {x:2,y:20}])
+ *
+ * @example
+ * // Error propagation with Either
+ * const validate = Do(function* () {
+ *   const email = yield* $(validateEmail(input))  // Either<string, Email>
+ *   const user = yield* $(fetchUser(email))       // Either<string, User>
+ *   const saved = yield* $(saveUser(user))        // Either<string, Result>
+ *   return saved
+ * })
+ * // If any step returns Left, entire chain short-circuits with that error
+ *
+ * @see {@link https://github.com/jordanburke/functype/blob/main/docs/do-notation.md} Full documentation
+ * @module Do
+ */
+
+type OptionLike = {
+    _tag: "Some" | "None";
+    isSome(): boolean;
+    get(): unknown;
+};
+type EitherLike = {
+    _tag: "Left" | "Right";
+    isLeft(): boolean;
+    isRight(): boolean;
+    value: unknown;
+};
+type ListLike = {
+    _tag: "List";
+    toArray(): unknown[];
+};
+type TryLike = {
+    _tag: "Success" | "Failure";
+    isSuccess(): boolean;
+    get(): unknown;
+};
+/**
+ * Executes a generator-based monadic comprehension
+ * Returns the same monad type as the first yielded monad (Scala semantics)
+ *
+ * - Option comprehensions return Option (None on short-circuit)
+ * - Either comprehensions return Either (Left with error on short-circuit)
+ * - List comprehensions return List (empty or cartesian product)
+ * - Try comprehensions return Try (Failure with error on short-circuit)
+ *
+ * Type Inference Notes:
+ * - TypeScript infers the correct return type for homogeneous comprehensions
+ * - For mixed monad types, TypeScript returns a union type
+ * - Use DoTyped<T> or type assertions for mixed scenarios
+ *
+ * @example
+ * ```typescript
+ * // Option comprehension returns Option:
+ * const result = Do(function* () {
+ *   const x = yield* $(Option(5));
+ *   const y = yield* $(Option(10));
+ *   return x + y;
+ * });
+ * // result: Option(15)
+ *
+ * // Either comprehension returns Either:
+ * const result = Do(function* () {
+ *   const x = yield* $(Right(5));
+ *   const y = yield* $(Left("error"));
+ *   return x + y;
+ * });
+ * // result: Left("error") - error is preserved
+ *
+ * // List comprehension returns List with cartesian product:
+ * const result = Do(function* () {
+ *   const x = yield* $(List([1, 2]));
+ *   const y = yield* $(List([3, 4]));
+ *   return x + y;
+ * });
+ * // result: List([4, 5, 5, 6])
+ *
+ * // Mixed types - use type assertion or DoTyped:
+ * const result = Do(function* () {
+ *   const x = yield* $(Option(5));
+ *   const y = yield* $(Right<string, number>(10));
+ *   return x + y;
+ * }) as Option<number>;
+ * // result: Option(15)
+ * ```
+ *
+ * @param gen - Generator function that yields monads and returns a result
+ * @returns The same monad type as the first yield
+ */
+declare function Do<T>(gen: () => Generator<OptionLike, T, unknown>): Option<T>;
+declare function Do<L, R>(gen: () => Generator<EitherLike, R, unknown>): Either<L, R>;
+declare function Do<T>(gen: () => Generator<ListLike, T, unknown>): List<T>;
+declare function Do<T>(gen: () => Generator<TryLike, T, unknown>): Try<T>;
+declare function Do<T>(gen: () => Generator<OptionLike | EitherLike | ListLike | TryLike, T, unknown>): Reshapeable<T>;
+declare function Do<T>(gen: () => Generator<unknown, T, unknown>): unknown;
+/**
+ * Executes an async generator-based monadic comprehension
+ * Returns the same monad type as the first yielded monad
+ *
+ * @example
+ * ```typescript
+ * const result = await DoAsync(async function* () {
+ *   const user = yield* $(await fetchUser(id));       // Promise<Option<User>> → User
+ *   const profile = yield* $(await getProfile(user)); // Promise<Either<Error, Profile>> → Profile
+ *   return { user, profile };
+ * });
+ * // result type matches first yield
+ * ```
+ *
+ * @param gen - Async generator function that yields monads/promises and returns a result
+ * @returns Promise of the same monad type as first yield
+ */
+declare function DoAsync<T>(gen: () => AsyncGenerator<OptionLike, T, unknown>): Promise<Option<T>>;
+declare function DoAsync<L, R>(gen: () => AsyncGenerator<EitherLike, R, unknown>): Promise<Either<L, R>>;
+declare function DoAsync<T>(gen: () => AsyncGenerator<ListLike, T, unknown>): Promise<List<T>>;
+declare function DoAsync<T>(gen: () => AsyncGenerator<TryLike, T, unknown>): Promise<Try<T>>;
+declare function DoAsync<T>(gen: () => AsyncGenerator<OptionLike | EitherLike | ListLike | TryLike, T, unknown>): Promise<Reshapeable<T>>;
+declare function DoAsync<T>(gen: () => AsyncGenerator<unknown, T, unknown>): Promise<unknown>;
+/**
+ * Helper function to check if a value implements the Do protocol
+ * @param value - Value to check
+ * @returns True if the value implements DoProtocol
+ */
+declare function isDoCapable<T>(value: unknown): value is DoProtocol<T>;
+/**
+ * Manually unwrap a monad using the Do protocol
+ * Useful for testing or when you need to unwrap outside of a Do-comprehension
+ *
+ * @param monad - Monad to unwrap
+ * @returns The unwrapped value
+ * @throws Error if the monad cannot be unwrapped
+ */
+declare function unwrap<T>(monad: DoProtocol<T>): T;
+/**
+ * Type helper for Do-notation generators.
+ * Provides better type hints in IDEs.
+ *
+ * @example
+ * ```typescript
+ * const result = Do(function* (): DoGenerator<number> {
+ *   const x = yield* $(List([1, 2]))  // x is still unknown but return type is clear
+ *   const y = yield* $(List([3, 4]))
+ *   return x + y
+ * })
+ * ```
+ */
+type DoGenerator<T, TYield = unknown> = Generator<TYield, T, unknown>;
+/**
+ * Extracts values from monads in Do-notation with type inference.
+ * The '$' symbol is the universal extraction operator in functional programming.
+ *
+ * @example
+ * ```typescript
+ * const result = Do(function* () {
+ *   const x = yield* $(Option(5))        // x: number
+ *   const y = yield* $(List([1, 2, 3]))  // y: number (for cartesian product)
+ *   const name = yield* $(Right("Alice")) // name: string
+ *   return `${name}: ${x + y}`
+ * })
+ * ```
+ *
+ * @param monad - Any monad that can be unwrapped (Option, Either, List, Try, etc.)
+ * @returns A generator that yields the monad and returns its extracted value
+ */
+declare function $<T>(monad: Option<T>): Generator<Option<T>, T, T>;
+declare function $<L, R>(monad: Either<L, R>): Generator<Either<L, R>, R, R>;
+declare function $<T>(monad: List<T>): Generator<List<T>, T, T>;
+declare function $<T>(monad: Try<T>): Generator<Try<T>, T, T>;
+declare function $<T>(monad: DoProtocol<T>): Generator<DoProtocol<T>, T, T>;
+declare function $<M>(monad: M): Generator<M, InferYieldType<M>, InferYieldType<M>>;
+type InferYieldType<M> = M extends {
+    isSome(): boolean;
+    get(): infer T;
+} ? T : M extends {
+    isRight(): boolean;
+    value: infer R;
+} ? R : M extends {
+    toArray(): (infer T)[];
+} ? T : M extends {
+    isSuccess(): boolean;
+    get(): infer T;
+} ? T : M extends DoProtocol<infer T> ? T : unknown;
+declare const NoneError: (message?: string) => Error;
+interface LeftErrorType<L> extends Error {
+    value: L;
+}
+declare const LeftError: <L>(value: L, message?: string) => LeftErrorType<L>;
+declare const EmptyListError: (message?: string) => Error;
+interface FailureErrorType extends Error {
+    cause: Error;
+}
+declare const FailureError: (cause: Error, message?: string) => FailureErrorType;
+
+export { $, Do, DoAsync, type DoGenerator, DoProtocol, EmptyListError, FailureError, type FailureErrorType, LeftError, type LeftErrorType, NoneError, isDoCapable, unwrap };

package/dist/do/index.mjs

@@ -0,0 +1,2 @@
+export{P as $,a as DO_PROTOCOL,L as Do,M as DoAsync,S as EmptyListError,T as FailureError,R as LeftError,Q as NoneError,N as isDoCapable,O as unwrap}from'../chunk-7VZBQDNM.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-YBBRJTHY.mjs';//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/do/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/either/index.d.ts

@@ -1,2 +1,2 @@
-export { E as Either, c as Left, R as Right, b as TestEither, f as TypeCheckLeft, e as TypeCheckRight, d as isLeft, i as isRight, t as tryCatch, g as tryCatchAsync } from '../Either-DgkP4DUw.js';
-import '../Serializable-CK9upOU0.js';
+export { E as Either, f as Left, R as Right, e as TestEither, j as TypeCheckLeft, h as TypeCheckRight, g as isLeft, i as isRight, t as tryCatch, k as tryCatchAsync } from '../Either-D4P39LPj.js';
+import '../Typeable-CitTP1ay.js';

package/dist/either/index.mjs

@@ -1,2 +1,2 @@
-export{q as Either,j as Left,i as Right,o as TypeCheckLeft,n as TypeCheckRight,l as isLeft,k as isRight,m as tryCatch,p as tryCatchAsync}from'../chunk-PPFDDUSD.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-YBBRJTHY.mjs';//# sourceMappingURL=index.mjs.map
+export{u as Either,n as Left,m as Right,s as TypeCheckLeft,r as TypeCheckRight,p as isLeft,o as isRight,q as tryCatch,t as tryCatchAsync}from'../chunk-7VZBQDNM.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-YBBRJTHY.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/fpromise/index.d.ts

@@ -1,5 +1,5 @@
-import { E as Either } from '../Either-DgkP4DUw.js';
-import { T as Type } from '../Serializable-CK9upOU0.js';
+import { E as Either } from '../Either-D4P39LPj.js';
+import { T as Type } from '../Typeable-CitTP1ay.js';
 
 /**
  * Error context information that provides additional metadata about errors.

package/dist/fpromise/index.mjs

@@ -1,2 +1,2 @@
-export{K as FPromise,J as FPromiseCompanion}from'../chunk-PPFDDUSD.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-YBBRJTHY.mjs';//# sourceMappingURL=index.mjs.map
+export{X as FPromise,W as FPromiseCompanion}from'../chunk-7VZBQDNM.mjs';import'../chunk-BQJB6CCW.mjs';import'../chunk-YBBRJTHY.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map