Large v1.0.0 update.

Documentation overhauls, added more malleable generic signature, etc.

Author: Trevor Sears

ts/abstract-iterable.ts

@@ -1,38 +1,60 @@
 /*
- *	Created by Trevor Sears <trevorsears.main@gmail.com>.
- *	7:45 PM -- October 06th, 2019.
- *	Project: @jsdsl/iterator
+ * Created by Trevor Sears <trevor@trevorsears.com> (https://trevorsears.com/).
+ * 3:43 PM -- August 31st, 2021.
+ * Project: @jsdsl/iterator
+ * 
+ * @jsdsl/iterator - A collection of classes that allow iteration over a predefined collection of elements.
+ * Copyright (C) 2021 Trevor Sears
+ * 
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { Iterator as JSDSLIterator } from "./iterator";
-import { Iterable as JSDSLIterable } from "./iterable";
+import { Iterator } from "./iterator";
+import { Iterable } from "./iterable";
 
 /**
- * An abstract implementation of the JSDSL {@link Iterable} interface.
+ * A basic abstract implementation of a class that is iterable (i.e. navigable via JavaScript's `for...of` construct).
+ * 
+ * This class serves as an abstract implementation of the JSDSL {@link Iterable} interface.
+ *
+ * @param {any} E The type of element that this AbstractIterable intends to iterate over.
+ * @param {any} U The type of the value that will be returned in the case that this AbstractIterable's content has been
+ * exhausted. Can be set to 'void' in the case that this AbstractIterable has infinite content. Defaults to `undefined`.
  * 
- * @author Trevor Sears <trevorsears.main@gmail.com>
- * @version v0.1.0
+ * @author Trevor Sears <trevor@trevorsears.com>
+ * @version v1.0.0
  * @since v0.1.0
  */
-export abstract class AbstractIterable<E> implements JSDSLIterable<E> {
+export abstract class AbstractIterable<E, U = undefined> implements Iterable<E, U> {
 
 	/**
 	 * Returns an iterator over the element contents of this AbstractIterable.
 	 *
-	 * @return An iterator over the element contents of this AbstractIterable.
+	 * @return {Iterator<E, U>} An iterator over the element contents of this AbstractIterable.
 	 */
-	public abstract iterator(): JSDSLIterator<E>;
+	public abstract iterator(): Iterator<E, U>;
 
 	/**
-	 * Returns an instance of an IterableIterator that allows 'this' to be iterable using the baked-in 'for...of'
+	 * Returns an instance of an IterableIterator that allows 'this' to be iterable using the baked-in `for...of`
 	 * syntax, rather than more verbose iteration (i.e. using a 'while' loop).
 	 *
-	 * @return An instance of an IterableIterator.
+	 * @return {IterableIterator<E>} An instance of an IterableIterator.
 	 */
 	public [Symbol.iterator](): IterableIterator<E> {
 
-		return this.iterator().getIterableIterator();
+		return this.iterator()[Symbol.iterator]();
 
 	}
 
-}
+}

ts/abstract-iterator.ts

@@ -1,20 +1,47 @@
 /*
- *	Created by Trevor Sears <trevorsears.main@gmail.com>.
- *	7:43 PM -- October 06th, 2019.
- *	Project: @jsdsl/iterator
+ * Created by Trevor Sears <trevor@trevorsears.com> (https://trevorsears.com/).
+ * 3:43 PM -- August 31st, 2021.
+ * Project: @jsdsl/iterator
+ * 
+ * @jsdsl/iterator - A collection of classes that allow iteration over a predefined collection of elements.
+ * Copyright (C) 2021 Trevor Sears
+ * 
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { Iterator as JSDSLIterator } from "./iterator";
+import { Iterator } from "./iterator";
 import { AbstractIterable } from "./abstract-iterable";
 
 /**
- * An abstract implementation of the JSDSL {@link Iterator} interface.
+ * A basic abstract implementation of the JSDSL {@link Iterator} protocol, a class that furnishes the functionality
+ * required to use an object with the JavaScript `for...of` syntax.
  * 
- * @author Trevor Sears <trevorsears.main@gmail.com>
- * @version v0.2.0
+ * Note: Usually, classes that desire to be 'iterable' should not extend this class, but should instead implement the
+ * {@link Iterable} interface (or extend the {@link AbstractIterable} abstract class). Extending this class
+ * syntactically implies that the class in question 'is-a' iterator, whereas most use cases intend to assert that the
+ * class in question 'has-a' iterator. In either case, iteration via `for...of` works as expected (with either an
+ * {@link Iterator} or an {@link Iterable}).
+ * 
+ * @param {any} E The type of element that this AbstractIterator intends to iterate over.
+ * @param {any} U The type of the value that will be returned in the case that this AbstractIterator's content has been
+ * exhausted. Can be set to 'void' in the case that this AbstractIterator has infinite content. Defaults to `undefined`.
+ * 
+ * @author Trevor Sears <trevor@trevorsears.com>
+ * @version v1.0.0
  * @since v0.1.0
  */
