js迭代协议

November 15, 2022

迭代协议

迭代协议分为可迭代协议和迭代器协议。

注：在下文中我们会将实现可迭代协议的对象称为可迭代对象，将实现了迭代器协议的对象称为迭代器对象（简称：迭代器）。

可以使用可迭代对象的地方有： for...of 循环、... （spread 运算符）、yield* 语法和数组解构。
而可迭代对象的功能实际上是由迭代器来提供的。
因此，迭代器对象无法脱离迭代器，而迭代器可以离开可迭代对象使用。

type Value = number; // 仅为了标识被迭代的泛型

const example1: Iterable<Value> = {
    // 可迭代对象 的 Symbol.iterator 属性是返回 迭代器对象 的函数
    // （对于 ts 而言就是实现 Iterable 接口）
    [Symbol.iterator]: () => {
        const iterator: Iterator<Value> = {
            next() {
                const result: IteratorResult<Value> = { value: 123, done: true };
                return result;
            },
        };
        return iterator;
    },
};

// IterableIterator 是 ts 提供的实用接口，它把 可迭代对象 和 迭代器对象 结合成一个对象
const example2: IterableIterator<Value> = {
    next() {
        return { value: 123, done: true };
    },
    [Symbol.iterator]() {
        return this;
    },
};

// 生成器返回 Generator 对象，它是可迭代的迭代器
const viaGenerator: Iterable<Value> = {
    [Symbol.iterator]: function* () {
        yield 123;
        yield 456;
        yield 789;
    },
};

// lib.es2015.iterable.d.ts

interface IteratorYieldResult<TYield> {
    done?: false;
    value: TYield;
}

interface IteratorReturnResult<TReturn> {
    done: true;
    value: TReturn;
}

type IteratorResult<T, TReturn = any> = IteratorYieldResult<T> | IteratorReturnResult<TReturn>;

interface Iterator<T, TReturn = any, TNext = undefined> {
    // NOTE: 'next' is defined using a tuple to ensure we report the correct assignability errors in all places.
    next(...args: [] | [TNext]): IteratorResult<T, TReturn>;
    return?(value?: TReturn): IteratorResult<T, TReturn>;
    throw?(e?: any): IteratorResult<T, TReturn>;
}

interface Iterable<T> {
    [Symbol.iterator](): Iterator<T>;
}

interface IterableIterator<T> extends Iterator<T> {
    [Symbol.iterator](): IterableIterator<T>;
}

生成器

生成器函数返回一个实现 Generator 接口的对象
Generator 继承 Iterator，但仔细看可以发现 Generator 其实完全相当与 Required<IterableIterator>
也就是说生成器函数返回的对象同时是可迭代对象和迭代器对象

使用生成器可以参见此处：https://zh.javascript.info/generators

// lib.es2015.generator.d.ts

interface Generator<T = unknown, TReturn = any, TNext = unknown> extends Iterator<T, TReturn, TNext> {
    // NOTE: 'next' is defined using a tuple to ensure we report the correct assignability errors in all places.
    next(...args: [] | [TNext]): IteratorResult<T, TReturn>;
    return(value: TReturn): IteratorResult<T, TReturn>;
    throw(e: any): IteratorResult<T, TReturn>;
    [Symbol.iterator](): Generator<T, TReturn, TNext>;
}

interface GeneratorFunction {
    /**
     * Creates a new Generator object.
     * @param args A list of arguments the function accepts.
     */
    new (...args: any[]): Generator;
    /**
     * Creates a new Generator object.
     * @param args A list of arguments the function accepts.
     */
    (...args: any[]): Generator;
    /**
     * The length of the arguments.
     */
    readonly length: number;
    /**
     * Returns the name of the function.
     */
    readonly name: string;
    /**
     * A reference to the prototype.
     */
    readonly prototype: Generator;
}

interface GeneratorFunctionConstructor {
    /**
     * Creates a new Generator function.
     * @param args A list of arguments the function accepts.
     */
    new (...args: string[]): GeneratorFunction;
    /**
     * Creates a new Generator function.
     * @param args A list of arguments the function accepts.
     */
    (...args: string[]): GeneratorFunction;
    /**
     * The length of the arguments.
     */
    readonly length: number;
    /**
     * Returns the name of the function.
     */
    readonly name: string;
    /**
     * A reference to the prototype.
     */
    readonly prototype: GeneratorFunction;
}

