or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async-iterator-utilities.mdindex.mditerator-utilities.md
tile.json

tessl/npm-iterall

Minimal zero-dependency utilities for using JavaScript Iterables in all environments.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/iterall@1.3.x

To install, run

npx @tessl/cli install tessl/npm-iterall@1.3.0

index.mddocs/

iterall

iterall provides essential utilities for working with JavaScript Iterator and AsyncIterator protocols across all JavaScript environments, including legacy browsers. It offers cross-compatible implementations that support ES2015 Iterables, AsyncIterables, and Array-like objects, enabling libraries to accept any collection type instead of being limited to Arrays.

Package Information

  • Package Name: iterall
  • Package Type: npm
  • Language: JavaScript (ES modules)
  • Installation: npm install iterall

Core Imports

import { 
  $$iterator, $$asyncIterator,
  isIterable, isArrayLike, isCollection,
  getIterator, getIteratorMethod, createIterator, forEach,
  isAsyncIterable, getAsyncIterator, getAsyncIteratorMethod, createAsyncIterator, forAwaitEach
} from "iterall";

For CommonJS:

const { 
  $$iterator, $$asyncIterator,
  isIterable, isArrayLike, isCollection,
  getIterator, getIteratorMethod, createIterator, forEach,
  isAsyncIterable, getAsyncIterator, getAsyncIteratorMethod, createAsyncIterator, forAwaitEach
} = require("iterall");

Basic Usage

import { isCollection, forEach, forAwaitEach } from "iterall";

// Sync iteration - works with Arrays, Maps, Sets, NodeLists, TypedArrays, etc.
if (isCollection(myData)) {
  forEach(myData, (item, index) => {
    console.log(`Item ${index}:`, item);
  });
}

// Async iteration - works with AsyncIterables and Iterables containing Promises
await forAwaitEach(myAsyncData, async (item, index) => {
  const processed = await processItem(item);
  console.log(`Processed ${index}:`, processed);
});

Architecture

iterall is built around JavaScript's iteration protocols with comprehensive fallback support:

  • Cross-environment Compatibility: Works in all JavaScript environments, from ES3 to modern browsers
  • Protocol Detection: Smart detection of Iterator, AsyncIterator, and Array-like objects
  • Symbol Fallbacks: Uses Symbol.iterator/Symbol.asyncIterator when available, falls back to string property names
  • Performance Optimization: Delegates to native methods when available (e.g., Array.prototype.forEach)
  • Zero Dependencies: Minimal library footprint with no external dependencies

Capabilities

Iterator Utilities

Core synchronous iteration functionality for working with Iterables, Array-like objects, and testing for iteration support. Essential for libraries that need to accept multiple collection types.

// Symbol for creating iterables
export const $$iterator: unique symbol;

// Type checking functions
function isIterable(obj: any): obj is Iterable<any>;
function isArrayLike(obj: any): obj is { length: number };
function isCollection(obj: any): obj is Iterable<any> | { length: number };

// Iterator creation and access
function getIterator<TValue>(iterable: Iterable<TValue>): Iterator<TValue>;
function getIterator(iterable: any): void | Iterator<any>;
function getIteratorMethod<TValue>(iterable: Iterable<TValue>): () => Iterator<TValue>;
function getIteratorMethod(iterable: any): void | (() => Iterator<any>);
function createIterator<TValue>(collection: Iterable<TValue>): Iterator<TValue>;
function createIterator(collection: { length: number }): Iterator<any>;
function createIterator(collection: any): void | Iterator<any>;

// Iteration utilities  
function forEach<TCollection extends Iterable<any>>(
  collection: TCollection,
  callbackFn: (value: ValueOf<TCollection>, index: number, collection: TCollection) => any,
  thisArg?: any
): void;
function forEach<TCollection extends { length: number }>(
  collection: TCollection,
  callbackFn: (value: any, index: number, collection: TCollection) => any,
  thisArg?: any
): void;

Iterator Utilities

AsyncIterator Utilities

Asynchronous iteration functionality for working with AsyncIterables, Promise-containing Iterables, and Array-like objects. Enables consistent async iteration patterns across all JavaScript environments.

// Symbol for creating async iterables
export const $$asyncIterator: unique symbol;

// Type checking function
function isAsyncIterable(obj: any): obj is AsyncIterable<any>;

// AsyncIterator creation and access
function getAsyncIterator<TValue>(asyncIterable: AsyncIterable<TValue>): AsyncIterator<TValue>;
function getAsyncIterator(asyncIterable: any): void | AsyncIterator<any>;
function getAsyncIteratorMethod<TValue>(asyncIterable: AsyncIterable<TValue>): () => AsyncIterator<TValue>;
function getAsyncIteratorMethod(asyncIterable: any): void | (() => AsyncIterator<any>);
function createAsyncIterator<TValue>(
  collection: AsyncIterable<TValue> | Iterable<Promise<TValue> | TValue>
): AsyncIterator<TValue>;
function createAsyncIterator(collection: { length: number }): AsyncIterator<any>;
function createAsyncIterator(collection: any): void | AsyncIterator<any>;

// Async iteration utility
function forAwaitEach<TCollection extends AsyncIterable<any>>(
  collection: TCollection,
  callbackFn: (value: ResolvedOf<TCollection>, index: number, collection: TCollection) => any,
  thisArg?: any
): Promise<void>;
function forAwaitEach<TCollection extends Iterable<any>>(
  collection: TCollection,
  callbackFn: (value: ResolvedOf<TCollection>, index: number, collection: TCollection) => any,
  thisArg?: any
): Promise<void>;
function forAwaitEach<TCollection extends { length: number }>(
  collection: TCollection,
  callbackFn: (value: any, index: number, collection: TCollection) => any,
  thisArg?: any
): Promise<void>;

AsyncIterator Utilities

Types

// Iterator and AsyncIterator types are built into JavaScript/TypeScript
// iterall uses these standard types throughout its API

interface Iterator<T> {
  next(): IteratorResult<T>;
  return?(value?: any): IteratorResult<T>;
  throw?(e?: any): IteratorResult<T>;
}

interface AsyncIterator<T> {
  next(): Promise<IteratorResult<T>>;
  return?(value?: any): Promise<IteratorResult<T>>;
  throw?(e?: any): Promise<IteratorResult<T>>;
}

interface IteratorResult<T> {
  done: boolean;
  value: T;
}

// Helper types used in function signatures
type ValueOf<TCollection> =
  TCollection extends Iterable<infer TValue> ? TValue : never;

type ResolvedOf<TCollection> =
  TCollection extends AsyncIterable<infer TValue> ? TValue :
  TCollection extends Iterable<infer U> ?
    U extends Promise<infer TValue> ? TValue : U :
  never;