@johnhenry/iteration 0.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAE/B,OAAO,KAAK,iBAAiB,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,CAAC"}

package/dist/is-iterator.d.ts

@@ -0,0 +1,5 @@
+export declare const isIterator: (obj: unknown) => obj is Iterable<unknown>;
+export declare const isAsyncIterator: (obj: unknown) => obj is AsyncIterable<unknown>;
+export declare const exhaustable: (obj: unknown) => boolean;
+export default exhaustable;
+//# sourceMappingURL=is-iterator.d.ts.map

package/dist/is-iterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-iterator.d.ts","sourceRoot":"","sources":["../src/is-iterator.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,QAAQ,CAAC,OAAO,CACI,CAAC;AAEtE,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,aAAa,CAAC,OAAO,CACI,CAAC;AAEhF,eAAO,MAAM,WAAW,GAAI,KAAK,OAAO,KAAG,OAAkD,CAAC;AAE9F,eAAe,WAAW,CAAC"}

package/dist/is-iterator.js

@@ -0,0 +1,5 @@
+export const isIterator = (obj) => typeof obj?.[Symbol.iterator] === "function";
+export const isAsyncIterator = (obj) => typeof obj?.[Symbol.asyncIterator] === "function";
+export const exhaustable = (obj) => isIterator(obj) || isAsyncIterator(obj);
+export default exhaustable;
+//# sourceMappingURL=is-iterator.js.map

package/dist/is-iterator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-iterator.js","sourceRoot":"","sources":["../src/is-iterator.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAY,EAA4B,EAAE,CACnE,OAAQ,GAAyB,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,UAAU,CAAC;AAEtE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAY,EAAiC,EAAE,CAC7E,OAAQ,GAA8B,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,UAAU,CAAC;AAEhF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAY,EAAW,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;AAE9F,eAAe,WAAW,CAAC"}

