@jhel/iterup/dist/core.d.ts

A TypeScript iterator utility library that provides lazy evaluation for efficient data processing

import { Extensions, NumericExtensions } from "./extensions";
import { RangeArgument } from "./methods";
import { OverrideFunctions, type Overrides } from "./overrides";
/**
 * Sentinel value representing the absence of a value in Option types.
 * Used to indicate that a value should be filtered out or is not present.
 *
 * @example
 * ```ts
 * const result = someValue > 10 ? someValue * 2 : None;
 * ```
 */
export declare const None: unique symbol;
/**
 * Type representing the None sentinel value.
 */
export type None = typeof None;
/**
 * Unique identifier symbol for Iterup instances.
 * Used internally to distinguish Iterup objects from regular iterators.
 */
export declare const IterupID: unique symbol;
/**
 * Type representing the Iterup identifier.
 */
export type IterupID = typeof IterupID;
/**
 * Represents an optional value that can either be a value of type T or None.
 * Used in methods like filterMap and findMap to indicate presence or absence of a value.
 *
 * @template T - The type of the value when present
 *
 * @example
 * ```ts
 * function processNumber(n: number): Option<string> {
 *   if (n > 0) return `Positive: ${n}`;
 *   return None;
 * }
 * ```
 */
export type Option<T> = None | T;
/**
 * Internal type that excludes certain functions from the base iterator interface.
 * These functions are either overridden or have special handling in Iterup.
 */
type Excludes<Value> = OverrideFunctions<Value> | "toArray";
/**
 * Base async iterator type for handling asynchronous iteration.
 * @template Value - The type of values yielded by the iterator
 */
export type BaseAsyncIterator<Value> = AsyncIteratorObject<Value, unknown, unknown>;
/**
 * Base synchronous iterator type for handling regular iteration.
 * @template Value - The type of values yielded by the iterator
 */
export type BaseSyncIterator<Value> = IteratorObject<Value, unknown, unknown>;
/**
 * Union type representing any kind of iterator that can be processed.
 * Includes iterables, sync iterators, and async iterators.
 * @template Value - The type of values in the iterator
 */
export type BaseIterator<Value> = Iterable<Value> | BaseSyncIterator<Value> | BaseAsyncIterator<Value>;
type IterupBase<Value> = Omit<BaseAsyncIterator<Value>, Excludes<Value>> & Overrides<Value> & Extensions<Value> & {
    [IterupID]: {};
};
type IterupNumeric<Value extends number> = IterupBase<Value> & NumericExtensions<Value>;
/**
 * The main Iterup type that combines base async iterator functionality
 * with extension methods and overrides. This is the enhanced iterator
 * interface that provides functional programming capabilities.
 *
 * @template Value - The type of values yielded by the iterator
 */
export type Iterup<Value> = Value extends number ? IterupNumeric<Value> : IterupBase<Value>;
/**
 * Creates an Iterup instance from an async iterator by wrapping it with
 * extension methods and overrides using a Proxy.
 *
 * @template Value - The type of values yielded by the iterator
 * @param iterator - The async iterator to wrap
 * @returns An enhanced Iterup instance with additional methods
 *
 * @internal This function is used internally by the main iterup function
 */
export declare function fromAsyncIterator<Value>(iterator: BaseAsyncIterator<Value>): Iterup<Value>;
/**
 * Main entry point for creating an Iterup instance from any iterator type or range.
 * This function is overloaded to handle both collections and range arguments:
 * - When passed a RangeArgument, creates a numeric range iterator
 * - When passed any other iterator/iterable, wraps it with extension methods
 * Automatically detects the input type and applies appropriate wrapping.
 *
 * @overload
 * @param range - Range configuration object to create a numeric sequence
 * @returns An Iterup instance yielding numbers in the specified range
 *
 * @overload
 * @param collection - Any iterator, iterable, or async iterator to enhance
 * @returns An Iterup instance with functional programming methods
 *
 * @example
 * ```ts
 * // From array
 * const fromArray = iterup([1, 2, 3, 4]);
 *
 * // From range argument
 * const fromRange = iterup({ from: 0, to: 5 });
 * const rangeResult = await fromRange.collect();
 * // result: [0, 1, 2, 3, 4, 5]
 *
 * // Chain operations
 * const result = await iterup({ from: 1, to: 6 })
 *   .map(x => x * 2)
 *   .filter(x => x > 5)
 *   .collect();
 * // result: [6, 8, 10, 12]
 * ```
 */
export declare function iterup(range: RangeArgument): Iterup<number>;
export declare function iterup<Value>(collection: BaseIterator<Value>): Iterup<Value>;
export {};