-export abstract class AbstractIterator<E> extends AbstractIterable<E> implements JSDSLIterator<E> {
+export abstract class AbstractIterator<E, U = undefined> extends AbstractIterable<E, U> implements Iterator<E, U> {
 
 	/**
 	 * Returns true if a call to {@link #next} would return a valid and meaningful result after calling this method.
@@ -24,25 +51,23 @@ export abstract class AbstractIterator<E> extends AbstractIterable<E> implements
 	 * present in the underlying structure versus the undefined value that is returned from {@link #next} when all other
 	 * valid results are exhausted.
 	 *
-	 * @return true if a call to {@link #next} would return a valid and meaningful result.
+	 * @return {boolean} true if a call to {@link #next} would return a valid and meaningful result.
 	 */
 	public abstract hasNext(): boolean;
 
 	/**
-	 * Returns the next element this AbstractIterator has to iterate over, over undefined if there are no more valid
-	 * elements to return.
+	 * Returns the next element this AbstractIterator has to iterate over.
 	 *
-	 * @return The next element this AbstractIterator has to iterate over, over undefined if there are no more valid
-	 * elements to return.
+	 * @return {E | U} The next element this AbstractIterator has to iterate over.
 	 */
-	public abstract next(): E | undefined;
+	public abstract next(): E | U;
 
 	/**
 	 * Performs the specified action for all of the remaining elements in this AbstractIterator.
 	 *
-	 * @param callback The action to perform on the remaining elements of this AbstractIterator.
+	 * @param {(element: E) => any} callback The action to perform on the remaining elements of this AbstractIterator.
 	 */
-	public forEach(callback: (element: E) => void): void {
+	public forEachRemaining(callback: (element: E) => any): void {
 
 		for (let element of this) callback(element);
 
@@ -54,9 +79,9 @@ export abstract class AbstractIterator<E> extends AbstractIterable<E> implements
 	 * Note if this method is not overridden in implementing child classes, the `#remove` method will throw an error,
 	 * with a warning that the method is not supported for the current implementation.
 	 *
-	 * @return The last element returned by the {@link #next} method.
+	 * @return {E | U} The last element returned by the {@link #next} method.
 	 */
-	public remove(): E | undefined {
+	public remove(): E | U {
 
 		throw new Error("ERR | #remove operation is not supported for this implementation of AbstractIterator.");
 
@@ -66,8 +91,11 @@ export abstract class AbstractIterator<E> extends AbstractIterable<E> implements
 	 * Resets this AbstractIterator back to it's initial position, readying it to iterate over the underlying collection
 	 * from the 'beginning' again.
 	 * 
-	 * Note if this method is not overridden in implementing child classes, the `#reset` method will throw an error,
+	 * Note: If this method is not overridden in implementing child classes, the `#reset` method will throw an error,
 	 * with a warning that the method is not supported for the current implementation.
+	 *
+	 * Note: This does not/should not modify the underlying data structure, meaning that any modifications to the
+	 * underlying structure will not be/should not be 'undone' by calling this method.
 	 */
 	public reset(): void {
 
@@ -76,56 +104,17 @@ export abstract class AbstractIterator<E> extends AbstractIterable<E> implements
 	}
 
 	/**
-	 * Returns an Iterator over the contents of this AbstractIterator.
+	 * Returns an {@link Iterator} over the contents of this AbstractIterator.
 	 * 
-	 * Because of the fact that this class is in-and-of-itself an Iterator, this method simply returns 'this'. This is
-	 * simply a formality so that this class will conform to the {@link Iterable} interface.
+	 * Because of the fact that this class is in-and-of-itself an {@link Iterator}, this method simply returns 'this'.
+	 * This is simply a formality so that this class will conform to the {@link Iterable} interface.
 	 * 
-	 * @return An Iterator over the contents of this AbstractIterator.
+	 * @return {Iterator<E, U>} An {@link Iterator} over the contents of this AbstractIterator.
 	 */
-	public iterator(): JSDSLIterator<E> {
+	public iterator(): Iterator<E, U> {
 
 		return this;
 
 	}
 
-	/**
-	 * This method is simply an ease-of-understanding alias method for the [Symbol.iterator] method.
-	 *
-	 * @return An instance of an IterableIterator.
-	 * @see AbstractIterator#[Symbol.iterator]
-	 */
-	public getIterableIterator(): IterableIterator<E> {
-		
-		return new class implements IterableIterator<E> {
-			
-			private iterator: AbstractIterator<E>;
-			
-			public constructor(iterator: AbstractIterator<E>) {
-				
-				this.iterator = iterator;
-				
-			}
-			
-			public [Symbol.iterator](): IterableIterator<E> {
-				
-				return this;
-				
-			}
-			
-			public next(): IteratorResult<E> {
-				
-				return {
-					
-					done: !this.iterator.hasNext(),
-					value: this.iterator.next() as E
-					
-				};
-				
-			}
-			
-		}(this);
-		
-	}
-	
-}
+}

ts/iterable.ts

@@ -1,33 +1,55 @@
 /*
- *	Created by Trevor Sears <trevorsears.main@gmail.com>.
- *	7:41 PM -- October 06th, 2019.
- *	Project: @jsdsl/iterator
+ * Created by Trevor Sears <trevor@trevorsears.com> (https://trevorsears.com/).
+ * 3:43 PM -- August 31st, 2021.
+ * Project: @jsdsl/iterator
+ * 
+ * @jsdsl/iterator - A collection of classes that allow iteration over a predefined collection of elements.
+ * Copyright (C) 2021 Trevor Sears
+ * 
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { Iterator as JSDSLIterator } from "./iterator";
+import { Iterator } from "./iterator";
 
 /**
- * An interface representing some type that can be iterated over via a {@link Iterator}.
+ * An interface representing some type that can be iterated over via an {@link Iterator}.
+ *
+ * @param {any} E The type of element that this Iterable intends to iterate over.
+ * @param {any} U The type of the value that will be returned in the case that this Iterable's content has been
+ * exhausted. Can be set to 'void' in the case that this Iterable has infinite content. Defaults to `undefined`.
  * 
- * @author Trevor Sears <trevorsears.main@gmail.com>
- * @version v0.1.0
+ * @author Trevor Sears <trevor@trevorsears.com>
+ * @version v1.0.0
  * @since v0.1.0
  */
-export interface Iterable<E> {
+export interface Iterable<E, U = undefined> {
 
 	/**
-	 * Returns an iterator over the element contents of this Iterable.
+	 * Returns an iterator over the contents of this Iterable.
 	 * 
-	 * @return An iterator over the element contents of this Iterable.
+	 * @return {Iterator<E, U>} An iterator over the contents of this Iterable.
 	 */
-	iterator(): JSDSLIterator<E>;
+	iterator(): Iterator<E, U>;
 
 	/**
-	 * Returns an instance of an IterableIterator that allows 'this' to be iterable using the baked-in 'for...of'
-	 * syntax, rather than more verbose iteration (i.e. using a 'while' loop).
+	 * Returns an instance of an IterableIterator.
+	 * 
+	 * The presence of this method allows 'this' to be iterable using the baked-in 'for...of' syntax, rather than more
+	 * verbose iteration (i.e. using a 'while' loop).
 	 *
-	 * @return An instance of an IterableIterator.
+	 * @return {IterableIterator<E>} An instance of an IterableIterator.
 	 */
 	[Symbol.iterator](): IterableIterator<E>;
 
-}
+}