0
# iterall
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: iterall
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install iterall`
10

11
## Core Imports
12

13
```javascript
14
import { 
15
  $$iterator, $$asyncIterator,
16
  isIterable, isArrayLike, isCollection,
17
  getIterator, getIteratorMethod, createIterator, forEach,
18
  isAsyncIterable, getAsyncIterator, getAsyncIteratorMethod, createAsyncIterator, forAwaitEach
19
} from "iterall";
20
```
21

22
For CommonJS:
23

24
```javascript
25
const { 
26
  $$iterator, $$asyncIterator,
27
  isIterable, isArrayLike, isCollection,
28
  getIterator, getIteratorMethod, createIterator, forEach,
29
  isAsyncIterable, getAsyncIterator, getAsyncIteratorMethod, createAsyncIterator, forAwaitEach
30
} = require("iterall");
31
```
32

33
## Basic Usage
34

35
```javascript
36
import { isCollection, forEach, forAwaitEach } from "iterall";
37

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

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

52
## Architecture
53

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

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

62
## Capabilities
63

64
### Iterator Utilities
65

66
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.
67

68
```javascript { .api }
69
// Symbol for creating iterables
70
export const $$iterator: unique symbol;
71

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

77
// Iterator creation and access
78
function getIterator<TValue>(iterable: Iterable<TValue>): Iterator<TValue>;
79
function getIterator(iterable: any): void | Iterator<any>;
80
function getIteratorMethod<TValue>(iterable: Iterable<TValue>): () => Iterator<TValue>;
81
function getIteratorMethod(iterable: any): void | (() => Iterator<any>);
82
function createIterator<TValue>(collection: Iterable<TValue>): Iterator<TValue>;
83
function createIterator(collection: { length: number }): Iterator<any>;
84
function createIterator(collection: any): void | Iterator<any>;
85

86
// Iteration utilities  
87
function forEach<TCollection extends Iterable<any>>(
88
  collection: TCollection,
89
  callbackFn: (value: ValueOf<TCollection>, index: number, collection: TCollection) => any,
90
  thisArg?: any
91
): void;
92
function forEach<TCollection extends { length: number }>(
93
  collection: TCollection,
94
  callbackFn: (value: any, index: number, collection: TCollection) => any,
95
  thisArg?: any
96
): void;
97
```
98

99
[Iterator Utilities](./iterator-utilities.md)
100

101
### AsyncIterator Utilities
102

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

105
```javascript { .api }
106
// Symbol for creating async iterables
107
export const $$asyncIterator: unique symbol;
108

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

112
// AsyncIterator creation and access
113
function getAsyncIterator<TValue>(asyncIterable: AsyncIterable<TValue>): AsyncIterator<TValue>;
114
function getAsyncIterator(asyncIterable: any): void | AsyncIterator<any>;
115
function getAsyncIteratorMethod<TValue>(asyncIterable: AsyncIterable<TValue>): () => AsyncIterator<TValue>;
116
function getAsyncIteratorMethod(asyncIterable: any): void | (() => AsyncIterator<any>);
117
function createAsyncIterator<TValue>(
118
  collection: AsyncIterable<TValue> | Iterable<Promise<TValue> | TValue>
119
): AsyncIterator<TValue>;
120
function createAsyncIterator(collection: { length: number }): AsyncIterator<any>;
121
function createAsyncIterator(collection: any): void | AsyncIterator<any>;
122

123
// Async iteration utility
124
function forAwaitEach<TCollection extends AsyncIterable<any>>(
125
  collection: TCollection,
126
  callbackFn: (value: ResolvedOf<TCollection>, index: number, collection: TCollection) => any,
127
  thisArg?: any
128
): Promise<void>;
129
function forAwaitEach<TCollection extends Iterable<any>>(
130
  collection: TCollection,
131
  callbackFn: (value: ResolvedOf<TCollection>, index: number, collection: TCollection) => any,
132
  thisArg?: any
133
): Promise<void>;
134
function forAwaitEach<TCollection extends { length: number }>(
135
  collection: TCollection,
136
  callbackFn: (value: any, index: number, collection: TCollection) => any,
137
  thisArg?: any
138
): Promise<void>;
139
```
140

141
[AsyncIterator Utilities](./async-iterator-utilities.md)
142

143
## Types
144

145
```javascript { .api }
146
// Iterator and AsyncIterator types are built into JavaScript/TypeScript
147
// iterall uses these standard types throughout its API
148

149
interface Iterator<T> {
150
  next(): IteratorResult<T>;
151
  return?(value?: any): IteratorResult<T>;
152
  throw?(e?: any): IteratorResult<T>;
153
}
154

155
interface AsyncIterator<T> {
156
  next(): Promise<IteratorResult<T>>;
157
  return?(value?: any): Promise<IteratorResult<T>>;
158
  throw?(e?: any): Promise<IteratorResult<T>>;
159
}
160

161
interface IteratorResult<T> {
162
  done: boolean;
163
  value: T;
164
}
165

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

170
type ResolvedOf<TCollection> =
171
  TCollection extends AsyncIterable<infer TValue> ? TValue :
172
  TCollection extends Iterable<infer U> ?
173
    U extends Promise<infer TValue> ? TValue : U :
174
  never;
175
```