GeneratorFunctionConstructor 接口并没有什么实用意义，其对应 FunctionConstructor
FunctionConstructor 接口被 Function 构造函数实现，定义如下

interface FunctionConstructor {
    /**
     * Creates a new function.
     * @param args A list of arguments the function accepts.
     */
    new (...args: string[]): Function;
    (...args: string[]): Function;
    readonly prototype: Function;
}

declare var Function: FunctionConstructor;

注：通过原型获取生成器函数构造器

const GeneratorFunction = Object.getPrototypeOf(function* () {}).constructor;

异步迭代器和异步可迭代协议

异步迭代器只不过是支持异步的迭代器，但注意同时实现迭代协议与异步迭代协议显然是不冲突的。

type Value = number; // 仅为了标识被迭代的泛型

const example3: AsyncIterable<Value> = {
    [Symbol.asyncIterator]: () => {
        const asyncIterator: AsyncIterator<Value> = {
            // 不同之处就在于这里的 async
            async next() {
                const result: IteratorResult<Value> = { value: 123, done: true };
                return result;
            },
        };
        return asyncIterator;
    },
};

const example4: AsyncIterableIterator<Value> = {
    async next() {
        return { value: 123, done: true };
    },
    [Symbol.asyncIterator]() {
        return this;
    },
};

const viaAsyncGenerator: AsyncIterable<Value> = {
    [Symbol.asyncIterator]: async function* () {
        yield 123;
        yield 456;
        yield 789;
    },
};

// lib.es2018.asynciterable.d.ts

interface AsyncIterator<T, TReturn = any, TNext = undefined> {
    // NOTE: 'next' is defined using a tuple to ensure we report the correct assignability errors in all places.
    next(...args: [] | [TNext]): Promise<IteratorResult<T, TReturn>>;
    return?(value?: TReturn | PromiseLike<TReturn>): Promise<IteratorResult<T, TReturn>>;
    throw?(e?: any): Promise<IteratorResult<T, TReturn>>;
}

interface AsyncIterable<T> {
    [Symbol.asyncIterator](): AsyncIterator<T>;
}

interface AsyncIterableIterator<T> extends AsyncIterator<T> {
    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
}

异步生成器

// lib.es2018.asyncgenerator.d.ts

interface AsyncGenerator<T = unknown, TReturn = any, TNext = unknown> extends AsyncIterator<T, TReturn, TNext> {
    // NOTE: 'next' is defined using a tuple to ensure we report the correct assignability errors in all places.
    next(...args: [] | [TNext]): Promise<IteratorResult<T, TReturn>>;
    return(value: TReturn | PromiseLike<TReturn>): Promise<IteratorResult<T, TReturn>>;
    throw(e: any): Promise<IteratorResult<T, TReturn>>;
    [Symbol.asyncIterator](): AsyncGenerator<T, TReturn, TNext>;
}

interface AsyncGeneratorFunction {
    /**
     * Creates a new AsyncGenerator object.
     * @param args A list of arguments the function accepts.
     */
    new (...args: any[]): AsyncGenerator;
    /**
     * Creates a new AsyncGenerator object.
     * @param args A list of arguments the function accepts.
     */
    (...args: any[]): AsyncGenerator;
    /**
     * The length of the arguments.
     */
    readonly length: number;
    /**
     * Returns the name of the function.
     */
    readonly name: string;
    /**
     * A reference to the prototype.
     */
    readonly prototype: AsyncGenerator;
}

interface AsyncGeneratorFunctionConstructor {
    /**
     * Creates a new AsyncGenerator function.
     * @param args A list of arguments the function accepts.
     */
    new (...args: string[]): AsyncGeneratorFunction;
    /**
     * Creates a new AsyncGenerator function.
     * @param args A list of arguments the function accepts.
     */
    (...args: string[]): AsyncGeneratorFunction;
    /**
     * The length of the arguments.
     */
    readonly length: number;
    /**
     * Returns the name of the function.
     */
    readonly name: string;
    /**
     * A reference to the prototype.
     */
    readonly prototype: AsyncGeneratorFunction;
}

`for...of` `for await..of`

for (const value of example1) console.log(value);
// => 123

for await (const value of example3) console.log(value);
// => 123

注意，for await 也可用于迭代普通迭代器（反之则不行）

for await (var value of example1) console.log(value);

// 就像 await 也可用于任意值一样
console.log(await "test");

←Back to home

This work is licensed under CC BY-NC-SA 4.0