@santi100/array-shuffle - npm Package Compare versions

Comparing version 0.0.1 to 0.0.2

CHANGELOG.md

@@ -6,1 +6,11 @@ # Changelog
 - First version!
+
+## Version 0.0.2
+
+- **Added error handling:** Improved the library's robustness by adding error handling mechanisms. The `shuffle` function now validates inputs and provides clear error messages when invalid arguments are provided. This enhancement ensures that the library behaves predictably and gracefully handles various scenarios.
+
+- **Added new TypeScript signatures:** Expanded the library's TypeScript support by introducing additional function signatures with detailed type annotations. This makes it even easier for TypeScript users to integrate the library into their projects and benefit from type safety.
+
+- **Included error cases in the test suite:** Strengthened the library's test suite to cover various error cases, ensuring that the error handling mechanisms are thoroughly tested and reliable.
+
+- **Improved documentation:** Updated the README and API documentation to provide clearer instructions on how to use the `shuffle` function and what algorithm is being used. Users can now quickly understand how to utilize the library and handle time complexity effectively.

cjs/index.d.ts

 /**
  * Shuffles the elements of an array randomly.
  *
- * @param array - The array to be shuffled.
- * @param opts - Optional parameters for shuffling.
- * @param opts.inPlace - If true, shuffles the array in place. Default is false.
+ * @param array The array to be shuffled.
  * @returns The shuffled array.
  */