package/dist/iterator-tools.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Sentinel returned by a reducer step to stop consumption of the source
+ * iterator (early termination -- see the `take` transducer).
+ */
+export declare const HALT: unique symbol;
+export type Halt = typeof HALT;
+/**
+ * @deprecated Misspelled legacy alias of {@link HALT} (pre-2.1 name).
+ * Kept for backwards compatibility; prefer HALT.
+ */
+export { HALT as HAULT };
+/**
+ * The transducer step protocol (v2.1, "pending-emission buffer").
+ *
+ * The accumulator is a plain array used as a pending-emission buffer: the
+ * innermost step ("emit" -- see transduce.ts) pushes emitted items onto it
+ * and returns it. A step may instead return {@link HALT} to terminate
+ * consumption of the source early. A stateful step (e.g. `group`,
+ * `partitionBy`) may carry a `complete` method, invoked once after the
+ * source is exhausted (or halted) to flush buffered state; `complete`
+ * implementations must cascade to their inner step's own `complete` (see
+ * transducers.ts).
+ */
+export interface ReducerStep<in In> {
+    (buffer: unknown[], item: In, iterator?: Iterable<In> | AsyncIterable<In>): unknown[] | Halt;
+    complete?: (buffer: unknown[]) => unknown[];
+}
+/**
+ * A transducer: transforms a step that consumes `Out` items into a step
+ * that consumes `In` items. Produced by the factories in transducers.ts
+ * (map, filter, take, group, ...), consumed by transduceSync/transduceAsync
+ * (left-to-right composition as written).
+ */
+export type Transducer<In, Out> = (next: ReducerStep<Out>) => ReducerStep<In>;
+/**
+ * Create a promise that fulfills after a given number of milliseconds
+ * The primary purpose of this is to allow pausing of asynchronous functions
+ * @kind function
+ * @name pause
+ * @param milliseconds time in milliseconds before value is resolved
+ * @param value value given
+ * @returns Promise fulfilled with given value
+ * @example <caption>Pause a function for 5000 milliseconds</caption>
+ * ```javascript
+ * import { pause } from '...';
+ * (async ()=>{
+ *  console.log('hello');
+ *  await pause(5000);
+ *  console.log('there.');
+ * })();
+ * ```
+ */
+export declare const pause: <T = undefined>(milliseconds: number, value?: T) => Promise<T>;
+/**
+ * Streaming reduce for iterators -- the engine under transduceSync.
+ *
+ * Protocol (v2.1): the accumulator (`init`) is a plain array used as a
+ * *pending-emission buffer*, not a threaded iterable. The innermost step
+ * ("emit" -- see transduce.ts) pushes emitted items onto the buffer and
+ * returns it; after each step call the buffer is drained (yielded out and
+ * cleared in place). This replaces the v2.0 protocol, in which the
+ * accumulator was an iterable that each step wrapped in a fresh generator
+ * (`conjoin(init, item)`) -- that formed an ever-growing generator chain
+ * retaining ~176 bytes per item processed, i.e. unbounded heap growth on
+ * long streams.
+ *
+ * Preserved semantics:
+ * - Left-to-right composition order as written in transduceSync(...fns).
+ * - If `step` carries a `.complete(init)` method (the transducer completion
+ *   protocol -- see transducers.ts's `group`/`partitionBy`), it is invoked
+ *   once after the source iterator is exhausted (or halted), letting
+ *   stateful transducers flush buffered state (e.g. a trailing,
+ *   under-sized `group`).
+ * - HALT early termination: a step returning HALT stops consumption of
+ *   the source; emissions buffered during the halting step itself are
+ *   discarded (as in v2.0, where the halting step's accumulator chain was
+ *   dropped), then `.complete` still flushes.
+ * @kind function
+ * @name reduceSync
+ * @param iterator source iterable
+ * @param step reducer/transducer step function
+ * @param init pending-emission buffer (defaults to a fresh array)
+ * @param ignore_halt ignore when HALT is passed
+ * @returns generator yielding each emitted item
+ */
+export declare const reduceSync: <In, Out = unknown>(iterator: Iterable<In>, step: ReducerStep<In>, init?: unknown[], ignore_halt?: boolean) => Generator<Out>;
+/**
+ * Streaming reduce for asynchronous iterators -- the engine under
+ * transduceAsync. See reduceSync for the pending-emission-buffer protocol
+ * (v2.1), the `.complete` flush protocol, and HALT semantics -- all
+ * identical here, just async.
+ * @kind function
+ * @name reduceAsync
+ * @param iterator source (async) iterable
+ * @param step reducer/transducer step function
+ * @param init pending-emission buffer (defaults to a fresh array)
+ * @param ignore_halt ignore when HALT is passed
+ * @returns async generator yielding each emitted item
+ */
+export declare const reduceAsync: <In, Out = unknown>(iterator: AsyncIterable<In> | Iterable<In>, step: ReducerStep<In>, init?: unknown[], ignore_halt?: boolean) => AsyncGenerator<Out>;
+/**
+ * Concatinates sequence of synchronous iterables
+ * @kind function
+ * @name concatSync
+ * @param iterators iterators
+ * @returns iterator generating sequence of combined from given iterables; empty iterator if nothing is passed
+ */
+export declare const concatSync: <T>(...iterators: Array<Iterable<T>>) => Generator<T>;
+/**
+ * Appends items to synchronous iterator
+ * @kind function
+ * @name conjoinSync
+ * @param iterator iterator
+ * @param itemList items to be appended
+ * @returns copy of initial iterator with items appended
+ */
+export declare const conjoinSync: <T>(iterator?: Iterable<T>, ...itemList: T[]) => Generator<T>;
+/**
+ * Concatinates sequence of asynchronous iterables
+ * @kind function
+ * @name concatAsync
+ * @param iterators iterators
+ * @returns iterator generating sequence of combined from given iterables; empty iterator if nothing is passed
+ */
+export declare const concatAsync: <T>(...iterators: Array<AsyncIterable<T> | Iterable<T>>) => AsyncGenerator<T>;
+/**
+ * Appends items to asynchronous iterator
+ * @kind function
+ * @name conjoinAsync
+ * @param iterator iterator
+ * @param itemList items to be appended
+ * @returns copy of initial iterator with items appended
+ */
+export declare const conjoinAsync: <T>(iterator?: AsyncIterable<T> | Iterable<T>, ...itemList: T[]) => AsyncGenerator<T>;
+/**
+ * Zips synchronous iterators
+ * @kind function
+ * @name zipSync
+ * @param iteratorList iterators
+ * @returns an iterator who's members are the members of the given iterators zipped sequencially
+ */
+export declare const zipSync: <T>(...iteratorList: Array<Iterable<T>>) => Generator<T[]>;
+/**
+ * Zips asynchronous iterators (dual of zipSync).
+ * Pulls the next value from every input in parallel each round (rather than
+ * sequentially awaiting one at a time), stopping as soon as any input is
+ * exhausted -- matching zipSync's stop-at-shortest semantics.
+ * @kind function
+ * @name zipAsync
+ * @param iteratorList (async or sync) iterators
+ * @returns an async iterator who's members are the members of the given iterators zipped sequencially
+ */
+export declare const zipAsync: <T>(...iteratorList: Array<AsyncIterable<T> | Iterable<T>>) => AsyncGenerator<T[]>;
+/**
+ * "run" iterator as a program
+ * @kind function
+ * @name run
+ * @param program iterator
+ * @param render function to render output from iterator
+ */
+export declare const run: <T>(program: AsyncIterable<T> | Iterable<T>, render?: (output: T) => unknown) => Promise<void>;
+export declare const syncFrom: <T>(...stuff: T[]) => Generator<T>;
+export declare const asyncFrom: <T>(...stuff: T[]) => AsyncGenerator<T>;
+//# sourceMappingURL=iterator-tools.d.ts.map

