@ts-common/iterator - npm Package Compare versions

Comparing version 0.3.2 to 0.3.3

dist/index.d.ts

@@ -0,34 +1,132 @@
+/**
+ * See this PR https://github.com/microsoft/TypeScript/pull/30790
+ */
 export declare type IteratorResult<T> = {
+    /**
+     * - Has the value `true` if the iterator is past the end of the iterated sequence. In this case value optionally
+     *   specifies the return value of the iterator.
+     * - Has the value `false` if the iterator was able to produce the next value in the sequence. This is equivalent of
+     *   not specifying the done property altogether.
+     */
     readonly done: boolean;
+    /**
+     * any JavaScript value returned by the iterator. Can be omitted when done is true.
+     */
     readonly value: T;
 };
 export declare type Iterator<T> = {
+    /**
+     * Returns `IterableResult<T>`.
+     */
     readonly next: () => IteratorResult<T>;
 };
 export declare type Iterable<T> = {
+    /**
+     * The function returns an iterator.
+     */
     readonly [Symbol.iterator]: () => Iterator<T>;
 };
 export declare type IterableEx<T> = Iterable<T> & {
+    /**
+     * The function returns an iterator of a this container own enumerable number-keyed value [key, value] pairs.
+     */
     readonly entries: () => IterableEx<Entry<T>>;
+    /**
+     * Creates a new sequence whose values are calculated by passing this sequence's elements through the given
+     * function.
+     */
     readonly map: <R>(func: (v: T, i: number) => R) => IterableEx<R>;
+    /**
+     * The flatMap() method first maps each element using a mapping function, then flattens the result.
+     */
     readonly flatMap: <R>(func: (v: T, i: number) => Iterable<R>) => IterableEx<R>;
+    /**
+     * Creates a new sequence whose values are the elements of this sequence which satisfy the specified predicate.
+     */
     readonly filter: (func: (v: T, i: number) => boolean) => IterableEx<T>;
+    /**
+     * Creates a new sequence whose values are calculated by passing this sequence's elements through the given
+     * function. If the function `func` returns `undefined`, the item is removed from the sequence.
+     */
     readonly filterMap: <R>(func: (v: T, i: number) => R | undefined) => IterableEx<R>;
+    /**
+     * The forEach() method executes a provided function once for each sequence element.
+     */
     readonly forEach: (func: (v: T, i: number) => void) => void;
+    /**
+     * Creates a slice of sequence with n elements dropped from the beginning.
+     */
     readonly drop: (n?: number) => IterableEx<T>;
+    /**
+     * Creates a new sequence with all of the elements of this one, plus those of the given sequence(s).
+     */
     readonly concat: (...input: readonly (Iterable<T> | undefined)[]) => IterableEx<T>;
+    /**
+     * Creates a new sequence comprising the elements from the head of this sequence that satisfy some predicate. Once
+     * an element is encountered that doesn't satisfy the predicate, iteration will stop.
+     */
     readonly takeWhile: (func: (v: T, i: number) => boolean) => IterableEx<T>;
+    /**
+     * Creates a slice of sequence with n elements taken from the beginning.
+     */
     readonly take: (n?: number) => IterableEx<T>;
+    /**
+     * This method is like find except that it returns the `Entry<T>` of the first element predicate returns truthy for
+     * instead of the element itself. This is useful if the sequence can contain `undefined` values.
+     */
     readonly findEntry: (func: (v: T, i: number) => boolean) => Entry<T> | undefined;
+    /**
+     * Searches for the first element in the sequence satisfying a given predicate.
+     */
     readonly find: (func: (v: T, i: number) => boolean) => T | undefined;
+    /**
+     * Reduces collection to a value which is the accumulated result of running each element in collection thru
+     * `func`, where each successive invocation is supplied the return value of the previous.
+     */
     readonly fold: <A>(func: (a: A, b: T, i: number) => A, init: A) => A;
+    /**
+     * Reduces collection to a value which is the accumulated result of running each element in collection thru
+     * `func`, where each successive invocation is supplied the return value of the previous.
+     *
+     * The first element of collection is used as the initial value.
+     */
     readonly reduce: (func: (a: T, b: T, i: number) => T) => T | undefined;
+    /**
+     *  Returns the last element of this sequence.
+     */
     readonly last: () => T | undefined;
+    /**
+     * Checks whether at least one element in this sequence satisfies a given predicate (or, if no predicate is
+     * specified, whether the sequence contains at least one element).
+     */
     readonly some: (func?: (v: T, i: number) => boolean) => boolean;
+    /**
+     * Checks whether every element in this sequence satisfies a given predicate.
+     */
     readonly every: (func: (v: T, i: number) => boolean) => boolean;
+    /**
+     * Creates a new sequence by combining the elements from this sequence with corresponding elements from the
+     * specified sequence(s).
+     */
     readonly zip: (...inputs: readonly (Iterable<T> | undefined)[]) => IterableEx<readonly T[]>;
+    /**
+     * Checks if all items in the sequence are equal to the items in the given sequence `b`.
+     */
     readonly isEqual: <B>(b: Iterable<B> | undefined, e?: (ai: T, bi: B) => boolean) => boolean;
+    /**
+     * Creates an array snapshot of a sequence.
+     */
     readonly toArray: () => readonly T[];
+    /**
+     * Creates a new array with the same elements as this sequence, but in the opposite order.
+     */
     readonly reverse: () => readonly T[];
+    /**
+     * Checks whether the sequence has no elements.
+     */
     readonly isEmpty: () => boolean;
+    /**
+     * Creates a new sequence with every unique element from this one appearing exactly once (i.e., with duplicates
+     * removed).
+     */
     readonly uniq: (key?: (v: T) => unknown) => IterableEx<T>;
@@ -71,2 +169,3 @@ };
 export declare const reverse: <T>(i: Iterable<T> | undefined) => readonly T[];
