iterange v1.0.0

iterange

Numeric sequence lazy generator, TC39 proposal-iterator.range implementation.

Entrypoint

This project provides ponyfill and polyfill.

Polyfill has a side effect, so the endpoint is isolated.

The entrypoint of each are as follows:

Incremental sequence

Specify start and end. By default, step is 1 and end is exclusive.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const start = 0;
const end = 5;

assertEquals([...range(start, end)], [0, 1, 2, 3, 4]);

Decremental sequence

If end is less than start, a decremental sequence is generated.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(1, -3);

assertEquals(iterator.next().value, 1);
assertEquals(iterator.next().value, 0);
assertEquals(iterator.next().value, -1);

Step

You can change the interval(step) of the sequence. The default is 1 (or 1n for bigint).

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(0, Infinity, 2);

assertEquals(iterator.next().value, 0);
assertEquals(iterator.next().value, 2);
assertEquals(iterator.next().value, 4);

Inclusive end range

By default, end is exclusive. This can be changed by specifying options.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

assertEquals([...range(0, 5, { inclusive: true })], [0, 1, 2, 3, 4, 5]);

Step option

Option accepts another step field. This is equivalent to step.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(0, -Infinity, { step: -2 });

assertEquals(iterator.next().value, 0);
assertEquals(iterator.next().value, -2);
assertEquals(iterator.next().value, -4);

Bigint

The range supports bigint as well as number.

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";

const iterator = range(0n, 100n, { step: 10n });

assertEquals(iterator.next().value, 0n);
assertEquals(iterator.next().value, 10n);
assertEquals(iterator.next().value, 20n);

That is, the following cannot be compiled and are type safe:

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";

//@ts-expect-error
range(0, 0n);
//@ts-expect-error
range(0, 100, 3n);
//@ts-expect-error
range(1n, Infinity, { step: 1 });

Throwing error

Throws RangeError in the following cases:

• start, end or step is NaN
• start is infinity
• if step is 0, start and end are not the same

import { range } from "https://deno.land/x/iterange@$VERSION/mod.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => range(NaN, 0).next());
assertThrows(() => range(0, NaN).next());
assertThrows(() => range(0, Infinity, NaN).next());
assertThrows(() => range(Infinity, Infinity).next());
assertThrows(() => range(0n, 1n, { step: 0n }).next());

Polyfill

Polyfill affects the global object. You must be very careful when using it.

Depends on the Iterator object. If there is no Iterator, a runtime error will occur.

import "https://deno.land/x/iterange@$VERSION/polyfill.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

assert(Iterator.range);

API

See deno doc for all APIs.

License

Copyright © 2023-present Tomoki Miyauchi.

Released under the MIT license