package/dist/iterator-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterator-tools.d.ts","sourceRoot":"","sources":["../src/iterator-tools.ts"],"names":[],"mappings":"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"}

package/dist/iterator-tools.js

@@ -0,0 +1,231 @@
+import { isAsyncIterator } from "./is-iterator.js";
+/**
+ * Sentinel returned by a reducer step to stop consumption of the source
+ * iterator (early termination -- see the `take` transducer).
+ */
+export const HALT = Symbol("HALT");
+/**
+ * @deprecated Misspelled legacy alias of {@link HALT} (pre-2.1 name).
+ * Kept for backwards compatibility; prefer HALT.
+ */
+export { HALT as HAULT };
+/**
+ * Create a promise that fulfills after a given number of milliseconds
+ * The primary purpose of this is to allow pausing of asynchronous functions
+ * @kind function
+ * @name pause
+ * @param milliseconds time in milliseconds before value is resolved
+ * @param value value given
+ * @returns Promise fulfilled with given value
+ * @example <caption>Pause a function for 5000 milliseconds</caption>
+ * ```javascript
+ * import { pause } from '...';
+ * (async ()=>{
+ *  console.log('hello');
+ *  await pause(5000);
+ *  console.log('there.');
+ * })();
+ * ```
+ */
+export const pause = (milliseconds, value) => new Promise((resolve) => setTimeout(resolve, milliseconds, value));
+/**
+ * Streaming reduce for iterators -- the engine under transduceSync.
+ *
+ * Protocol (v2.1): the accumulator (`init`) is a plain array used as a
+ * *pending-emission buffer*, not a threaded iterable. The innermost step
+ * ("emit" -- see transduce.ts) pushes emitted items onto the buffer and
+ * returns it; after each step call the buffer is drained (yielded out and
+ * cleared in place). This replaces the v2.0 protocol, in which the
+ * accumulator was an iterable that each step wrapped in a fresh generator
+ * (`conjoin(init, item)`) -- that formed an ever-growing generator chain
+ * retaining ~176 bytes per item processed, i.e. unbounded heap growth on
+ * long streams.
+ *
+ * Preserved semantics:
+ * - Left-to-right composition order as written in transduceSync(...fns).
+ * - If `step` carries a `.complete(init)` method (the transducer completion
+ *   protocol -- see transducers.ts's `group`/`partitionBy`), it is invoked
+ *   once after the source iterator is exhausted (or halted), letting
+ *   stateful transducers flush buffered state (e.g. a trailing,
+ *   under-sized `group`).
+ * - HALT early termination: a step returning HALT stops consumption of
+ *   the source; emissions buffered during the halting step itself are
+ *   discarded (as in v2.0, where the halting step's accumulator chain was
+ *   dropped), then `.complete` still flushes.
+ * @kind function
+ * @name reduceSync
+ * @param iterator source iterable
+ * @param step reducer/transducer step function
+ * @param init pending-emission buffer (defaults to a fresh array)
+ * @param ignore_halt ignore when HALT is passed
+ * @returns generator yielding each emitted item
+ */
+export const reduceSync = function* (iterator, step, init = [], ignore_halt = false) {
+    for (const item of iterator) {
+        const next = step(init, item, iterator);
+        if (!ignore_halt && next === HALT) {
+            init.length = 0;
+            break;
+        }
+        init = next;
+        while (init.length > 0) {
+            yield init.shift();
+        }
+    }
+    if (step.complete) {
+        init = step.complete(init);
+        while (init.length > 0) {
+            yield init.shift();
+        }
+    }
+};
+/**
+ * Streaming reduce for asynchronous iterators -- the engine under
+ * transduceAsync. See reduceSync for the pending-emission-buffer protocol
+ * (v2.1), the `.complete` flush protocol, and HALT semantics -- all
+ * identical here, just async.
+ * @kind function
+ * @name reduceAsync
+ * @param iterator source (async) iterable
+ * @param step reducer/transducer step function
+ * @param init pending-emission buffer (defaults to a fresh array)
+ * @param ignore_halt ignore when HALT is passed
+ * @returns async generator yielding each emitted item
+ */
+export const reduceAsync = async function* (iterator, step, init = [], ignore_halt = false) {
+    for await (const item of iterator) {
+        const next = step(init, item, iterator);
+        if (!ignore_halt && next === HALT) {
+            init.length = 0;
+            break;
+        }
+        init = next;
+        while (init.length > 0) {
+            yield init.shift();
+        }
+    }
+    if (step.complete) {
+        init = step.complete(init);
+        while (init.length > 0) {
+            yield init.shift();
+        }
+    }
+};
+/**
+ * Concatinates sequence of synchronous iterables
+ * @kind function
+ * @name concatSync
+ * @param iterators iterators
+ * @returns iterator generating sequence of combined from given iterables; empty iterator if nothing is passed
+ */
+export const concatSync = function* (...iterators) {
+    for (const iterator of iterators) {
+        yield* iterator;
+    }
+};
+/**
+ * Appends items to synchronous iterator
+ * @kind function
+ * @name conjoinSync
+ * @param iterator iterator
+ * @param itemList items to be appended
+ * @returns copy of initial iterator with items appended
+ */
+export const conjoinSync = function* (iterator, ...itemList) {
+    if (iterator) {
+        yield* iterator;
+    }
+    yield* itemList;
+};
+/**
+ * Concatinates sequence of asynchronous iterables
+ * @kind function
+ * @name concatAsync
+ * @param iterators iterators
+ * @returns iterator generating sequence of combined from given iterables; empty iterator if nothing is passed
+ */
+export const concatAsync = async function* (...iterators) {
+    for (const iterator of iterators) {
+        yield* iterator;
+    }
+};
+/**
+ * Appends items to asynchronous iterator
+ * @kind function
+ * @name conjoinAsync
+ * @param iterator iterator
+ * @param itemList items to be appended
+ * @returns copy of initial iterator with items appended
+ */
+export const conjoinAsync = async function* (iterator, ...itemList) {
+    if (iterator) {
+        yield* iterator;
+    }
+    yield* itemList;
+};
+/**
+ * Zips synchronous iterators
+ * @kind function
+ * @name zipSync
+ * @param iteratorList iterators
+ * @returns an iterator who's members are the members of the given iterators zipped sequencially
+ */
+export const zipSync = function* (...iteratorList) {
+    const generators = iteratorList.map((iterator) => iterator[Symbol.iterator]());
+    outer: while (true) {
+        const result = [];
+        for (const generator of generators) {
+            const { value, done } = generator.next();
+            if (done) {
+                break outer;
+            }
+            result.push(value);
+        }
+        yield result;
+    }
+};
+/**
+ * Zips asynchronous iterators (dual of zipSync).
+ * Pulls the next value from every input in parallel each round (rather than
+ * sequentially awaiting one at a time), stopping as soon as any input is
+ * exhausted -- matching zipSync's stop-at-shortest semantics.
+ * @kind function
+ * @name zipAsync
+ * @param iteratorList (async or sync) iterators
+ * @returns an async iterator who's members are the members of the given iterators zipped sequencially
+ */
+export const zipAsync = async function* (...iteratorList) {
+    const generators = iteratorList.map((iterator) => isAsyncIterator(iterator)
+        ? iterator[Symbol.asyncIterator]()
+        : iterator[Symbol.iterator]());
+    while (true) {
+        const results = await Promise.all(generators.map((g) => g.next()));
+        if (results.some(({ done }) => done)) {
+            break;
+        }
+        yield results.map(({ value }) => value);
+    }
+};
+/**
+ * "run" iterator as a program
+ * @kind function
+ * @name run
+ * @param program iterator
+ * @param render function to render output from iterator
+ */
+export const run = async (program, render = console.log) => {
+    for await (const output of program) {
+        await render(output);
+    }
+};
+export const syncFrom = function* (...stuff) {
+    for (const thing of stuff) {
+        yield thing;
+    }
+};
+export const asyncFrom = async function* (...stuff) {
+    for (const thing of stuff) {
+        yield thing;
+    }
+};
+//# sourceMappingURL=iterator-tools.js.map