+export declare const arrayReverse: <T>(a: readonly T[]) => IterableEx<T>;
 export declare const isEmpty: <T>(i: Iterable<T> | undefined) => boolean;
@@ -73,0 +172,0 @@ export declare const join: (i: Iterable<string> | undefined, separator: string) => string;

dist/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.iterable = (createIterator) => {
-    const property = (f) => (...p) => f(result, ...p);
-    const result = {
+    const it = { [Symbol.iterator]: createIterator };
+    const property = (f) => (...p) => f(it, ...p);
+    return {
         [Symbol.iterator]: createIterator,
@@ -31,3 +32,2 @@ concat: property(exports.concat),
     };
-    return result;
 };
@@ -47,3 +47,3 @@ exports.ENTRY_KEY = 0;
         /* tslint:disable-next-line:no-expression-statement */
-        ++index;
+        index += 1;
     }
@@ -107,3 +107,5 @@ });
 });
-exports.generate = (func, count) => infinite().takeWhile((_, i) => i !== count).map((_, i) => func(i));
+exports.generate = (func, count) => infinite()
+    .takeWhile((_, i) => i !== count)
+    .map((_, i) => func(i));
 exports.repeat = (v, count) => exports.generate(() => v, count);
@@ -123,5 +125,6 @@ exports.fold = (input, func, init) => {
 exports.every = (input, func) => !exports.some(input, (v, i) => !func(v, i));
-exports.forEach = (input, func) => 
-/* tslint:disable-next-line:no-expression-statement */
-exports.fold(input, (_, v, i) => { func(v, i); }, undefined);
+exports.forEach = (input, func) => {
+    // tslint:disable-next-line:no-expression-statement
+    exports.fold(input, (_, v, i) => { func(v, i); }, undefined);
+};
 exports.sum = (input) => exports.fold(input, (a, b) => a + b, 0);
@@ -178,2 +181,10 @@ exports.min = (input) => exports.fold(input, (a, b) => Math.min(a, b), Infinity);
 exports.reverse = (i) => exports.fold(i, (a, b) => [b, ...a], new Array());
+exports.arrayReverse = (a) => exports.iterable(function* () {
+    // tslint:disable-next-line:no-loop-statement
+    for (let i = a.length; i > 0;) {
+        // tslint:disable-next-line:no-expression-statement
+        i -= 1;
+        yield a[i];
+    }
+});
 exports.isEmpty = (i) => !exports.some(i, () => true);
@@ -180,0 +191,0 @@ exports.join = (i, separator) => {

package.json

 {
   "name": "@ts-common/iterator",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Iterator library for JavaScript and TypeScript",
@@ -65,3 +65,3 @@ "main": "dist/index.js",
   "devDependencies": {
-    "@types/jest": "^24.0.12",
+    "@types/jest": "^24.0.13",
     "@types/node": "^11.9.3",
@@ -68,0 +68,0 @@ "jest": "^24.8.0",

src/index.ts

@@ -0,3 +1,15 @@
+/**
+ * See this PR https://github.com/microsoft/TypeScript/pull/30790
+ */
 export type IteratorResult<T> = {
+    /**
+     * - Has the value `true` if the iterator is past the end of the iterated sequence. In this case value optionally
+     *   specifies the return value of the iterator.
+     * - Has the value `false` if the iterator was able to produce the next value in the sequence. This is equivalent of
+     *   not specifying the done property altogether.
+     */
     readonly done: boolean;
+    /**
+     * any JavaScript value returned by the iterator. Can be omitted when done is true.
+     */
     readonly value: T;
@@ -7,2 +19,5 @@ }
 export type Iterator<T> = {
+    /**
+     * Returns `IterableResult<T>`.
+     */
     readonly next: () => IteratorResult<T>;
@@ -12,2 +27,5 @@ }
 export type Iterable<T> = {
+    /**
+     * The function returns an iterator.
+     */
     readonly [Symbol.iterator]: () => Iterator<T>;
@@ -17,24 +35,104 @@ }
 export type IterableEx<T> = Iterable<T> & {
+    /**
+     * The function returns an iterator of a this container own enumerable number-keyed value [key, value] pairs.
+     */
     readonly entries: () => IterableEx<Entry<T>>
+    /**
+     * Creates a new sequence whose values are calculated by passing this sequence's elements through the given
+     * function.
+     */
     readonly map: <R>(func: (v: T, i: number) => R) => IterableEx<R>
+    /**
+     * The flatMap() method first maps each element using a mapping function, then flattens the result.
+     */
     readonly flatMap: <R>(func: (v: T, i: number) => Iterable<R>) => IterableEx<R>
+    /**
+     * Creates a new sequence whose values are the elements of this sequence which satisfy the specified predicate.
+     */
     readonly filter: (func: (v: T, i: number) => boolean) => IterableEx<T>
-    readonly filterMap: <R>(func: (v: T, i: number) => R|undefined) => IterableEx<R>
+    /**
+     * Creates a new sequence whose values are calculated by passing this sequence's elements through the given
+     * function. If the function `func` returns `undefined`, the item is removed from the sequence.
+     */
+    readonly filterMap: <R>(func: (v: T, i: number) => R | undefined) => IterableEx<R>
+    /**
+     * The forEach() method executes a provided function once for each sequence element.
+     */
     readonly forEach: (func: (v: T, i: number) => void) => void
+    /**
+     * Creates a slice of sequence with n elements dropped from the beginning.
+     */
     readonly drop: (n?: number) => IterableEx<T>
-    readonly concat: (...input: readonly (Iterable<T>|undefined)[]) => IterableEx<T>
+    /**
+     * Creates a new sequence with all of the elements of this one, plus those of the given sequence(s).
+     */
+    readonly concat: (...input: readonly (Iterable<T> | undefined)[]) => IterableEx<T>
+    /**
+     * Creates a new sequence comprising the elements from the head of this sequence that satisfy some predicate. Once
+     * an element is encountered that doesn't satisfy the predicate, iteration will stop.
+     */
     readonly takeWhile: (func: (v: T, i: number) => boolean) => IterableEx<T>
+    /**
+     * Creates a slice of sequence with n elements taken from the beginning.
+     */
     readonly take: (n?: number) => IterableEx<T>
-    readonly findEntry: (func: (v: T, i: number) => boolean) => Entry<T>|undefined
-    readonly find: (func: (v: T, i: number) => boolean) => T|undefined
+    /**
+     * This method is like find except that it returns the `Entry<T>` of the first element predicate returns truthy for
+     * instead of the element itself. This is useful if the sequence can contain `undefined` values.
+     */
+    readonly findEntry: (func: (v: T, i: number) => boolean) => Entry<T> | undefined
+    /**
+     * Searches for the first element in the sequence satisfying a given predicate.
+     */
+    readonly find: (func: (v: T, i: number) => boolean) => T | undefined
+    /**
+     * Reduces collection to a value which is the accumulated result of running each element in collection thru
+     * `func`, where each successive invocation is supplied the return value of the previous.
+     */
     readonly fold: <A>(func: (a: A, b: T, i: number) => A, init: A) => A
-    readonly reduce: (func: (a: T, b: T, i: number) => T) => T|undefined
-    readonly last: () => T|undefined
+    /**
+     * Reduces collection to a value which is the accumulated result of running each element in collection thru
+     * `func`, where each successive invocation is supplied the return value of the previous.
+     *
+     * The first element of collection is used as the initial value.
+     */
+    readonly reduce: (func: (a: T, b: T, i: number) => T) => T | undefined
+    /**
+     *  Returns the last element of this sequence.
+     */
+    readonly last: () => T | undefined
+    /**
+     * Checks whether at least one element in this sequence satisfies a given predicate (or, if no predicate is
+     * specified, whether the sequence contains at least one element).
+     */
     readonly some: (func?: (v: T, i: number) => boolean) => boolean
+    /**
+     * Checks whether every element in this sequence satisfies a given predicate.
+     */
     readonly every: (func: (v: T, i: number) => boolean) => boolean
-    readonly zip: (...inputs: readonly (Iterable<T>|undefined)[]) => IterableEx<readonly T[]>
-    readonly isEqual: <B>(b: Iterable<B>|undefined, e?: (ai: T, bi: B) => boolean) => boolean
+    /**
+     * Creates a new sequence by combining the elements from this sequence with corresponding elements from the
+     * specified sequence(s).
+     */
+    readonly zip: (...inputs: readonly (Iterable<T> | undefined)[]) => IterableEx<readonly T[]>
+    /**
+     * Checks if all items in the sequence are equal to the items in the given sequence `b`.
+     */
+    readonly isEqual: <B>(b: Iterable<B> | undefined, e?: (ai: T, bi: B) => boolean) => boolean
+    /**
+     * Creates an array snapshot of a sequence.
+     */
     readonly toArray: () => readonly T[]
+    /**
+     * Creates a new array with the same elements as this sequence, but in the opposite order.
+     */
     readonly reverse: () => readonly T[]
+    /**
+     * Checks whether the sequence has no elements.
+     */
     readonly isEmpty: () => boolean
+    /**
+     * Creates a new sequence with every unique element from this one appearing exactly once (i.e., with duplicates
+     * removed).
+     */
     readonly uniq: (key?: (v: T) => unknown) => IterableEx<T>,
@@ -44,5 +142,6 @@ }
 export const iterable = <T>(createIterator: () => Iterator<T>): IterableEx<T> => {
+    const it = { [Symbol.iterator]: createIterator }
     const property = <P extends readonly unknown[], R>(f: (self: Iterable<T>, ...p: P) => R) =>
-        (...p: P) => f(result, ...p)
-    const result: IterableEx<T> = {
+        (...p: P) => f(it, ...p)
+    return {
         [Symbol.iterator]: createIterator,
@@ -73,3 +172,2 @@ concat: property(concat),
     }
-    return result
 }
@@ -84,3 +182,3 @@
 
-export const entries = <T>(input: Iterable<T>|undefined): IterableEx<Entry<T>> =>
+export const entries = <T>(input: Iterable<T> | undefined): IterableEx<Entry<T>> =>
     iterable(function *() {
@@ -96,3 +194,3 @@ // tslint:disable-next-line:no-if-statement
             /* tslint:disable-next-line:no-expression-statement */
-            ++index
+            index += 1
         }
@@ -102,3 +200,3 @@ })
 export const map = <T, I>(
-    input: Iterable<I>|undefined,
+    input: Iterable<I> | undefined,
     func: (v: I, i: number) => T,
@@ -113,6 +211,6 @@ ): IterableEx<T> =>
 
-export const drop = <T>(input: Iterable<T>|undefined, n: number = 1): IterableEx<T> =>
+export const drop = <T>(input: Iterable<T> | undefined, n: number = 1): IterableEx<T> =>
     filter(input, (_, i) => n <= i)
 
-export const flat = <T>(input: Iterable<Iterable<T>|undefined>|undefined): IterableEx<T> =>
+export const flat = <T>(input: Iterable<Iterable<T> | undefined> | undefined): IterableEx<T> =>
     iterable(function *(): Iterator<T> {
@@ -132,7 +230,7 @@ // tslint:disable-next-line:no-if-statement
 
-export const concat = <T>(...input: readonly (Iterable<T>|undefined)[]): IterableEx<T> =>
+export const concat = <T>(...input: readonly (Iterable<T> | undefined)[]): IterableEx<T> =>
     flat(input)
 
 export const takeWhile = <T>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (v: T, i: number) => boolean,
@@ -151,9 +249,9 @@ ): IterableEx<T> =>
 
-export const take = <T>(input: Iterable<T>|undefined, n: number = 1) =>
+export const take = <T>(input: Iterable<T> | undefined, n: number = 1) =>
     takeWhile(input, (_, i) => i < n)
 
 export const findEntry = <T>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (v: T, i: number) => boolean,
-): Entry<T>|undefined => {
+): Entry<T> | undefined => {
     // tslint:disable-next-line:no-loop-statement
@@ -170,5 +268,5 @@ for (const e of entries(input)) {
 export const find = <T>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (v: T, i: number) => boolean,
-): T|undefined => {
+): T | undefined => {
     const e = findEntry(input, func)
@@ -179,3 +277,3 @@ return e === undefined ? undefined : e[ENTRY_VALUE]
 export const flatMap = <T, I>(
-    input: Iterable<I>|undefined,
+    input: Iterable<I> | undefined,
     func: (v: I, i: number) => Iterable<T>,
@@ -185,8 +283,8 @@ ): IterableEx<T> =>
 
-export const optionalToArray = <T>(v: T|undefined): readonly T[] =>
+export const optionalToArray = <T>(v: T | undefined): readonly T[] =>
     v === undefined ? [] : [v]
 
 export const filterMap = <T, I>(
-    input: Iterable<I>|undefined,
-    func: (v: I, i: number) => T|undefined,
+    input: Iterable<I> | undefined,
+    func: (v: I, i: number) => T | undefined,
 ): IterableEx<T> =>
@@ -196,3 +294,3 @@ flatMap(input, (v, i) => optionalToArray(func(v, i)))
 export const filter = <T>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (v: T, i: number) => boolean,
@@ -209,3 +307,5 @@ ): IterableEx<T> =>
 export const generate = <T>(func: (i: number) => T, count?: number): IterableEx<T> =>
-    infinite().takeWhile((_, i) => i !== count).map((_, i) => func(i))
+    infinite()
+        .takeWhile((_, i) => i !== count)
+        .map((_, i) => func(i))
 
@@ -216,3 +316,3 @@ export const repeat = <T>(v: T, count?: number): IterableEx<T> =>
 export const fold = <T, A>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (a: A, b: T, i: number) => A,
@@ -231,6 +331,6 @@ init: A,
 export const reduce = <T>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (a: T, b: T, i: number) => T,
-): T|undefined =>
-    fold<T, T|undefined>(
+): T | undefined =>
+    fold<T, T | undefined>(
         input,
@@ -241,7 +341,7 @@ (a, b, i) => a !== undefined ? func(a, b, i) : b,
 
-export const last = <T>(input: Iterable<T>|undefined): T|undefined =>
+export const last = <T>(input: Iterable<T> | undefined): T | undefined =>
     reduce(input, (_, v) => v)
 
 export const some = <T>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (v: T, i: number) => boolean = () => true,
@@ -252,3 +352,3 @@ ): boolean =>
 export const every = <T>(
-    input: Iterable<T>|undefined,
+    input: Iterable<T> | undefined,
     func: (v: T, i: number) => boolean,
@@ -258,16 +358,17 @@ ): boolean =>
 
-export const forEach = <T>(input: Iterable<T>|undefined, func: (v: T, i: number) => void): void =>
-    /* tslint:disable-next-line:no-expression-statement */
+export const forEach = <T>(input: Iterable<T> | undefined, func: (v: T, i: number) => void): void => {
+    // tslint:disable-next-line:no-expression-statement
     fold<T, void>(input, (_, v, i) => { func(v, i) }, undefined)
+}
 
-export const sum = (input: Iterable<number>|undefined): number =>
+export const sum = (input: Iterable<number> | undefined): number =>
     fold(input, (a, b) => a + b, 0)
 
-export const min = (input: Iterable<number>|undefined): number =>
+export const min = (input: Iterable<number> | undefined): number =>
     fold(input, (a, b) => Math.min(a, b), Infinity)
 
-export const max = (input: Iterable<number>|undefined): number =>
+export const max = (input: Iterable<number> | undefined): number =>
     fold(input, (a, b) => Math.max(a, b), -Infinity)
 
-export const zip = <T>(...inputs: readonly (Iterable<T>|undefined)[]): IterableEx<readonly T[]> =>
+export const zip = <T>(...inputs: readonly (Iterable<T> | undefined)[]): IterableEx<readonly T[]> =>
     iterable(function *(): Iterator<readonly T[]> {
@@ -298,4 +399,4 @@ const iterators = inputs.map(
 export const isEqual = <A, B>(
-    a: Iterable<A>|undefined,
-    b: Iterable<B>|undefined,
+    a: Iterable<A> | undefined,
+    b: Iterable<B> | undefined,
     e: (ai: A, bi: B) => boolean = isStrictEqual,
@@ -328,15 +429,25 @@ ): boolean => {
 
-export const isArray = <T, U>(v: readonly T[]|U): v is readonly T[] =>
+export const isArray = <T, U>(v: readonly T[] | U): v is readonly T[] =>
     v instanceof Array
 
-export const toArray = <T>(i: Iterable<T>|undefined): readonly T[] =>
+export const toArray = <T>(i: Iterable<T> | undefined): readonly T[] =>
     i === undefined ? [] : Array.from(i)
 
-export const reverse = <T>(i: Iterable<T>|undefined): readonly T[] =>
+export const reverse = <T>(i: Iterable<T> | undefined): readonly T[] =>
     fold(i, (a, b) => [b, ...a], new Array<T>())
 
-export const isEmpty = <T>(i: Iterable<T>|undefined): boolean =>
+export const arrayReverse = <T>(a: readonly T[]): IterableEx<T> =>
+    iterable(function *() {
+        // tslint:disable-next-line:no-loop-statement
+        for (let i = a.length; i > 0;) {
+            // tslint:disable-next-line:no-expression-statement
+            i -= 1
+            yield a[i]
+        }
+    })
+
+export const isEmpty = <T>(i: Iterable<T> | undefined): boolean =>
     !some(i, () => true)
 
-export const join = (i: Iterable<string>|undefined, separator: string): string => {
+export const join = (i: Iterable<string> | undefined, separator: string): string => {
     const result = reduce(i, (a, b) => a + separator + b)
@@ -349,3 +460,3 @@ return result === undefined ? "" : result
 
-export const dropRight = <T>(i: readonly T[]|undefined, n: number = 1): IterableEx<T> =>
+export const dropRight = <T>(i: readonly T[] | undefined, n: number = 1): IterableEx<T> =>
     i === undefined ? empty() : take(i, i.length - n)
@@ -352,0 +463,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

61106

increased by17.98%

Lines of code

788

increased by38.73%

No dependency changes