Update descriptions and examples

README.md

@@ -1,24 +1,77 @@
 # Package Sorter
 
-> A function used for monorepos production build.
+> A function sorts a group of packages that depends on each other.
 
 When you have projects depend on each other. You have to build core first, then
-the project depends on it and so on. You probably want this step to be automated
+the project depends on it and, so on. You probably want this step to be automated
 so you can use: `package-sorter(unsortedPackages[], coreDependency)`.
 
-_If `coreDependency` is not passed, `package-sorter` will extract it as `@coreDep/`_
-
 ```bash
 npm install package-sorter
 ```
 
-### Example:
+## API
+
+```js
+/**
+ *
+ * @param {Array} [packages=[]] - packages in workspace.
+ * @param {string} coreDependency - core package that other packages depends on it.
+ *
+ * @returns {Object} result
+ * @returns {Array} result.sorted
+ * @returns {Array} result.unSorted
+ */
+const { sorted, unSorted } = packageSorter(packages, coreDependency);
+```
+
+If `coreDependency` is not passed, `package-sorter` will extract it following
+monorepo naming pattern as: `@coreDep/`
+
+> Why returns `unSorted`?
+> Just in case, packages are missing the main dependency will be added to
+> unSorted. Then you can figure out what's missing before production.
+
+### Example (1) - All Sorted
 
 ```js
 import packageSorter from "package-sorter";
 
-// packages in your monorepo:
+// input packages:
+const pkg0 = {
+  name: "@folo/withcontext",
+  dependencies: {}
+};
+
+const pkg1 = {
+  name: "@folo/values",
+  dependencies: {
+    "@folo/withcontext": "^0.1.5"
+  }
+};
+
+const pkg2 = {
+  name: "@folo/layout",
+  dependencies: {
+    "@folo/values": "^0.1.5"
+  }
+};
+
+const packages = [pkg2, pkg1, pkg0];
 
+// our core dependency in this case is: @folo.
+const { sorted, unSorted } = sortPackages(packages, "@folo");
+
+// sorted: [pkg0, pkg1, pkg2];
+// unSorted: []
+```
+
+### Example (2) - Mixed Packages
+
+```js
+import packageSorter from "package-sorter";
+
+// input packages:
 const pkg0 = {
   name: "@folo/withcontext",
   dependencies: {}
@@ -32,31 +85,49 @@ const pkg1 = {
 };
 
 const pkg2 = {
-  name: "@folo/utils",
+  name: "unrelated",
   dependencies: {}
 };
 
-const pkg3 = {
-  name: "@folo/layout",
+const packages = [pkg2, pkg1, pkg0];
+
+const { sorted } = sortPackages(packages);
+
+// sorted: [pkg2, pkg0, pkg1]
+// unSorted: []
+```
+
+### Example (3) - Some unsorted
+
+```js
+import packageSorter from "package-sorter";
+
+// input packages:
+const pkg0 = {
+  name: "@folo/withcontext",
+  dependencies: {}
+};
+
+const pkg1 = {
+  name: "@folo/values",
   dependencies: {
     "@folo/withcontext": "^0.1.5"
   }
 };
 
-const pkg4 = {
-  name: "@folo/forms",
+const pkg2 = {
+  name: "@folo/unsortable",
   dependencies: {
-    "@folo/layout": "^0.1.4",
-    "@folo/values": "^0.1.4"
+    "@folo/missing": "^0.1.5"
   }
 };
 
-const unsortedPackages = [pkg1, pkg2, pkg3, pkg0, pkg4];
+const packages = [pkg2, pkg1, pkg0];
 
-// our core dependency in this case is: @folo.
-const sorted = sortPackages(unsortedPackages, "@folo");
+const { sorted } = sortPackages(packages);
 
-//=> [pkg2, pkg0, pkg1, pkg4, pkg3]
+// sorted: [pkg0, pkg1]
+// unSorted: [pkg2]
 ```
 
 ## Tests

src/packageSorter.js

@@ -112,12 +112,12 @@ function sort(packages) {
  * Sorting packages. Package with no deps will come first, then package that
  * depending of package that is built. This is essential for monorepo build.
  *
- * @param {Array} packages - packages in workspace.
+ * @param {*} [packages=[]] - packages in workspace.
  * @param {string} coreDependency - core package that other packages depend on.
  *
  * @returns {Object} result
- * @returns {boolean} result.sorted
- * @returns {Object} result.unSorted
+ * @returns {Array} result.sorted
+ * @returns {Array} result.unSorted
  */
 function packageSorter(packages = [], coreDependency) {
   unSorted = [];