-declare function shuffle<T = unknown>(array: T[], opts?: {
+declare function shuffle<T = unknown>(array: T[]): T[];
+/**
+ * Shuffles the elements of an array randomly.
+ *
+ * @param array The array to be shuffled.
+ * @param opts Optional parameters for shuffling.
+ * @param opts.inPlace If true, shuffles the array in place. Default is false.
+ * @returns The shuffled array.
+ */
+declare function shuffle<T = unknown>(array: T[], opts: {
     inPlace: boolean;
 }): T[];
 export = shuffle;

cjs/index.js

@@ -11,17 +11,13 @@ "use strict";
 };
-var random_1 = require("@santi100/random-lib/cjs/random");
-/**
- * Shuffles the elements of an array randomly.
- *
- * @param array - The array to be shuffled.
- * @param opts - Optional parameters for shuffling.
- * @param opts.inPlace - If true, shuffles the array in place. Default is false.
- * @returns The shuffled array.
- */
+var random = require("@santi100/random-lib/cjs/random");
+var assertArray = require("@santi100/assertion-lib/cjs/array");
+var assertTypeOf = require("@santi100/assertion-lib/cjs/type-of");
 function shuffle(array, opts) {
     var _a, _b;
     if (opts === void 0) { opts = { inPlace: false }; }
+    assertArray(array, 'array');
+    assertTypeOf(opts.inPlace, 'boolean', 'opts.inPlace');
     if (opts.inPlace) {
         for (var i = array.length - 1; i > 0; i--) {
-            var j = (0, random_1.random)(i + 1);
+            var j = random(i + 1);
             _a = [array[j], array[i]], array[i] = _a[0], array[j] = _a[1]; // Swap elements
@@ -33,3 +29,3 @@ }
     for (var i = shuffledArray.length - 1; i > 0; i--) {
-        var j = (0, random_1.random)(i + 1);
+        var j = random(i + 1);
         _b = [shuffledArray[j], shuffledArray[i]], shuffledArray[i] = _b[0], shuffledArray[j] = _b[1]; // Swap elements
@@ -36,0 +32,0 @@ }

package.json

 {
   "name": "@santi100/array-shuffle",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "main": "cjs/index.js",
@@ -10,3 +10,3 @@ "module": "index.js",
     "@types/jest": "29.5.1",
-    "@typescript-eslint/eslint-plugin": "5.59.7",
+    "@typescript-eslint/eslint-plugin": "5.62.0",
     "@typescript-eslint/parser": "5.59.7",
@@ -16,3 +16,3 @@ "eslint": "^8.39.0",
     "jest": "^29.4.3",
-    "prettier": "2.8.8",
+    "prettier": "3.0.1",
     "remark-cli": "^11.0.0",
@@ -25,3 +25,10 @@ "remark-gfm": "^3.0.1",
   "description": "Santi's Array Shuffling Library: Shuffle it up!",
-  "keywords": ["santi100", "shuffle", "array", "es3", "lightweight", "portable"],
+  "keywords": [
+    "santi100",
+    "shuffle",
+    "array",
+    "es3",
+    "lightweight",
+    "portable"
+  ],
   "repository": {
@@ -50,4 +57,5 @@ "url": "https://github.com/santi100a/array-shuffle",
   "dependencies": {
-    "@santi100/random-lib": "^1.1.6"
+    "@santi100/assertion-lib": "^2.0.1",
+    "@santi100/random-lib": "^1.1.7"
   }
 }

README.md

@@ -26,2 +26,3 @@ # Santi's Array Shuffling Library
 This library exports a function that shuffles the values in any array.
+It is implemented using the [Fisher-Yates shuffle algorithm](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle) to shuffle the array elements.
 
@@ -38,9 +39,18 @@ ## Installation
 
-| Name         | Type      | Description                           | Optional? | Default              |
-| ------------ | --------- | ------------------------------------- | --------- | -------------------- |
-| array        | `T[]`     | The array to be shuffled.             | No        | _N/A_                |
-| opts         | `object`  | Optional parameters for shuffling.    | Yes       | `{ inPlace: false }` |
-| opts.inPlace | `boolean` | If true, shuffles the array in place. | Yes       | `false`              |
-| returns      | `T[]`     | The shuffled array.                   | No        | _N/A_                |
+  | Name         | Type      | Description                           | Optional? | Default              |
+  | ------------ | --------- | ------------------------------------- | --------- | -------------------- |
+  | array        | `T[]`     | The array to be shuffled.             | No        | _N/A_                |
 
+  Returns the shuffled array.
+
+- `function shuffle<T = unknown>(array: T[], opts: { inPlace: boolean; }): T[];`
+
+  | Name         | Type      | Description                           | Optional? | Default              |
+  | ------------ | --------- | ------------------------------------- | --------- | -------------------- |
+  | array        | `T[]`     | The array to be shuffled.             | No        | _N/A_                |
+  | opts         | `object`  | Optional parameters for shuffling.    | Yes       | `{ inPlace: false }` |
+  | opts.inPlace | `boolean` | If true, shuffles the array in place. | Yes       | `false`              |
+
+  Returns the shuffled array.
+
 ## Usage
@@ -47,0 +57,0 @@

src/index.ts

@@ -1,2 +0,4 @@
-import { random } from '@santi100/random-lib/cjs/random';
+import random = require('@santi100/random-lib/cjs/random');
+import assertArray = require('@santi100/assertion-lib/cjs/array');
+import assertTypeOf = require('@santi100/assertion-lib/cjs/type-of');
 
@@ -6,7 +8,18 @@ /**
  * 
- * @param array - The array to be shuffled.
- * @param opts - Optional parameters for shuffling.
- * @param opts.inPlace - If true, shuffles the array in place. Default is false.
+ * @param array The array to be shuffled.
  * @returns The shuffled array.
  */
+function shuffle<T = unknown>(array: T[]): T[];
+
+/**
+ * Shuffles the elements of an array randomly.
+ * 
+ * @param array The array to be shuffled.
+ * @param opts Optional parameters for shuffling.
+ * @param opts.inPlace If true, shuffles the array in place. Default is false.
+ * @returns The shuffled array.
+ */
+function shuffle<T = unknown>(array: T[], opts: { inPlace: boolean; }): T[];
+
+
 function shuffle<T = unknown>(
@@ -16,2 +29,5 @@ array: T[],
 ): T[] {
+	assertArray(array, 'array');
+	assertTypeOf(opts.inPlace, 'boolean', 'opts.inPlace');
+
 	if (opts.inPlace) {
@@ -18,0 +34,0 @@ for (let i = array.length - 1; i > 0; i--) {

tests/main.test.js

 // Generated by CodiumAI
 
 describe('shuffle', () => {
-    const shuffle = require('..');
+	const shuffle = require('..');
 
-    // Tests that shuffle can shuffle an array of numbers
-    it('should shuffle an array of numbers', () => {
-        const array = [1, 2, 3, 4, 5];
-        const shuffledArray = shuffle(array);
-        expect(shuffledArray).not.toEqual(array);
-        expect(shuffledArray.sort()).toEqual(array.sort());
-    });
+	describe('error handling', () => {
+		it('should throw an error if array is not an array', () => {
+			expect(shuffle).toThrow(/must be an Array/);
+			expect(() => shuffle('not an Array')).toThrow(/must be an Array/);
+		});
+		it('should throw an error if opts.inPlace is not boolean', () => {
+			expect(() => shuffle([1, 2, 3, 4], { inPlace: 'not a boolean' })).toThrow(
+				/must be of type "boolean"/
+			);
+		});
+	});
 
-    // Tests that shuffle can shuffle an array of strings
-    it('should shuffle an array of strings', () => {
-        const array = ['apple', 'banana', 'cherry', 'date', 'elderberry'];
-        const shuffledArray = shuffle(array);
-        expect(shuffledArray).not.toEqual(array);
-        expect(shuffledArray.sort()).toEqual(array.sort());
-    });
+	// Tests that shuffle can shuffle an array of numbers
+	it('should shuffle an array of numbers', () => {
+		const array = [1, 2, 3, 4, 5];
+		const shuffledArray = shuffle(array);
+		expect(shuffledArray).not.toEqual(array);
+		expect(shuffledArray.sort()).toEqual(array.sort());
+	});
 
-    // Tests that shuffle can shuffle an array of objects
-    it('should shuffle an array of objects', () => {
-        const array = [
-            { name: 'Alice', age: 25 },
-            { name: 'Bob', age: 30 },
-            { name: 'Charlie', age: 35 },
-            { name: 'David', age: 40 },
-            { name: 'Eve', age: 45 }
-        ];
-        const shuffledArray = shuffle(array);
-        expect(shuffledArray).not.toEqual(array);
-        expect(shuffledArray.sort((a, b) => a.age - b.age)).toEqual(array.sort((a, b) => a.age - b.age));
-    });
+	// Tests that shuffle can shuffle an array of strings
+	it('should shuffle an array of strings', () => {
+		const array = ['apple', 'banana', 'cherry', 'date', 'elderberry'];
+		const shuffledArray = shuffle(array);
+		expect(shuffledArray).not.toEqual(array);
+		expect(shuffledArray.sort()).toEqual(array.sort());
+	});
 
-    // Tests that shuffle can shuffle an empty array
-    it('should return an empty array when given an empty array', () => {
-        const array = [];
-        const shuffledArray = shuffle(array);
-        expect(shuffledArray).toEqual([]);
-    });
+	// Tests that shuffle can shuffle an array of objects
+	it('should shuffle an array of objects', () => {
+		const array = [
+			{ name: 'Alice', age: 25 },
+			{ name: 'Bob', age: 30 },
+			{ name: 'Charlie', age: 35 },
+			{ name: 'David', age: 40 },
+			{ name: 'Eve', age: 45 },
+		];
+		const shuffledArray = shuffle(array);
+		expect(shuffledArray).not.toEqual(array);
+		expect(shuffledArray.sort((a, b) => a.age - b.age)).toEqual(
+			array.sort((a, b) => a.age - b.age)
+		);
+	});
 
-    // Tests that shuffle can shuffle an array with one element
-    it('should return the same array when given an array with one element', () => {
-        const array = [1];
-        const shuffledArray = shuffle(array);
-        expect(shuffledArray).toEqual(array);
-    });
+	// Tests that shuffle can shuffle an empty array
+	it('should return an empty array when given an empty array', () => {
+		const array = [];
+		const shuffledArray = shuffle(array);
+		expect(shuffledArray).toEqual([]);
+	});
 
-    // Tests that shuffle can shuffle an array with duplicate elements
-    it('should shuffle an array with duplicate elements', () => {
-        const array = [1, 2, 2, 3, 3, 3];
-        const shuffledArray = shuffle(array);
-        expect(shuffledArray).not.toEqual(array);
-        expect(shuffledArray.sort()).toEqual(array.sort());
-    });
+	// Tests that shuffle can shuffle an array with one element
+	it('should return the same array when given an array with one element', () => {
+		const array = [1];
+		const shuffledArray = shuffle(array);
+		expect(shuffledArray).toEqual(array);
+	});
+
+	// Tests that shuffle can shuffle an array with duplicate elements
+	it('should shuffle an array with duplicate elements', () => {
+		const array = [1, 2, 2, 3, 3, 3];
+		const shuffledArray = shuffle(array);
+		expect(shuffledArray).not.toEqual(array);
+		expect(shuffledArray.sort()).toEqual(array.sort());
+	});
+
+    // Tests that shuffle can shuffle in place
+    it('should shuffle an array of numbers in place', () => {
+		const array = [1, 2, 3, 4, 5];
+        const previousArray = [...array];
+		shuffle(array, { inPlace: true });
+		expect(previousArray).not.toEqual(array);
+		expect(previousArray.sort()).toEqual(array.sort());
+	});
 });

No alert changes

Improved metrics

Total package byte prevSize

39379

increased by7.68%

Lines of code

304

increased by13.43%

Number of lines in readme file

88

increased by12.82%

Worsened metrics

Dependency count

2

increased by100%

Dependency changes

• + Added@santi100/assertion-lib@^2.0.1

• Updated@santi100/random-lib@^1.1.7