functype 0.8.67 → 0.8.69

package/dist/fpromise/index.d.ts

@@ -1,3 +1,373 @@
-export { f as ErrorContext, F as FPromise, g as FPromiseCompanion } from '../option/index.js';
-import '../Tuple-DfdXAbL_.js';
-import '../branded/index.js';
+import { E as Either } from '../Either-BfXNbTHo.js';
+import { a as Type } from '../Valuable-CtuVEKTZ.js';
+
+/**
+ * Error context information that provides additional metadata about errors.
+ * This context is passed to error mapping functions to provide more information
+ * about the error that occurred.
+ *
+ * @property originalError - The original error that was thrown
+ * @property stack - The stack trace of the error, if available
+ * @property timestamp - The timestamp when the error occurred
+ */
+type ErrorContext = {
+    originalError: unknown;
+    stack?: string;
+    timestamp: number;
+};
+/**
+ * Static utility methods for FPromise using the Companion pattern.
+ * These methods provide factory functions and utilities for working with FPromises.
+ */
+declare const FPromiseCompanion: {
+    /**
+     * Creates an FPromise that resolves to the provided value.
+     *
+     * @template T - The type of the value
+     * @template E - The type of the error (defaults to never since this FPromise won't reject)
+     * @param value - The value to resolve with
+     * @returns An FPromise that resolves to the value
+     *
+     * @example
+     * const promise = FPromise.resolve(42)
+     * // promise resolves to 42
+     */
+    resolve: <T, E = never>(value: T | PromiseLike<T>) => FPromise<T, E>;
+    /**
+     * Creates an FPromise that rejects with the provided reason.
+     *
+     * @template T - The type of the value (which will never be produced)
+     * @template E - The type of the error
+     * @param reason - The reason for rejection
+     * @returns An FPromise that rejects with the reason
+     *
+     * @example
+     * const promise = FPromise.reject<number, Error>(new Error("Something went wrong"))
+     * // promise rejects with Error("Something went wrong")
+     */
+    reject: <T, E = unknown>(reason: E) => FPromise<T, E>;
+    /**
+     * Creates an FPromise from a regular Promise.
+     *
+     * @template T - The type of the value
+     * @template E - The type of the error
+     * @param promise - The Promise to convert
+     * @returns An FPromise that resolves or rejects with the same value or error
+     *
+     * @example
+     * const promise = FPromise.from(fetch("https://api.example.com/data"))
+     * // promise is an FPromise that resolves or rejects based on the fetch result
+     */
+    from: <T, E = unknown>(promise: Promise<T>) => FPromise<T, E>;
+    /**
+     * Creates an FPromise from an Either.
+     * If the Either is a Right, the FPromise resolves with the Right value.
+     * If the Either is a Left, the FPromise rejects with the Left value.
+     *
+     * @template L - The type of the Left value (error)
+     * @template R - The type of the Right value (success)
+     * @param either - The Either to convert
+     * @returns An FPromise that resolves or rejects based on the Either
+     *
+     * @example
+     * const either = Right<Error, number>(42)
+     * const promise = FPromise.fromEither(either)
+     * // promise resolves to 42
+     */
+    fromEither: <L, R>(either: Either<L, R>) => FPromise<R, L>;
+    /**
+     * Runs multiple FPromises in parallel and returns an array of results.
+     * Similar to Promise.all, this will reject if any of the promises reject.
+     *
+     * @template T - The type of the values
+     * @template E - The type of the error
+     * @param promises - An array of FPromises, Promises, or values
+     * @returns An FPromise that resolves to an array of results
+     *
+     * @example
+     * const promises = [FPromise.resolve(1), FPromise.resolve(2), 3]
+     * const result = await FPromise.all(promises).toPromise()
+     * // result is [1, 2, 3]
+     */
+    all: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T> | T>) => FPromise<T[], E>;
+    /**
+     * Like Promise.allSettled, returns results of all promises whether they succeed or fail.
+     * This will always resolve, never reject.
+     *
+     * @template T - The type of the values
+     * @template E - The type of the errors
+     * @param promises - An array of FPromises or Promises
+     * @returns An FPromise that resolves to an array of Either results
+     *
+     * @example
+     * const promises = [FPromise.resolve(1), FPromise.reject<number, Error>(new Error("Failed"))]
+     * const result = await FPromise.allSettled(promises).toPromise()
+     * // result is [Right(1), Left(Error("Failed"))]
+     */
+    allSettled: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T>>) => FPromise<Array<Either<E, T>>, never>;
+    /**
+     * Like Promise.race, returns the first promise to settle (either resolve or reject).
+     *
+     * @template T - The type of the values
+     * @template E - The type of the errors
+     * @param promises - An array of FPromises or Promises
+     * @returns An FPromise that resolves or rejects with the result of the first promise to settle
+     *
+     * @example
+     * const slow = FPromise.resolve(1).tap(() => new Promise(r => setTimeout(r, 100)))
+     * const fast = FPromise.resolve(2).tap(() => new Promise(r => setTimeout(r, 50)))
+     * const result = await FPromise.race([slow, fast]).toPromise()
+     * // result is 2
+     */
+    race: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T>>) => FPromise<T, E>;
+    /**
+     * Like Promise.any, returns the first promise to fulfill.
+     * This will only reject if all promises reject.
+     *
+     * @template T - The type of the values
+     * @template E - The type of the errors
+     * @param promises - An array of FPromises or Promises
+     * @returns An FPromise that resolves with the first promise to fulfill or rejects if all promises reject
+     *
+     * @example
+     * const promises = [
+     *   FPromise.reject<number, Error>(new Error("First failed")),
+     *   FPromise.resolve(2),
+     *   FPromise.reject<number, Error>(new Error("Third failed"))
+     * ]
+     * const result = await FPromise.any(promises).toPromise()
+     * // result is 2
+     */
+    any: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T>>) => FPromise<T, E>;
+    /**
+     * Retries an operation with exponential backoff.
+     * This is useful for operations that may fail temporarily, such as network requests.
+     *
+     * @template T - The type of the value
+     * @template E - The type of the error
+     * @param operation - A function that returns an FPromise
+     * @param options - Configuration options for the retry
+     * @param options.maxRetries - Maximum number of retry attempts
+     * @param options.baseDelay - Base delay in milliseconds (default: 100)
+     * @param options.shouldRetry - Function that determines whether to retry based on the error (default: always retry)
+     * @returns An FPromise that resolves when the operation succeeds or rejects after all retries fail
+     *
+     * @example
+     * const operation = () => {
+     *   if (Math.random() > 0.8) {
+     *     return FPromise.resolve("Success!")
+     *   }
+     *   return FPromise.reject<string, Error>(new Error("Temporary failure"))
+     * }
+     *
+     * const result = await FPromise.retryWithBackoff(operation, {
+     *   maxRetries: 3,
+     *   baseDelay: 100,
+     *   shouldRetry: (error) => error.message === "Temporary failure"
+     * }).toPromise()
+     */
+    retryWithBackoff: <T, E = unknown>(operation: () => FPromise<T, E>, options: {
+        maxRetries: number;
+        baseDelay?: number;
+        shouldRetry?: (error: E, attempt: number) => boolean;
+    }) => FPromise<T, E>;
+};
+/**
+ * FPromise is a functional wrapper around JavaScript's Promise with enhanced error handling.
+ * It implements the Functor and AsyncFunctor interfaces, providing map and flatMap operations
+ * for functional composition.
+ *
+ * FPromise adds several features not available in standard Promises:
+ * - Generic error typing for better type safety
+ * - Error recovery mechanisms (recover, recoverWith, recoverWithF)
+ * - Error filtering and categorization
+ * - Side effect methods (tap, tapError)
+ * - Error context preservation
+ * - Conversion to/from Either for more functional error handling
+ *
+ * @template T - The type of the value that the FPromise resolves to
+ * @template E - The type of the error that the FPromise may reject with (defaults to unknown)
+ */
+/**
+ * FPromise type that defines the function signature and methods
+ */
+type FPromise<T extends Type, E extends Type = unknown> = PromiseLike<T> & {
+    readonly _tag: "FPromise";
+    tap: (f: (value: T) => void) => FPromise<T, E>;
+    mapError: <E2>(f: (error: E, context: ErrorContext) => E2) => FPromise<T, E2>;
+    tapError: (f: (error: E) => void) => FPromise<T, E>;
+    recover: (fallback: T) => FPromise<T, never>;
+    recoverWith: (f: (error: E) => T) => FPromise<T, never>;
+    recoverWithF: <E2>(f: (error: E) => FPromise<T, E2>) => FPromise<T, E2>;
+    filterError: <E2 extends E>(predicate: (error: E) => boolean, handler: (error: E) => FPromise<T, E2>) => FPromise<T, E>;
+    logError: (logger: (error: E, context: ErrorContext) => void) => FPromise<T, E>;
+    toPromise: () => Promise<T>;
+    toEither: () => Promise<T>;
+    fold: <R extends Type>(onError: (error: E) => R, onSuccess: (value: T) => R) => FPromise<R, never>;
+    map: <U extends Type>(f: (value: T) => U) => FPromise<U, E>;
+    flatMap: <U extends Type>(f: (value: T) => FPromise<U, E> | PromiseLike<U>) => FPromise<U, E>;
+    flatMapAsync: <U extends Type>(f: (value: T) => PromiseLike<U>) => Promise<U>;
+};
+/**
+ * Creates an FPromise from an executor function.
+ *
+ * @template T - The type of the value that the FPromise resolves to
+ * @template E - The type of the error that the FPromise may reject with
+ * @param executor - A function that receives resolve and reject functions
+ * @returns An FPromise instance
+ */
+declare const FPromise: (<T extends Type, E = unknown>(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: E) => void) => void) => FPromise<T, E>) & {
+    /**
+     * Creates an FPromise that resolves to the provided value.
+     *
+     * @template T - The type of the value
+     * @template E - The type of the error (defaults to never since this FPromise won't reject)
+     * @param value - The value to resolve with
+     * @returns An FPromise that resolves to the value
+     *
+     * @example
+     * const promise = FPromise.resolve(42)
+     * // promise resolves to 42
+     */
+    resolve: <T, E = never>(value: T | PromiseLike<T>) => FPromise<T, E>;
+    /**
+     * Creates an FPromise that rejects with the provided reason.
+     *
+     * @template T - The type of the value (which will never be produced)
+     * @template E - The type of the error
+     * @param reason - The reason for rejection
+     * @returns An FPromise that rejects with the reason
+     *
+     * @example
+     * const promise = FPromise.reject<number, Error>(new Error("Something went wrong"))
+     * // promise rejects with Error("Something went wrong")
+     */
+    reject: <T, E = unknown>(reason: E) => FPromise<T, E>;
+    /**
+     * Creates an FPromise from a regular Promise.
+     *
+     * @template T - The type of the value
+     * @template E - The type of the error
+     * @param promise - The Promise to convert
+     * @returns An FPromise that resolves or rejects with the same value or error
+     *
+     * @example
+     * const promise = FPromise.from(fetch("https://api.example.com/data"))
+     * // promise is an FPromise that resolves or rejects based on the fetch result
+     */
+    from: <T, E = unknown>(promise: Promise<T>) => FPromise<T, E>;
+    /**
+     * Creates an FPromise from an Either.
+     * If the Either is a Right, the FPromise resolves with the Right value.
+     * If the Either is a Left, the FPromise rejects with the Left value.
+     *
+     * @template L - The type of the Left value (error)
+     * @template R - The type of the Right value (success)
+     * @param either - The Either to convert
+     * @returns An FPromise that resolves or rejects based on the Either
+     *
+     * @example
+     * const either = Right<Error, number>(42)
+     * const promise = FPromise.fromEither(either)
+     * // promise resolves to 42
+     */
+    fromEither: <L, R>(either: Either<L, R>) => FPromise<R, L>;
+    /**
+     * Runs multiple FPromises in parallel and returns an array of results.
+     * Similar to Promise.all, this will reject if any of the promises reject.
+     *
+     * @template T - The type of the values
+     * @template E - The type of the error
+     * @param promises - An array of FPromises, Promises, or values
+     * @returns An FPromise that resolves to an array of results
+     *
+     * @example
+     * const promises = [FPromise.resolve(1), FPromise.resolve(2), 3]
+     * const result = await FPromise.all(promises).toPromise()
+     * // result is [1, 2, 3]
+     */
+    all: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T> | T>) => FPromise<T[], E>;
+    /**
+     * Like Promise.allSettled, returns results of all promises whether they succeed or fail.
+     * This will always resolve, never reject.
+     *
+     * @template T - The type of the values
+     * @template E - The type of the errors
+     * @param promises - An array of FPromises or Promises
+     * @returns An FPromise that resolves to an array of Either results
+     *
+     * @example
+     * const promises = [FPromise.resolve(1), FPromise.reject<number, Error>(new Error("Failed"))]
+     * const result = await FPromise.allSettled(promises).toPromise()
+     * // result is [Right(1), Left(Error("Failed"))]
+     */
+    allSettled: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T>>) => FPromise<Array<Either<E, T>>, never>;
+    /**
+     * Like Promise.race, returns the first promise to settle (either resolve or reject).
+     *
+     * @template T - The type of the values
+     * @template E - The type of the errors
+     * @param promises - An array of FPromises or Promises
+     * @returns An FPromise that resolves or rejects with the result of the first promise to settle
+     *
+     * @example
+     * const slow = FPromise.resolve(1).tap(() => new Promise(r => setTimeout(r, 100)))
+     * const fast = FPromise.resolve(2).tap(() => new Promise(r => setTimeout(r, 50)))
+     * const result = await FPromise.race([slow, fast]).toPromise()
+     * // result is 2
+     */
+    race: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T>>) => FPromise<T, E>;
+    /**
+     * Like Promise.any, returns the first promise to fulfill.
+     * This will only reject if all promises reject.
+     *
+     * @template T - The type of the values
+     * @template E - The type of the errors
+     * @param promises - An array of FPromises or Promises
+     * @returns An FPromise that resolves with the first promise to fulfill or rejects if all promises reject
+     *
+     * @example
+     * const promises = [
+     *   FPromise.reject<number, Error>(new Error("First failed")),
+     *   FPromise.resolve(2),
+     *   FPromise.reject<number, Error>(new Error("Third failed"))
+     * ]
+     * const result = await FPromise.any(promises).toPromise()
+     * // result is 2
+     */
+    any: <T, E = unknown>(promises: Array<FPromise<T, E> | PromiseLike<T>>) => FPromise<T, E>;
+    /**
+     * Retries an operation with exponential backoff.
+     * This is useful for operations that may fail temporarily, such as network requests.
+     *
+     * @template T - The type of the value
+     * @template E - The type of the error
+     * @param operation - A function that returns an FPromise
+     * @param options - Configuration options for the retry
+     * @param options.maxRetries - Maximum number of retry attempts
+     * @param options.baseDelay - Base delay in milliseconds (default: 100)
+     * @param options.shouldRetry - Function that determines whether to retry based on the error (default: always retry)
+     * @returns An FPromise that resolves when the operation succeeds or rejects after all retries fail
+     *
+     * @example
+     * const operation = () => {
+     *   if (Math.random() > 0.8) {
+     *     return FPromise.resolve("Success!")
+     *   }
+     *   return FPromise.reject<string, Error>(new Error("Temporary failure"))
+     * }
+     *
+     * const result = await FPromise.retryWithBackoff(operation, {
+     *   maxRetries: 3,
+     *   baseDelay: 100,
+     *   shouldRetry: (error) => error.message === "Temporary failure"
+     * }).toPromise()
+     */
+    retryWithBackoff: <T, E = unknown>(operation: () => FPromise<T, E>, options: {
+        maxRetries: number;
+        baseDelay?: number;
+        shouldRetry?: (error: E, attempt: number) => boolean;
+    }) => FPromise<T, E>;
+};
+
+export { type ErrorContext, FPromise, FPromiseCompanion };

package/dist/fpromise/index.mjs

@@ -1,2 +1,2 @@
-export{t as FPromise,s as FPromiseCompanion}from'../chunk-NTL4HYMA.mjs';import'../chunk-PXFJPCM7.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
+export{u as FPromise,t as FPromiseCompanion}from'../chunk-5DWCHDSA.mjs';import'../chunk-7PQA3W7W.mjs';import'../chunk-TQJDL6YW.mjs';//# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map