feat(collection): added is method

Author: nandi95

docs/helpers/collection.md

@@ -71,6 +71,20 @@ numCollection.shuffle(); // Collection[3, 1, 4, 2, 5]
 numCollection.shuffle(); // Collection[2, 5, 1, 4, 3]
 ```
 
+#### is
+
+The `is` method determines if the collection is equal to the given collection. It uses deep equality to ensure every element in the collection is equal to the given collection in the same order.
+
+```js
+import { Collection } from '@upfrontjs/framework';
+
+const collection = new Collection([1, 2, 3, 4, 5]);
+collection.is(collection); // true
+collection.is(new Collection([1, 2, 3, 4, 5])); // true
+collection.is(collection.slice(0, 1)); // false
+(new Collection([{ id: 1 }])).is(new Collection([{ id: 2 }])); // false
+```
+
 #### isEmpty
 
 The `isEmpty` method determines whether the collection is empty or not.

src/Support/Collection.ts

@@ -174,14 +174,33 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
      * {@link https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm|Durstenfeld algorithm}.
      */
     public shuffle(): this {
+        if (this.length <= 1) {
+            return this._newInstance(this.toArray());
+        }
+
         const items = this.toArray();
 
         for (let i = items.length - 1; i > 0; i--) {
             const j = Math.floor(Math.random() * (i + 1));
             [items[i], items[j]] = [items[j]!, items[i]!];
         }
 
-        return this._newInstance(items);
+        const result = this._newInstance(items);
+
+        return this.is(result) ? this.shuffle() : result;
+    }
+
+    /**
+     * Check that the collection the same as the given one.
+     *
+     * @param value
+     *
+     * @return {this}
+     */
+    public is(value: unknown): value is this {
+        return value instanceof this.constructor &&
+            (value as Collection<any>).length === this.length &&
+            this.every((item, index) => isEqual(item, (value as Collection<any>)[index]));
     }
 
     /**
@@ -725,10 +744,10 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
      *
      * @throws {Error}
      */
-    public pluck<Keys extends (Readonly<keyof T> | keyof T)[]>(
+    public pluck<Keys extends (Readonly<keyof T>  )[]>(
         properties: Keys
     ): Collection<Pick<T, Keys[number]>>;
-    public pluck<Keys extends Readonly<keyof T> | keyof T>(
+    public pluck<Keys extends Readonly<keyof T>  >(
         properties: Keys
     ): Collection<Pick<T, Keys>>;
     public pluck<V>(properties: MaybeArray<string>): Collection<V>;

tests/Support/Collection.test.ts

@@ -138,6 +138,20 @@ describe('Collection', () => {
         });
     });
 
+    describe('is()', () => {
+        const elements = [1, 2, 3, 4, 5];
+
+        beforeEach(() => {
+            collection = new Collection(elements);
+        });
+
+        it('should assert if the collection is equal to another collection', () => {
+            expect(collection.is(new Collection(elements))).toBe(true);
+            expect(collection.is(collection)).toBe(true);
+            expect(collection.is(collection.slice(0, 1))).toBe(false);
+        });
+    });
+
     describe('isEmpty()', () => {
         const elements = [1, 2, 3, 4, 5];