/**
 * ===============================================================================
 * RESULT BUILDERS AND UTILITIES
 * ===============================================================================
 *
 * Fluent builders for creating Result types, type guards, and utility functions
 * for working with Result values.
 *
 * ===============================================================================
 */
import type { Result, Success, Failure, ResultMetadata, ResultError, LegacyResult } from './types.js';
/**
 * Creates a Success result with the given data.
 *
 * @param data - The successful result data
 * @param metadata - Optional metadata about the operation
 * @returns A Success result
 *
 * @example
 * ```typescript
 * const result = success({ id: 1, name: 'Alice' });
 * // result.success === true
 * // result.data === { id: 1, name: 'Alice' }
 * ```
 */
export declare function success<T>(data: T, metadata?: ResultMetadata): Success<T>;
/**
 * Creates a Failure result with the given error information.
 *
 * @param code - Machine-readable error code
 * @param message - Human-readable error message
 * @param options - Additional error options
 * @returns A Failure result
 *
 * @example
 * ```typescript
 * const result = failure('NOT_FOUND', 'User not found', { details: { userId: 123 } });
 * // result.success === false
 * // result.error.code === 'NOT_FOUND'
 * ```
 */
export declare function failure(code: string, message: string, options?: {
    details?: Record<string, unknown>;
    retryable?: boolean;
    retryAfterMs?: number;
    cause?: ResultError;
    metadata?: ResultMetadata;
}): Failure;
/**
 * Interface for errors that have a code property.
 * Used by fromError to extract structured error information.
 */
interface CodedError extends Error {
    code?: string;
    details?: Record<string, unknown>;
    retryable?: boolean;
}
/**
 * Creates a Failure result from an Error object.
 * Extracts code and details if available (e.g., from PromptSpeakError).
 *
 * @param error - The error to convert
 * @param defaultCode - Default error code if none is present on the error
 * @returns A Failure result
 *
 * @example
 * ```typescript
 * try {
 *   await riskyOperation();
 * } catch (err) {
 *   return fromError(err);
 * }
 * ```
 */
export declare function fromError(error: Error | CodedError | unknown, defaultCode?: string): Failure;
/**
 * Wraps a Promise to return a Result instead of throwing.
 *
 * @param promise - The promise to wrap
 * @param errorCode - Error code to use if the promise rejects
 * @returns A Promise that resolves to a Result
 *
 * @example
 * ```typescript
 * const result = await fromPromise(fetchUser(id), 'FETCH_USER_FAILED');
 * if (isSuccess(result)) {
 *   console.log(result.data);
 * }
 * ```
 */
export declare function fromPromise<T>(promise: Promise<T>, errorCode?: string): Promise<Result<T>>;
/**
 * Wraps a synchronous function to return a Result instead of throwing.
 *
 * @param fn - The function to wrap
 * @param errorCode - Error code to use if the function throws
 * @returns A Result
 *
 * @example
 * ```typescript
 * const result = fromThrowable(() => JSON.parse(jsonString), 'PARSE_FAILED');
 * ```
 */
export declare function fromThrowable<T>(fn: () => T, errorCode?: string): Result<T>;
/**
 * Type guard to check if a Result is a Success.
 *
 * @param result - The result to check
 * @returns True if the result is a Success
 *
 * @example
 * ```typescript
 * if (isSuccess(result)) {
 *   // TypeScript knows result.data exists
 *   console.log(result.data);
 * }
 * ```
 */
export declare function isSuccess<T>(result: Result<T>): result is Success<T>;
/**
 * Type guard to check if a Result is a Failure.
 *
 * @param result - The result to check
 * @returns True if the result is a Failure
 *
 * @example
 * ```typescript
 * if (isFailure(result)) {
 *   // TypeScript knows result.error exists
 *   console.error(result.error.message);
 * }
 * ```
 */
export declare function isFailure<T>(result: Result<T>): result is Failure;
/**
 * Type guard to check if an error is retryable.
 *
 * @param result - The failure result to check
 * @returns True if the operation can be retried
 */
export declare function isRetryable(result: Failure): boolean;
/**
 * Error thrown when unwrapping a Failure result.
 */
export declare class UnwrapError extends Error {
    readonly error: ResultError;
    constructor(error: ResultError);
}
/**
 * Extracts the data from a Success result.
 * Throws UnwrapError if the result is a Failure.
 *
 * @param result - The result to unwrap
 * @returns The success data
 * @throws UnwrapError if the result is a Failure
 *
 * @example
 * ```typescript
 * const user = unwrap(result);  // Throws if result is Failure
 * ```
 */