package/dist/iterator-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterator-tools.js","sourceRoot":"","sources":["../src/iterator-tools.ts"],"names":[],"mappings":"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"}

package/dist/itertools.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Python itertools-parity building blocks.
+ *
+ * Unlike the curried transducer factories in transducers.ts (which are
+ * shaped `(...) => (conjoin) => (init, item) => ...` for composition inside
+ * transduceSync/transduceAsync), the functions here are flat, direct
+ * iterable-in/iterable-out generators -- matching Python's itertools
+ * argument order (predicate/fn first, iterable(s) last) so porting a
+ * Python recipe is close to mechanical.
+ *
+ * Where a sync function's behavior is fully covered by native ES2025
+ * Iterator Helpers (Iterator.prototype.map/filter/...), it's implemented
+ * as a thin wrapper around Iterator.from(iterable) rather than a hand-rolled
+ * generator, to keep the maintenance surface small. Async counterparts are
+ * always hand-rolled async generators, since AsyncIterator helpers are not
+ * yet shipped (TC39 Stage 2).
+ *
+ * See docs/discussion/python-itertools.md for the full comparison to
+ * Python's itertools module and the documented design divergences.
+ */
+/**
+ * Yield items while predicate holds; stop (without consuming further) at
+ * the first item that fails it. Predicate-based complement to the
+ * numeric `take` transducer.
+ * @kind function
+ * @name takeWhileSync
+ */
+export declare function takeWhileSync<T>(predicate: (item: T) => boolean, iterable: Iterable<T>): Generator<T>;
+/**
+ * Asynchronous dual of takeWhileSync.
+ * @kind function
+ * @name takeWhileAsync
+ */
+export declare function takeWhileAsync<T>(predicate: (item: T) => boolean, iterable: AsyncIterable<T> | Iterable<T>): AsyncGenerator<T>;
+/**
+ * Drop items while predicate holds, then yield everything else.
+ * Predicate-based complement to the numeric `drop` transducer.
+ * @kind function
+ * @name dropWhileSync
+ */
+export declare function dropWhileSync<T>(predicate: (item: T) => boolean, iterable: Iterable<T>): Generator<T>;
+/**
+ * Asynchronous dual of dropWhileSync.
+ * @kind function
+ * @name dropWhileAsync
+ */
+export declare function dropWhileAsync<T>(predicate: (item: T) => boolean, iterable: AsyncIterable<T>): AsyncGenerator<T>;
+/**
+ * Select items from `iterable` for which the parallel `selectors` iterable
+ * is truthy. Mirrors Python's itertools.compress(data, selectors).
+ * @kind function
+ * @name compressSync
+ */
+export declare function compressSync<T>(iterable: Iterable<T>, selectors: Iterable<unknown>): Generator<T>;
+/**
+ * Asynchronous dual of compressSync.
+ * @kind function
+ * @name compressAsync
+ */
+export declare function compressAsync<T>(iterable: AsyncIterable<T> | Iterable<T>, selectors: AsyncIterable<unknown> | Iterable<unknown>): AsyncGenerator<T>;
+/**
+ * Yield overlapping windows of `n` consecutive items.
+ * @kind function
+ * @name windowedSync
+ */
+export declare function windowedSync<T>(iterable: Iterable<T>, n: number): Generator<T[]>;
+/**
+ * Asynchronous dual of windowedSync.
+ * @kind function
+ * @name windowedAsync
+ */
+export declare function windowedAsync<T>(iterable: AsyncIterable<T> | Iterable<T>, n: number): AsyncGenerator<T[]>;
+/**
+ * Yield successive overlapping pairs. Mirrors Python 3.10+'s
+ * itertools.pairwise -- a thin call to windowedSync(iterable, 2) so the
+ * ring-buffer logic isn't duplicated.
+ * @kind function
+ * @name pairwiseSync
+ */
+export declare function pairwiseSync<T>(iterable: Iterable<T>): Generator<[T, T]>;
+/**
+ * Asynchronous dual of pairwiseSync.
+ * @kind function
+ * @name pairwiseAsync
+ */
+export declare function pairwiseAsync<T>(iterable: AsyncIterable<T> | Iterable<T>): AsyncGenerator<[T, T]>;
+/**
+ * Group consecutive items sharing a key into `[key, items[]]` pairs.
+ * Mirrors Python's itertools.groupby, but deliberately diverges from it:
+ * Python's sub-iterators are lazy and invalidated by the next outer
+ * `next()` call (a well-known footgun); this eagerly materializes each
+ * run as an array instead, which is safer and matches what JS developers
+ * expect. As in Python, only *consecutive* runs are grouped -- sort the
+ * input first if you want all occurrences of a key merged globally.
+ * @kind function
+ * @name groupBySync
+ */
+export declare function groupBySync<T, K = T>(iterable: Iterable<T>, keyFn?: (item: T) => K): Generator<[K, T[]]>;
+/**
+ * Asynchronous dual of groupBySync.
+ * @kind function
+ * @name groupByAsync
+ */
+export declare function groupByAsync<T, K = T>(iterable: AsyncIterable<T>, keyFn?: (item: T) => K): AsyncGenerator<[K, T[]]>;
+/**
+ * Chain multiple iterables into one sequence. Mirrors Python's
+ * itertools.chain(*iterables); an itertools-parity alias of concatSync.
+ * @kind function
+ * @name chainSync
+ * @see flattenSync
+ */
+export declare const chainSync: <T>(...iterators: Array<Iterable<T>>) => Generator<T>;
+/**
+ * Asynchronous dual of chainSync; alias of concatAsync.
+ * @kind function
+ * @name chainAsync
+ * @see flattenAsync
+ */
+export declare const chainAsync: <T>(...iterators: Array<AsyncIterable<T> | Iterable<T>>) => AsyncGenerator<T>;
+/**
+ * Flatten one level of an iterable-of-iterables. Mirrors Python's
+ * itertools.chain.from_iterable -- the single-arg counterpart to
+ * chainSync's variadic form. Not recursive.
+ * @kind function
+ * @name flattenSync
+ * @see chainSync
+ */
+export declare function flattenSync<T>(iterableOfIterables: Iterable<Iterable<T>>): Generator<T>;
+/**
+ * Asynchronous dual of flattenSync.
+ * @kind function
+ * @name flattenAsync
+ * @see chainAsync
+ */
+export declare function flattenAsync<T>(iterableOfIterables: AsyncIterable<AsyncIterable<T> | Iterable<T>> | Iterable<AsyncIterable<T> | Iterable<T>>): AsyncGenerator<T>;
+/**
+ * Cycle through `iterable` forever, buffering it on the first pass so a
+ * one-shot source (e.g. a generator) can still be replayed. Yields
+ * nothing if the source is empty.
+ * @kind function
+ * @name cycleSync
+ */
+export declare function cycleSync<T>(iterable: Iterable<T>): Generator<T>;
+/**
+ * Asynchronous dual of cycleSync.
+ * @kind function
+ * @name cycleAsync
+ */
+export declare function cycleAsync<T>(iterable: AsyncIterable<T> | Iterable<T>): AsyncGenerator<T>;
+/**
+ * Yield `value` repeatedly, `times` times (default infinite).
+ * @kind function
+ * @name repeatSync
+ */
+export declare function repeatSync<T>(value: T, times?: number): Generator<T>;
+/**
+ * Asynchronous dual of repeatSync.
+ * @kind function
+ * @name repeatAsync
+ */
+export declare function repeatAsync<T>(value: T, times?: number): AsyncGenerator<T>;
+/**
+ * Yield only the first occurrence of each key -- global, unbounded-memory
+ * dedupe. Mirrors the `unique_everseen` recipe from Python's itertools docs.
+ * @kind function
+ * @name uniqueSync
+ */
+export declare function uniqueSync<T, K = T>(iterable: Iterable<T>, keyFn?: (item: T) => K): Generator<T>;
+/**
+ * Asynchronous dual of uniqueSync.
+ * @kind function
+ * @name uniqueAsync
+ */
+export declare function uniqueAsync<T, K = T>(iterable: AsyncIterable<T> | Iterable<T>, keyFn?: (item: T) => K): AsyncGenerator<T>;
+/**
+ * Yield `[index, value]` pairs, mirroring Python's builtin enumerate().
+ * Implemented via native Iterator Helpers: Iterator.prototype.map's
+ * callback receives `(value, index)`, unlike Array.prototype.map's
+ * `(value, index, array)` -- confirmed present in ES2025.
+ * @kind function
+ * @name enumerateSync
+ */
+export declare function enumerateSync<T>(iterable: Iterable<T>, start?: number): Generator<[number, T]>;
+/**
+ * Asynchronous dual of enumerateSync (hand-rolled -- no native
+ * AsyncIterator helpers are shipped yet).
+ * @kind function
+ * @name enumerateAsync
+ */
+export declare function enumerateAsync<T>(iterable: AsyncIterable<T> | Iterable<T>, start?: number): AsyncGenerator<[number, T]>;
+/**
+ * Call `fn` with each item's contents spread as arguments. Mirrors
+ * Python's itertools.starmap.
+ * @kind function
+ * @name starmapSync
+ */
+export declare function starmapSync<Args extends unknown[], R>(fn: (...args: Args) => R, iterableOfArgArrays: Iterable<Args>): Generator<R>;
+/**
+ * Asynchronous dual of starmapSync.
+ * @kind function
+ * @name starmapAsync
+ */
+export declare function starmapAsync<Args extends unknown[], R>(fn: (...args: Args) => R, iterableOfArgArrays: AsyncIterable<Args> | Iterable<Args>): AsyncGenerator<R>;
+/**
+ * Zip iterators, continuing to the longest one and filling exhausted
+ * ones with `fillValue`. Complement to the strict, stop-at-shortest
+ * zipSync/zipAsync. Mirrors Python's itertools.zip_longest.
+ * @kind function
+ * @name zipLongestSync
+ * @param fillValue value used once an input is exhausted
+ * @param iteratorList iterables to zip
+ */
+export declare function zipLongestSync<T, F>(fillValue: F, ...iteratorList: Array<Iterable<T>>): Generator<Array<T | F>>;
+/**
+ * Asynchronous dual of zipLongestSync. Pulls the next value from every
+ * input in parallel each round, like zipAsync.
+ * @kind function
+ * @name zipLongestAsync
+ */
+export declare function zipLongestAsync<T, F>(fillValue: F, ...iteratorList: Array<AsyncIterable<T> | Iterable<T>>): AsyncGenerator<Array<T | F>>;
+/**
+ * General slicing over an iterable. Mirrors Python's itertools.islice
+ * overloads: `isliceSync(iterable, stop)` or
+ * `isliceSync(iterable, start, stop, step)`. `step` has no native
+ * fast-path, so both sync and async are hand-rolled uniformly rather
+ * than branching between a native-composed common case and a fallback.
+ * @kind function
+ * @name isliceSync
+ */
+export declare function isliceSync<T>(iterable: Iterable<T>, ...args: Array<number | null | undefined>): Generator<T>;
+/**
+ * Asynchronous dual of isliceSync.
+ * @kind function
+ * @name isliceAsync
+ */
+export declare function isliceAsync<T>(iterable: AsyncIterable<T>, ...args: Array<number | null | undefined>): AsyncGenerator<T>;
+//# sourceMappingURL=itertools.d.ts.map