Merge pull request #58 from Sykander/async-sort

Async sort

Author: Sykander

README.md

@@ -27,6 +27,7 @@ class AsyncArray extends Array {...}
 * Async Find Index
 * Async For Each
 * Async Map
+* Async Sort
 
 ### [Async Filter](https://github.com/Sykander/iterable-async/wiki/Async-Filter) 
 
@@ -63,6 +64,13 @@ Map an iterable object asynchronously
 async function asyncMap(callback, [thisArg]) {...}
 ```
 
+### [Async Sort](https://github.com/Sykander/iterable-async/wiki/Async-Sort) 
+
+Sort an iterable object asynchronously
+```
+async function asyncSort(callback) {...}
+```
+
 
 ## Development
 

docs/playground.js

@@ -4,5 +4,6 @@ const {
 	asyncFindIndex,
 	asyncFilter,
 	asyncForEach,
-	asyncMap
+	asyncMap,
+	asyncSort
 } = require('iterable-async');

src/async-array.js

@@ -2,10 +2,13 @@ const asyncMap = require('./async-map'),
 	asyncForEach = require('./async-for-each'),
 	asyncFilter = require('./async-filter'),
 	asyncFind = require('./async-find'),
-	asyncFindIndex = require('./async-find-index');
+	asyncFindIndex = require('./async-find-index'),
+	asyncSort = require('./async-sort');
 
 /**
- * Create new constructor for Async Array
+ * Async Array
+ * ===========
+ * Array like object with access to async array methods
  * @type {AsyncArray}
  */
 class AsyncArray extends Array {}
@@ -15,6 +18,7 @@ class AsyncArray extends Array {}
 	(AsyncArray.prototype.asyncFindIndex = asyncFindIndex),
 	(AsyncArray.prototype.asyncFilter = asyncFilter),
 	(AsyncArray.prototype.asyncForEach = asyncForEach),
-	(AsyncArray.prototype.asyncMap = asyncMap);
+	(AsyncArray.prototype.asyncMap = asyncMap),
+	(AsyncArray.prototype.asyncSort = asyncSort);
 
 module.exports = AsyncArray;

src/async-filter.js

@@ -4,6 +4,7 @@ const { mapIterable, filterIterable } = require('./helpers'),
 
 /**
  * Async Filter
+ * ============
  * Filter an iterable object asynchronously and resolve when all callbacks are resolved
  * @async
  * @param {Function} callback - callback(currentValue, index, array)

src/async-find-index.js

@@ -4,6 +4,7 @@ const { mapIterable } = require('./helpers'),
 
 /**
  * Async Find Index
+ * ================
  * Find an item's index in an iterable object asynchronously and resolve when found or all callbacks resolve
  * @async
  * @param {Function} callback - callback(currentValue, index, array)

src/async-find.js

@@ -4,6 +4,7 @@ const { mapIterable } = require('./helpers'),
 
 /**
  * Async Find
+ * ==========
  * Find an item in an iterable object asynchronously and resolve when found or all callbacks resolve
  * @async
  * @param {Function} callback - callback(currentValue, index, array)

src/async-for-each.js

@@ -4,6 +4,7 @@ const { mapIterable } = require('./helpers'),
 
 /**
  * Async For Each
+ * ==============
  * Loop over an iterable object asynchronously and resolve when all callbacks are resolved
  * @async
  * @param {Function} callback - callback(currentValue, index, array)

src/async-map.js

@@ -4,6 +4,7 @@ const { mapIterable } = require('./helpers'),
 
 /**
  * Async Map
+ * =========
  * Map an iterable object asynchronously and resolve when all callbacks are resolved
  * @async
  * @param {Function} callback - callback(currentValue, index, array)

src/async-quick-sort.js

@@ -0,0 +1,38 @@
+const { asyncPartition } = require('./helpers');
+
+/**
+ * Async Quick Sort
+ * ================
+ * Asynchronously sorts an iterable using quick-sort algorithm
+ * @param {Object} iterable
+ * @param {Number} leftIndex
+ * @param {Number} rightIndex
+ * @param {Function} compareFunc
+ */
+module.exports = async function asyncQuickSort(
+	iterable,
+	leftIndex,
+	rightIndex,
+	compareFunc
+) {
+	let index;
+
+	if (iterable.length > 1) {
+		index = await asyncPartition(
+			iterable,
+			leftIndex,
+			rightIndex,
+			compareFunc
+		);
+
+		if (leftIndex < index - 1) {
+			await asyncQuickSort(iterable, leftIndex, index - 1, compareFunc);
+		}
+
+		if (index < rightIndex) {
+			await asyncQuickSort(iterable, index, rightIndex, compareFunc);
+		}
+	}
+
+	return iterable;
+};

src/async-sort.js

@@ -0,0 +1,25 @@
+const { noParam } = require('./constants'),
+	{ validateIsFunction, validateIsIterable } = require('./validation'),
+	asyncQuickSort = require('./async-quick-sort'),
+	{ compareByUnicode } = require('./helpers');
+
+/**
+ * Async Sort
+ * ==========
+ * Asynchronously sorts and an iterable object and resolves when fully sorted
+ * note that the object is sorted in place and no copy is made
+ * @async
+ * @param {Function} [compareFunc] - default is sort by item's unicode value
+ * @return {Object}
+ */
+module.exports = async function asyncSort(compareFunc = noParam) {
+	validateIsIterable(this);
+
+	const compare = compareFunc !== noParam ? compareFunc : compareByUnicode;
+
+	validateIsFunction(compare);
+
+	await asyncQuickSort(this, 0, this.length - 1, compare);
+
+	return this;
+};