import { type AsyncGetterOrValue, type GetterOrValue } from '../getter';
import { type PromiseOrValue } from '../promise/promise.type';
import { type MapFunction } from './map';
import { type Maybe } from './maybe.type';
/**
 * A MapFunction whose primary intent is to consume (use) the input value, optionally producing an output.
 * Defaults to void when no output is needed, making it suitable for side-effect-style consumers.
 */
export type UseValue<I, O = void> = MapFunction<I, O>;
/**
 * Applies the `use` function to the input if it is defined, otherwise returns the `defaultValue`.
 * Provides a safe pattern for consuming nullable values with a fallback.
 *
 * @param input - the possibly null/undefined value to consume
 * @param use - function to apply when input is defined
 * @param defaultValue - fallback value or getter used when input is null/undefined
 * @returns the result of `use`, or the default value if input was null/undefined
 *
 * @example
 * ```ts
 * const result = useValue(5, (x) => x * 2);
 * // result === 10
 *
 * const fallback = useValue(undefined, (x: number) => x * 2, 0);
 * // fallback === 0
 * ```
 */
export declare function useValue<I, O = void>(input: Maybe<I>, use: UseValue<I, O>, defaultValue?: Maybe<GetterOrValue<O>>): Maybe<O>;
/**
 * A MappedUseFunction where no mapping step is applied; the input type is used directly.
 */
export type UseFunction<I> = MappedUseFunction<I, I>;
/**
 * A function that first maps an input of type `A` to type `I`, then applies a {@link UseValue} consumer
 * to the mapped result. Falls back to a default value when the input is null/undefined.
 */
export type MappedUseFunction<A, I> = <O = void>(input: Maybe<A>, use: UseValue<I, O>, defaultValue?: Maybe<GetterOrValue<O>>) => Maybe<O>;
/**
 * Creates a {@link MappedUseFunction} that transforms the input through the given `map` before applying the consumer.
 * If the mapped result is null/undefined, the default value is returned instead.
 *
 * @param map - transforms the outer input into the type expected by the consumer
 * @returns a MappedUseFunction that maps then consumes
 *
 * @example
 * ```ts
 * const mapFn = (n: number) => String(n);
 * const mappedUseFn = mappedUseFunction(mapFn);
 *
 * const result = mappedUseFn(1, () => 'hello');
 * // result === 'hello'
 *
 * const fallback = mappedUseFn(undefined, () => 'wrong', 'default');
 * // fallback === 'default'
 * ```
 */
export declare function mappedUseFunction<A, I>(map: MapFunction<A, Maybe<I>>): MappedUseFunction<A, I>;
/**
 * Wraps an existing {@link MappedUseFunction} with an additional mapping step, allowing further transformation
 * of the intermediate value before it reaches the consumer.
 *
 * @param mappedUseFn - the existing mapped use function to wrap
 * @param map - additional transformation applied to the intermediate value
 * @returns a new MappedUseFunction with the extra mapping layer
 */
export declare function wrapUseFunction<A, B, I>(mappedUseFn: MappedUseFunction<A, B>, map: MapFunction<B, Maybe<I>>): MappedUseFunction<A, I>;
/**
 * A pre-configured consumer function that accepts an input and returns a value, encapsulating both the
 * consumer logic and default value in a single callable.
 */
export type UseContextFunction<I> = <O>(input: Maybe<I>) => Maybe<O>;
/**
 * Creates a {@link UseContextFunction} by binding a consumer and optional default value, so callers
 * only need to supply the input.
 *
 * @param use - the consumer function to bind
 * @param defaultValue - fallback when input is null/undefined
 * @returns a single-argument function that applies the bound consumer
 */
export declare function useContextFunction<I, O>(use: UseValue<I, O>, defaultValue?: GetterOrValue<O>): UseContextFunction<I>;
/**
 * Async variant of {@link UseValue} that may return a Promise, allowing asynchronous consumption of values.
 */
export type UseAsync<I, O = void> = MapFunction<I, PromiseOrValue<O>>;
/**
 * Async variant of {@link useValue}. Awaits the consumer result and supports async default value getters.
 *
 * @param input - the possibly null/undefined value to consume
 * @param use - async-capable consumer function
 * @param defaultValue - fallback value or getter when input is null/undefined
 * @returns a Promise resolving to the consumer result or the default value
 *
 * @example
 * ```ts
 * const result = await useAsync(1, (x) => Promise.resolve(x * 2));
 * // result === 2
 * ```
 */
export declare function useAsync<I, O = void>(input: Maybe<I>, use: UseValue<I, O>, defaultValue?: Maybe<GetterOrValue<O>>): Promise<Maybe<O>>;
/**
 * A {@link MappedUseAsyncFunction} where no mapping step is applied; the input type is used directly.
 */
export type UseAsyncFunction<I> = MappedUseAsyncFunction<I, I>;
/**
 * Async variant of {@link MappedUseFunction} that maps, then asynchronously consumes the result.
 */
export type MappedUseAsyncFunction<A, I> = <O = void>(input: Maybe<A>, use: UseAsync<I, O>, defaultValue?: Maybe<AsyncGetterOrValue<O>>) => Promise<Maybe<O>>;
/**
 * Creates a {@link MappedUseAsyncFunction} that transforms the input through the given `map` (which may return a Promise)
 * before applying the async consumer.
 *
 * @param map - transforms the outer input, optionally asynchronously, into the type expected by the consumer
 * @returns a MappedUseAsyncFunction that maps then asynchronously consumes
 *
 * @example
 * ```ts
 * const mapFn = (n: number) => String(n);
 * const mappedUseAsyncFn = mappedUseAsyncFunction(mapFn);
 *
 * const result = await mappedUseAsyncFn(1, () => Promise.resolve('hello'));
 * // result === 'hello'
 * ```
 */
export declare function mappedUseAsyncFunction<A, I>(map: MapFunction<A, Maybe<PromiseOrValue<Maybe<I>>>>): MappedUseAsyncFunction<A, I>;
/**
 * Wraps an existing {@link MappedUseAsyncFunction} with an additional async-capable mapping step,
 * allowing further transformation of the intermediate value before it reaches the consumer.
 *
 * @param mappedUsePromiseFn - the existing async mapped use function to wrap
 * @param map - additional transformation (sync or async) applied to the intermediate value
 * @returns a new MappedUseAsyncFunction with the extra mapping layer
 */
export declare function wrapUseAsyncFunction<A, B, I>(mappedUsePromiseFn: MappedUseAsyncFunction<A, B>, map: MapFunction<B, Maybe<PromiseOrValue<Maybe<I>>>>): MappedUseAsyncFunction<A, I>;