import type { SafeParseReturnType } from "zod";
import { ServiceError, type ServiceErrorParams } from "../errors/serviceError";
import { type Either, type Left, type Right } from "./either";
export interface Success<A> {
    readonly isSuccess: true;
    readonly value: A;
}
export interface Failure<E> {
    readonly isSuccess: false;
    readonly error: E;
}
export type SuccessResult<A> = Right<A> & Success<A>;
export type FailureResult<E extends ServiceError = ServiceError> = Left<E> & Failure<E>;
/**
 * Represents the result of a service operation that may fail.
 *
 * The type is also an {@link Either}, allowing functions built for {@link Either}.
 *
 * @template A The type of the successful result value
 * @template E The type of the failed result error
 */
export type ServiceResult<A, E extends ServiceError = ServiceError> = SuccessResult<A> | FailureResult<E>;
/**
 * Creates a successful ServiceResult.
 *
 * Call with no argument for a `ServiceResult<void>`; the value is `undefined`.
 */
export declare function success<E extends ServiceError = ServiceError>(): ServiceResult<void, E>;
export declare function success<A, E extends ServiceError = ServiceError>(value: A): ServiceResult<A, E>;
/**
 * Creates a failed ServiceResult.
 */
export declare function failure<E extends ServiceError>(error: E): FailureResult<E>;
export declare function failure(params: ServiceErrorParams): FailureResult;
/**
 * Type guard for failure results.
 */
export declare function isFailure<A, E extends ServiceError = ServiceError>(result: ServiceResult<A, E>): result is FailureResult<E>;
/**
 * Type guard for success results.
 */
export declare function isSuccess<A, E extends ServiceError = ServiceError>(result: ServiceResult<A, E>): result is SuccessResult<A>;
/**
 * Alias for {@link mapLeft}.
 * Note: returns an {@link Either}, not a ServiceResult.
 */
export declare function mapFailure<G, E extends ServiceError = ServiceError>(f: (left: E) => G): <A>(result: ServiceResult<A, E>) => Either<G, A>;
/**
 * Converts a promise returning function into a ServiceResult by handling potential rejections.
 * If the promise returning function resolves successfully, returns a success ServiceResult.
 * If the promise rejects, calls the onError function to convert the error into a ServiceError.
 *
 * @template A The type of the value the promise resolves to
 * @param f Function returning a Promise to execute. Passing a function allows catching synchronous throws
 * @param onError Maps unknown errors to a ServiceError
 * @returns A promise that resolves to a ServiceResult<A>
 *
 * @example
 * <embedex source="packages/util-ts/examples/tryCatchAsync.ts">
 *
 * ```ts
 * import { ok, strictEqual } from "node:assert/strict";
 *
 * import { isFailure, isSuccess, ServiceError, tryCatchAsync } from "@clipboard-health/util-ts";
 *
 * async function example() {
 *   const successResult = await tryCatchAsync(
 *     async () => {
 *       const response = await fetch("https://jsonplaceholder.typicode.com/posts/1");
 *       return (await response.json()) as { id: number };
 *     },
 *     (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
 *   );
 *
 *   ok(isSuccess(successResult));
 *   strictEqual(successResult.value.id, 1);
 *
 *   const failureResult = await tryCatchAsync(
 *     async () => await Promise.reject(new Error("Network error")),
 *     (error) => new ServiceError(`Failed to fetch: ${String(error)}`),
 *   );
 *
 *   ok(isFailure(failureResult));
 *   strictEqual(failureResult.error.issues[0]?.message, "Failed to fetch: Error: Network error");
 * }
 *
 * // eslint-disable-next-line unicorn/prefer-top-level-await
 * void example();
 * ```
 *
 * </embedex>
 */
export declare function tryCatchAsync<A>(f: () => Promise<A>, onError: (error: unknown) => ServiceError): Promise<ServiceResult<A>>;
/**
 * Wraps a synchronous function that might throw into a ServiceResult.
 * If the function executes successfully, returns a success ServiceResult.
 * If the function throws, calls the onError function to convert the error into a ServiceError.
 *
 * @template A The return type of the function
 * @param f The function to execute safely
 * @param onError Function to convert unknown errors into ServiceError
 * @returns A ServiceResult<A>
 *
 * @example
 * <embedex source="packages/util-ts/examples/tryCatch.ts">
 *
 * ```ts
 * import { ok, strictEqual } from "node:assert/strict";
 *
 * import { isFailure, isSuccess, parseJson, ServiceError, tryCatch } from "@clipboard-health/util-ts";
 *
 * const successResult = tryCatch(
 *   () => parseJson<{ name: string }>('{"name": "John"}'),
 *   (error) => new ServiceError(`Parse error: ${String(error)}`),
 * );
 *
 * ok(isSuccess(successResult));
 * strictEqual(successResult.value.name, "John");
 *
 * const failureResult = tryCatch(
 *   () => parseJson("invalid json"),
 *   (error) => new ServiceError(`Parse error: ${String(error)}`),
 * );
 *
 * ok(isFailure(failureResult));
 * ok(failureResult.error.issues[0]?.message?.includes("Parse error") === true);
 * ```
 *
 * </embedex>
 */
export declare function tryCatch<A>(f: () => A, onError: (error: unknown) => ServiceError): ServiceResult<A>;
/**
 * Converts a Zod SafeParseReturnType into a ServiceResult.
 * If the parse was successful, returns a success ServiceResult with the parsed data.
 * If the parse failed, returns a failure ServiceResult with the validation errors.
 *
 * @template A The type of the successfully parsed value
 * @param value The SafeParseReturnType from a Zod schema parse
 * @returns A ServiceResult<A>
 *
 * @example
 * <embedex source="packages/util-ts/examples/fromSafeParseReturnType.ts">
 *
 * ```ts
 * import { ok, strictEqual } from "node:assert/strict";
 *
 * import { fromSafeParseReturnType, isFailure, isSuccess } from "@clipboard-health/util-ts";
 * import { z } from "zod";
 *
 * const schema = z.object({ name: z.string(), age: z.number() });
 *
 * const validData = { name: "John", age: 30 };
 * const successResult = fromSafeParseReturnType(schema.safeParse(validData));
 *
 * ok(isSuccess(successResult));
 * strictEqual(successResult.value.name, "John");
 *
 * const invalidData = { name: "John", age: "thirty" };
 * const failureResult = fromSafeParseReturnType(schema.safeParse(invalidData));
 *
 * ok(isFailure(failureResult));
 * ok(failureResult.error.issues.length > 0);
 * ```
 *
 * </embedex>
 */
export declare function fromSafeParseReturnType<A>(value: SafeParseReturnType<unknown, A>): ServiceResult<A>;