export declare function unwrap<T>(result: Result<T>): T;
/**
 * Extracts the data from a Success result, or returns a default value.
 *
 * @param result - The result to unwrap
 * @param defaultValue - Value to return if result is Failure
 * @returns The success data or the default value
 *
 * @example
 * ```typescript
 * const user = unwrapOr(result, defaultUser);
 * ```
 */
export declare function unwrapOr<T>(result: Result<T>, defaultValue: T): T;
/**
 * Extracts the data from a Success result, or computes a default lazily.
 *
 * @param result - The result to unwrap
 * @param defaultFn - Function that returns the default value
 * @returns The success data or the computed default value
 *
 * @example
 * ```typescript
 * const user = unwrapOrElse(result, () => createDefaultUser());
 * ```
 */
export declare function unwrapOrElse<T>(result: Result<T>, defaultFn: () => T): T;
/**
 * Extracts the error from a Failure result.
 * Throws if the result is a Success.
 *
 * @param result - The result to unwrap
 * @returns The error
 * @throws Error if the result is a Success
 */
export declare function unwrapError<T>(result: Result<T>): ResultError;
/**
 * Maps a Success value to a new value using the provided function.
 * If the result is a Failure, returns the Failure unchanged.
 *
 * @param result - The result to map
 * @param fn - Function to transform the success data
 * @returns A new Result with the transformed data
 *
 * @example
 * ```typescript
 * const nameResult = map(userResult, user => user.name);
 * ```
 */
export declare function map<T, U>(result: Result<T>, fn: (data: T) => U): Result<U>;
/**
 * Maps a Failure error to a new error using the provided function.
 * If the result is a Success, returns the Success unchanged.
 *
 * @param result - The result to map
 * @param fn - Function to transform the error
 * @returns A new Result with the transformed error
 */
export declare function mapError<T>(result: Result<T>, fn: (error: ResultError) => ResultError): Result<T>;
/**
 * Chains a Result with a function that returns another Result.
 * Also known as flatMap or bind.
 *
 * @param result - The result to chain
 * @param fn - Function that takes the success data and returns a new Result
 * @returns The chained Result
 *
 * @example
 * ```typescript
 * const result = flatMap(userResult, user => fetchPosts(user.id));
 * ```
 */
export declare function flatMap<T, U>(result: Result<T>, fn: (data: T) => Result<U>): Result<U>;
/**
 * Async version of flatMap for chaining async operations.
 *
 * @param result - The result to chain
 * @param fn - Async function that takes the success data and returns a new Result
 * @returns A Promise that resolves to the chained Result
 */
export declare function flatMapAsync<T, U>(result: Result<T>, fn: (data: T) => Promise<Result<U>>): Promise<Result<U>>;
/**
 * Applies one of two functions depending on success/failure.
 *
 * @param result - The result to match
 * @param onSuccess - Function to call with success data
 * @param onFailure - Function to call with error
 * @returns The return value of the matched function
 *
 * @example
 * ```typescript
 * const message = match(
 *   result,
 *   user => `Hello, ${user.name}!`,
 *   error => `Error: ${error.message}`
 * );
 * ```
 */
export declare function match<T, U>(result: Result<T>, onSuccess: (data: T) => U, onFailure: (error: ResultError) => U): U;
/**
 * Combines multiple Results into a single Result containing an array.
 * If any Result is a Failure, returns the first Failure.
 *
 * @param results - Array of Results to combine
 * @returns A Result containing an array of all success values
 *
 * @example
 * ```typescript
 * const combined = all([result1, result2, result3]);
 * if (isSuccess(combined)) {
 *   const [a, b, c] = combined.data;
 * }
 * ```
 */
export declare function all<T>(results: Array<Result<T>>): Result<T[]>;
/**
 * Combines multiple Results, collecting all successes and failures.
 * Unlike `all`, this processes all results even if some fail.
 *
 * @param results - Array of Results to partition
 * @returns Object containing arrays of successes and failures
 */
export declare function partition<T>(results: Array<Result<T>>): {
    successes: T[];
    failures: Failure[];
};
/**
 * Converts a legacy result format to the new Result type.
 *
 * @param legacy - Legacy result object
 * @param dataKey - Key to extract data from (default: 'data')
 * @returns A proper Result type
 *
 * @example
 * ```typescript
 * const legacyResult = { success: true, user: { id: 1 } };
 * const result = fromLegacy(legacyResult, 'user');
 * ```
 */
export declare function fromLegacy<T>(legacy: LegacyResult<T>, dataKey?: string): Result<T>;
/**
 * Converts a Result to the legacy format for backward compatibility.
 *
 * @param result - The Result to convert
 * @returns A legacy result object
 */
export declare function toLegacy<T>(result: Result<T>): LegacyResult<T>;
export {};
//# sourceMappingURL=builders.d.ts.map