chore: add documentation for the diffUsing method

ecrmnn · Mar 21, 2023 · dd8a720 · dd8a720
1 parent 6c3ba5d
commit dd8a720
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -59,6 +59,7 @@ All available methods
 - [diff](#diff)
 - [diffAssoc](#diffassoc)
 - [diffKeys](#diffkeys)
+- [diffUsing](#diffusing)
 - [doesntContain](#doesntcontain)
 - [dump](#dump)
 - [duplicates](#duplicates)
@@ -553,6 +554,30 @@ diff.all();
 // { a: 'a', c: 'c' }
 ```
 
+#### `diffUsing()`
+
+The diffUsing method compares the collection against another collection or a plain array based on its values using a callback. This method will return the values in the original collection that are not present in the given collection:
+
+```js
+const collection = collect([
+    { name: 'Alice', age: 25 },
+    { name: 'Bob', age: 30 },
+    { name: 'Charlie', age: 35 },
+]);
+
+const users = [
+    { name: 'Bob', age: 30 },
+    { name: 'Charlie', age: 35 },
+    { name: 'David', age: 40 },
+];
+
+const diff = collection.diffUsing(users, (a, b) => a.age - b.age);
+
+diff.all();
+
+// [{ name: 'Alice', age: 25 }]
+```
+
 #### `doesntContain()`
 
 The `doesntContain` method determines whether the collection does not contain a given item. You may pass a closure to the `doesntContain` method to determine if an element does not exist in the collection matching a given truth test:
@@ -3330,4 +3355,4 @@ PRs are welcomed to this project, and help is needed in order to keep up with th
 
 ### License
 
-MIT © [Daniel Eckermann](https://danieleckermann.com)
+MIT © [Daniel Eckermann](https://danieleckermann.com)
diff --git a/docs/api/diffUsing.md b/docs/api/diffUsing.md
@@ -0,0 +1,25 @@
+# `diffUsing()`
+
+The diffUsing method compares the collection against another collection or a plain array based on its values using a callback. This method will return the values in the original collection that are not present in the given collection:
+
+```js
+const collection = collect([
+    { name: 'Alice', age: 25 },
+    { name: 'Bob', age: 30 },
+    { name: 'Charlie', age: 35 },
+]);
+
+const users = [
+    { name: 'Bob', age: 30 },
+    { name: 'Charlie', age: 35 },
+    { name: 'David', age: 40 },
+];
+
+const diff = collection.diffUsing(users, (a, b) => a.age - b.age);
+
+diff.all();
+
+// [{ name: 'Alice', age: 25 }]
+```
+
+[View source on GitHub](https://github.com/ecrmnn/collect.js/blob/master/src/methods/diffUsing.js)