Add an Iterator.from TypeScript goody

[elimanzo]

based off of MDN

closes #343

[elimanzo]

@miorel I think the snapshots are failing because of the declare class. I'm currently getting

Only interface declarations are currently supported in module declarations, got: ClassDeclaration

[miorel]

Can we use the implementation of .toIterable here? I'm hoping we can call it with a custom this, similar to what we were discussing this weekend.

Suggested change

	if (typeof iterator === "object" && Symbol.iterator in iterator) {
	return iterator as IterableIterator<T>;
	} else {
	return {
	...iterator,
	[Symbol.iterator]() {
	return this;
	},
	} as IterableIterator<T>;
	}
	return iteratorPrototype.toIterable.call(iterator);

[elimanzo]

I'm a bit confused did we want the custom annotation kind of like

declare global {
  interface IteratorConstructor {
    from<T>(
      this: Iterator<T>, // this context
      object: Iterator<T> | Iterable<T> | { next(): IteratorResult<T> },
    ): IterableIterator<T>;
  }

  const Iterator: IteratorConstructor;
}

Also while returning
return iteratorPrototype.toIterable.call(iterator);
it seems that I need to assert as IterableIterator<T> because of the type error

Type 'IterableIterator<unknown>' is not assignable to type 'IterableIterator<T>'.
  The types returned by 'next(...)' are incompatible between these types.
    Type 'IteratorResult<unknown, any>' is not assignable to type 'IteratorResult<T, any>'.
      Type 'IteratorYieldResult<unknown>' is not assignable to type 'IteratorResult<T, any>'.
        Type 'IteratorYieldResult<unknown>' is not assignable to type 'IteratorYieldResult<T>'.
          Type 'unknown' is not assignable to type 'T'.
            'T' could be instantiated with an arbitrary type which could be unrelated to 'unknown'.ts(2322)

[miorel]

Fun question for you: why do we have to do iteratorFactory.call(object) and can't just do iteratorFactory()?

Suggested change

	if (typeof (object as Iterable<T>)[Symbol.iterator] === "function") {
	const iterable = object as Iterable<T>;
	const iterator = iterable[Symbol.iterator]();
	return iteratorPrototype.toIterable.call(iterator) as IterableIterator<T>;
	}
	const iteratorFactory = (object as Iterable<T>)[Symbol.iterator];
	if (typeof iteratorFactory === "function") {
	return toIterable.call(iteratorFactory.call(object));
	}

[elimanzo]

Yeah this is because of the binding of this right, and we need to bind object to iteratorFactory when invoking the function?

[miorel]

Suggested change

	if (Object.prototype.isPrototypeOf.call(iteratorPrototype, object)) {
	return iteratorPrototype.toIterable.call(
	object as Iterator<T>,
	) as IterableIterator<T>;
	}
	if (iteratorPrototype.isPrototypeOf(object)) {
	return toIterable.call(object as Iterator<T>);
	}

[elimanzo]

I had to do this to suppress the linter