{"id":23011796,"url":"https://github.com/justinkunz/arrayusa","last_synced_at":"2025-04-02T17:11:27.930Z","repository":{"id":57386458,"uuid":"436131766","full_name":"justinkunz/ArrayUSA","owner":"justinkunz","description":"npm i unitedstatesofamerica","archived":false,"fork":false,"pushed_at":"2022-05-23T00:14:44.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T04:47:39.663Z","etag":null,"topics":["array","arraymethods","duplicate-detection","node-module","npm","npm-package","shuffle","usa"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/unitedstatesofamerica","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justinkunz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-08T05:49:04.000Z","updated_at":"2023-09-08T18:29:21.000Z","dependencies_parsed_at":"2022-09-05T05:00:25.664Z","dependency_job_id":null,"html_url":"https://github.com/justinkunz/ArrayUSA","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinkunz%2FArrayUSA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinkunz%2FArrayUSA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinkunz%2FArrayUSA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinkunz%2FArrayUSA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justinkunz","download_url":"https://codeload.github.com/justinkunz/ArrayUSA/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246856675,"owners_count":20844974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["array","arraymethods","duplicate-detection","node-module","npm","npm-package","shuffle","usa"],"created_at":"2024-12-15T10:11:11.505Z","updated_at":"2025-04-02T17:11:27.881Z","avatar_url":"https://github.com/justinkunz.png","language":"JavaScript","readme":"# USA Array 🇺🇸\n\n_Dumb name, useful package_\n\nA lightweight dependancy free module to enhance JavaScript's array functionality.\n\n```\nnpm i unitedstatesofamerica\n```\n\n## Creating a New Array 🇺🇸\n\nImport the wrapper from the module to use the extended methods without exposing the methods to standard arrays\n\n```js\nconst usa = require('unitedstatesofamerica');\n\n// Wrap array in wrapper\nconst choices = usa([10, 20, 30, 40, 50]);\n\n// Access custom array methods\nchoices.shuffle(); // [30, 50, 10, 40, 20]\n```\n\nTo create a new iterable USA Array of a set length without specifying the values contained, use the `.withLength(n)` method of the USA Array module.\n\n```js\nconst usa = require('unitedstatesofamerica');\n\n// Using .withLength() to create an iterable array with a length of 5\nconst arr = usa.withLength(5); // Expected: [undefined, undefined, undefined, undefined, undefined]\n\n// Able to access standard array methods\n// Set each item in the array to a random value between 1 and 3\nconst randomValues = arr.map(() =\u003e Math.floor(Math.random() * 3) + 1);\n\nconsole.log(randomValues); // Example: [ 3, 1, 2, 1, 2 ]\n\n// Also able to access Array USA methods\nrandomValues.countOf(1); // Expected: 2\n```\n\n## Extending Prototypes 🇺🇸\n\nOptionally, invoke the `.exposeProtos()` method to expose all arrays to the extended methods.\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst choices = [10, 20, 30, 40, 50];\n\n// Access custom array methods\nchoices.shuffle(); // [30, 50, 10, 40, 20]\n```\n\n## Chaining 🇺🇸\n\nAll Array USA methods that return arrays will return a new instance of Array USA, so standard JS Array methods, as well as Array USA methods can be chained.\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst grades = ['80', '60', '76', '100', '58', '96', '92', '62', '78', '84'];\n\nconst sortedPassingGrades = grades\n  .toNum() // ARRAY USA METHOD\n  .filter((score) =\u003e score \u003e 72) // STANDARD ARRAY METHOD\n  .descending(); // ARRAY USA METHOD\n\nconsole.log(sortedPassingGrades); // Expected: [100, 96, 92, 84, 80, 78, 76]\n```\n\n## Array USA Methods 🇺🇸\n\n##### Useful Methods 🇺🇸\n\n- [Shuffle](#shuffle)\n- [Batch](#batch)\n- [Replace](#replace)\n- [Is Empty](#is-empty)\n- [Last](#last)\n\n##### Duplicate Management 🇺🇸\n\n- [Without Duplicates](#without-duplicates)\n- [Duplicates](#duplicates)\n\n##### Copies 🇺🇸\n\n- [Copy](#copy)\n- [Deep Copy](#deep-copy)\n\n##### Random 🇺🇸\n\n- [Random](#random)\n- [Random Index](#random-index)\n\n##### Counts 🇺🇸\n\n- [Count Of](#count-of)\n- [Count If](#count-if)\n\n##### Sorting 🇺🇸\n\n- [Ascending](#ascending)\n- [Descending](#descending)\n\n##### Querying 🇺🇸\n\n- [Partial Match](#partial-match)\n- [Partial Match Index](#partial-match-index)\n\n##### Math 🇺🇸\n\n- [Sum](#sum)\n- [Difference](#difference)\n- [Product](#product)\n- [Quotient](#quotient)\n- [Mean](#mean)\n- [Average](#average)\n- [Median](#median)\n- [Mode](#mode)\n\n##### Type Management 🇺🇸\n\n- [Filter Type](#filter-type)\n- [Types](#types)\n- [To Array](#to-array)\n- [To Str](#to-str)\n- [To Num](#to-num)\n\n##### Filtering 🇺🇸\n\n- [Even Indexes](#even-indexes)\n- [Odd Indexes](#odd-indexes)\n- [Without Null Values](#without-null-values)\n- [Without Falsy Values](#without-falsy-values)\n\n##### Comparing 🇺🇸\n\n- [Assert](#assert)\n\n##### Conversion 🇺🇸\n\n- [To Object](#to-object)\n\n### Shuffle\n\n`.shuffle()` will randomize the order of an array using the [Fisher–Yates shuffle Algorithm](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle)\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst options = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];\nconst unshuffled = usa(options); // Use the spread operator to pass in an existing array\nconst shuffled = unshuffled.shuffle(); // Expected: array in randomized order, like [8,3,4,2,10,5,1,9,6,7]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst unshuffled = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];\nconst shuffled = unshuffled.shuffle(); // Expected: array in randomized order, like [8,3,4,2,10,5,1,9,6,7]\n```\n\n### Without Duplicates\n\n`.withoutDuplicates()` will return a new array without duplicate items\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst users = usa(['Justin', 'Justin', 'Jack', 'Amanda', 'Mary', 'Amanda']); // Pass values directly into the wrapper\nconst uniqueUsers = users.withoutDuplicates(); // Expected: [\"Justin\", \"Jack\", \"Amanda\", \"Mary\"]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst users = ['Justin', 'Justin', 'Jack', 'Amanda', 'Mary', 'Amanda'];\nconst uniqueUsers = users.withoutDuplicates(); // Expected: [\"Justin\", \"Jack\", \"Amanda\", \"Mary\"]\n```\n\n### Duplicates\n\n`.duplicates()` filters an array to include only items whose values appear more than once in the array.\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst logins = usa(['Justin', 'Justin', 'Jack', 'Amanda', 'Mary', 'Amanda']);\nconst duplicateLogins = logins.duplicates(); // Expected: [\"Justin\", \"Amanda\"]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst logins = ['Justin', 'Justin', 'Jack', 'Amanda', 'Mary', 'Amanda'];\nconst duplicateLogins = logins.duplicates(); // Expected: [\"Justin\", \"Amanda\"]\n```\n\n### Batch\n\n`.batch(limit)` will batch an array's elements into several nested arrays of a specified length.\n\n##### Parameters\n\n- `limit` _(Integer)_ - Length of batch\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst unbatched = ['Justin', 'Amanda', 'Mary', 'Kelly', 'Jonathan', 'Tom'];\nconst batched = usa(unbatched).batch(2); // Expected: [[\"Justin\", \"Amanda\"], [ \"Mary\", \"Kelly\"], [\"Jonathan\", \"Tom\"]]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst unbatched = ['Justin', 'Amanda', 'Mary', 'Kelly', 'Jonathan', 'Tom'];\nconst batched = unbatched.batch(2); // Expected: [[\"Justin\", \"Amanda\"], [ \"Mary\", \"Kelly\"], [\"Jonathan\", \"Tom\"]]\n```\n\n### Copy\n\n`.copy()` will create a [Shallow Copy](https://we-are.bookmyshow.com/understanding-deep-and-shallow-copy-in-javascript-13438bad941c) of an array\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst words = usa(['foo', 'bar', 'baz']);\nconst wordsCopy = words.copy(); // Expected: [\"foo\", \"bar\", \"baz\"]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst words = ['foo', 'bar', 'baz'];\nconst wordsCopy = words.copy(); // Expected: [\"foo\", \"bar\", \"baz\"]\n```\n\n### Deep Copy\n\n`.deepCopy()` will make a [Deep Copy](https://flaviocopes.com/how-to-clone-javascript-object/#deep-copy-vs-shallow-copy) of an array. This means objects or nested arrays will be replaced with replicated values, without referencing the original array. Changes can be made of the copied array without changing the original array.\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst original = usa([\n  { foo: 'bar', foobar: ['foo', 'bar'] },\n  { bar: 'foo', barfoo: ['bar', 'foo'] },\n  { foobar: ['foo', 'bar'] },\n  30,\n  20,\n  'Why does this array have so many types',\n  Symbol(),\n  'Oh yeah, to show you how to it can make a deep copy of any type',\n]);\n\nconst copied = original.deepCopy(); // Makes a deep copy\n\n// Object reference comparison\ncopied[0].foo = 'baz';\n\nconsole.log(original[0].foo === copied[0].foo); // Expected: false\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst original = [\n  { foo: 'bar', foobar: ['foo', 'bar'] },\n  { bar: 'foo', barfoo: ['bar', 'foo'] },\n  { foobar: ['foo', 'bar'] },\n  30,\n  20,\n  'Why does this array have so many types',\n  Symbol(),\n  'Oh yeah, to show you how to it can make a deep copy of any type',\n];\n\nconst copied = original.deepCopy(); // Makes a deep copy\n\n// Object reference comparison\ncopied[0].foo = 'baz';\n\nconsole.log(original[0].foo === copied[0].foo); // Expected: false\n```\n\n### Random\n\n`.random()` will return a random item in the array\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst words = usa(['foo', 'bar', 'baz']);\nwords.random(); // Expected Example: \"bar\"\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst words = ['foo', 'bar', 'baz'];\nwords.random(); // Expected Example: \"bar\"\n```\n\n### Random Index\n\n`.randomIndex()` returns a random index in the array\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst words = usa(['foo', 'bar', 'baz']);\nwords.randomIndex(); // Expected Example: 2\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst words = ['foo', 'bar', 'baz'];\nwords.randomIndex(); // Expected Example: 2\n```\n\n### Count Of\n\n`.countOf(val)` will return a count of all items in an array matching a specified value.\n\n##### Parameters\n\n- `val` _(any)_ - Value to match\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst words = usa(['foo', 'bar', 'foo', 'foo', 'baz']);\nconst fooCount = words.countOf('foo'); // Expected: 3\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst words = ['foo', 'bar', 'foo', 'foo', 'baz'];\nconst fooCount = words.countOf('foo'); // Expected: 3\n```\n\n### Count If\n\n`.countIf(condition)` will return a count of all items in an array that when passed into a callback function, return true\n\n##### Parameters\n\n- `condition` _(Function)_ - Callback function. For checking condition, takes in 3 parameters\n  - `item` - _(any)_ Item in the array\n  - `index` - **Optional** _(Integer)_ - Current index in the array\n  - `arr` - **Optional** _(Array)_ - Current array\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst grades = usa([99, 93, 60, 70, 100, 80, 78, 100, 98, 94]);\nconst over90 = grades.countIf((grade) =\u003e grade \u003e= 90); // Expected: 6\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst grades = [99, 93, 60, 70, 100, 80, 78, 100, 98, 94];\nconst over90 = grades.countIf((grade) =\u003e grade \u003e= 90); // Expected: 6\n```\n\n### Last\n\n`.last()` returns the last item in the array\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst users = usa(['Jack', 'Jill', 'Bob', 'Joe']);\nconst lastUser = users.last(); // Expected: Joe\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst users = ['Jack', 'Jill', 'Bob', 'Joe'];\nconst lastUser = users.last(); // Expected: Joe\n```\n\n### Ascending\n\n`.ascending()` sorts the array in ascending order\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst grades = usa([99, 93, 60, 70, 100, 80, 78, 100, 98, 94]);\nconst worstToBest = grades.ascending(); // Expected: [60, 70, 78, 80, 93,94, 98, 99, 100, 100]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst grades = [99, 93, 60, 70, 100, 80, 78, 100, 98, 94];\nconst worstToBest = grades.ascending(); // Expected: [60, 70, 78, 80, 93,94, 98, 99, 100, 100]\n```\n\n### Descending\n\n`.descending()` sorts the array in descending order\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst grades = usa([99, 93, 60, 70, 100, 80, 78, 100, 98, 94]);\nconst bestToWorst = grades.descending(); // Expected: [100, 100, 99, 98, 94, 93, 80, 78, 70, 60]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst grades = [99, 93, 60, 70, 100, 80, 78, 100, 98, 94];\nconst bestToWorst = grades.descending(); // Expected: [100, 100, 99, 98, 94, 93, 80, 78, 70, 60]\n```\n\n### Is Empty\n\n`.isEmpty()` is a simple method that returns true if the specified array's length is 0.\n\n##### Example\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr1 = usa([]);\nconst arr2 = usa(['foo', 'bar', 'baz']);\n\nconsole.log(arr1.isEmpty()); // Expected: true\nconsole.log(arr2.isEmpty()); // Expected: false\n\narr1.push('foobar');\n\nconsole.log(arr1.isEmpty()); // Expected: false\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst arr1 = [];\nconst arr2 = ['foo', 'bar', 'baz'];\n\nconsole.log(arr1.isEmpty()); // Expected: true\nconsole.log(arr2.isEmpty()); // Expected: false\n```\n\n### Partial Match\n\n`.partialMatch(obj)` finds the first item matching the key/value pairs of the object passed in.\n\n##### Parameters\n\n- `obj` _(Object)_ - Object containing key/value pairs of array item to find\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst users = usa([\n  {\n    firstName: 'Jon',\n    lastName: 'Smith',\n    email: 'jon.smith@gmail.com',\n  },\n  {\n    firstName: 'Jane',\n    lastName: 'Doe',\n    email: 'jdoe@ymail.com',\n  },\n  {\n    firstName: 'Elon',\n    lastName: 'Musk',\n    email: 'elon@tesla.com',\n  },\n]);\n\nconst person = users.partialMatch({ email: 'jdoe@ymail.com' });\n// Expected:\n//  {\n//    firstName: \"Jane\",\n//    lastName: \"Doe\",\n//    email: \"jdoe@ymail.com\",\n//  },\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst users = [\n  {\n    firstName: 'Jon',\n    lastName: 'Smith',\n    email: 'jon.smith@gmail.com',\n  },\n  {\n    firstName: 'Jane',\n    lastName: 'Doe',\n    email: 'jdoe@ymail.com',\n  },\n  {\n    firstName: 'Elon',\n    lastName: 'Musk',\n    email: 'elon@tesla.com',\n  },\n];\n\nconst person = users.partialMatch({ email: 'jdoe@ymail.com' });\n// Expected:\n//  {\n//    firstName: \"Jane\",\n//    lastName: \"Doe\",\n//    email: \"jdoe@ymail.com\",\n//  },\n```\n\n### Partial Match Index\n\n`.partialMatch(obj)` finds the first index matching the key/value pairs of the object passed in.\n\n##### Parameters\n\n- `obj` _(Object)_ - Object containing key/value pairs of array item to find\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst users = usa([\n  {\n    firstName: 'Jon',\n    lastName: 'Smith',\n    email: 'jon.smith@gmail.com',\n  },\n  {\n    firstName: 'Jane',\n    lastName: 'Doe',\n    email: 'jdoe@ymail.com',\n  },\n  {\n    firstName: 'Elon',\n    lastName: 'Musk',\n    email: 'elon@tesla.com',\n  },\n]);\n\nconst person = users.partialMatchIndex({ email: 'jdoe@ymail.com' }); // Expected: 1\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst users = [\n  {\n    firstName: 'Jon',\n    lastName: 'Smith',\n    email: 'jon.smith@gmail.com',\n  },\n  {\n    firstName: 'Jane',\n    lastName: 'Doe',\n    email: 'jdoe@ymail.com',\n  },\n  {\n    firstName: 'Elon',\n    lastName: 'Musk',\n    email: 'elon@tesla.com',\n  },\n];\n\nconst person = users.partialMatchIndex({ email: 'jdoe@ymail.com' }); // Expected: 1\n```\n\n### Without Nullish Values\n\n`.withoutNullishValues()` will return a new array without nullish values (`null` and `undefined`)\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr1 = [3, 4, 'foo', 'bar', null, 'baz', false, 'foobar', NaN, undefined, ''];\n\nconst cleaned = usa(arr1).withoutNullishValues(); // Expected: [ 3, 4, 'foo', 'bar', 'baz', false, 'foobar', NaN ]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst arr1 = [3, 4, 'foo', 'bar', null, 'baz', false, 'foobar', NaN, undefined, ''];\n\nconst cleaned = arr1.withoutNullishValues(); // Expected: [ 3, 4, 'foo', 'bar', 'baz', false, 'foobar', NaN ]\n```\n\n### Without Falsy Values\n\n`.withoutFalsyValues()` will return a new array without any falsy values from the array\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr1 = [3, 4, 'foo', 'bar', null, 'baz', false, 'foobar', NaN, undefined, ''];\n\nconst cleaned = usa(arr1).withoutFalsyValues(); // Expected: [ 3, 4, 'foo', 'bar', 'baz', 'foobar']\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst arr1 = [3, 4, 'foo', 'bar', null, 'baz', false, 'foobar', NaN, undefined, ''];\n\nconst cleaned = arr1.withoutFalsyValues(); // Expected: [ 3, 4, 'foo', 'bar', 'baz', 'foobar']\n```\n\n### Sum\n\n`.sum()` returns the sum of all items in a numerical array.\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst nums = usa([10, 20, 30]);\nnums.sum(); // Expected: 60\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst nums = [10, 20, 30];\nnums.sum(); // Expected: 60\n```\n\n### Difference\n\n`.difference()` returns the difference of all items in a numerical array.\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst nums = usa([10, 20, 30]);\nnums.difference(); // Expected: -40\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst nums = [10, 20, 30];\nnums.difference(); // Expected: -40\n```\n\n### Product\n\n`.product()` returns the product of all items in a numerical array.\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst nums = usa([10, 20, 30]);\nnums.product(); // Expected: 6000\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst nums = [10, 20, 30];\nnums.product(); // Expected: 6000\n```\n\n### Quotient\n\n`.quotient()` returns the quotient of all items in a numerical array.\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst nums = usa([10, 20, 30]);\nnums.quotient(); // Expected: 0.016666666666666666\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst nums = [10, 20, 30];\nnums.quotient(); // Expected: 0.016666666666666666\n```\n\n### Mean\n\n`.mean()` returns the average for an array. _Note: This will return NaN if all items in an array are not numbers_\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst projectGrades = usa([90, 100, 80, 100, 100]);\nconst averageGrage = projectGrades.average(); // Expected: 94\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst projectGrades = [90, 100, 80, 100, 100];\nconst averageGrage = projectGrades.average(); // Expected: 94\n```\n\n### Average\n\n`.average()` is an alternate term for `.mean()`\n\n### Median\n\n`.median()` returns the median of all items in the array\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst nums = usa([10, 20, 30, 50, 100]);\nnums.median(); // Expected: 30\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst nums = [10, 20, 30, 50, 100];\nnums.median(); // Expected: 30\n```\n\n### Mode\n\n`.mode()` returns the mode of the array\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst nums = usa([10, 20, 30, 50, 100]);\nnums.mode(); // Expected: 20\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst nums = [10, 20, 20, 30, 50, 100];\nnums.mode(); // Expected: 20\n```\n\n### Replace\n\n`.replace()` replaces all occurances of a specified value with a new value.\n\n##### Parameters\n\n- `oldVal` _(Any)_ - Value to replace\n- `newVal` _(Any)_ - Replacement value\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr = usa(['foo', 'bar', 'foobar', 'bar', 'foo']);\nconst noFoo = arr.replace('foo', 'baz'); // Expected: [\"baz\", \"bar\", \"foobar\", \"bar\", \"baz\"]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst arr = ['foo', 'bar', 'foobar', 'bar', 'foo'];\nconst noFoo = arr.replace('foo', 'baz'); // Expected: [\"baz\", \"bar\", \"foobar\", \"bar\", \"baz\"]\n```\n\n### Filter Type\n\n`.filterType()` filters an array to only a specified type\n\n##### Parameters\n\n- `type` _(String)_ - String representing JS type\n\n**Possible Types**\n\n- `\"string\"`\n- `\"number\"`\n- `\"boolean\"`\n- `\"undefined\"`\n- `\"symbol\"`\n- `\"function\"`\n- `\"object\"` - Returns all JS object types _(objects, arrays, functions, null)_\n- `\"array\"` - Returns only nested arrays\n- `\"null\"` - Returns only `null` values\n- `\"objectOnly\"` - Returns only objects without returning arrays\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr = [1, 4, 't', ['nested', 8], { foo: 'bar' }, { baz: false }, [1, 2, 3], true, ''];\nconst mixed = usa(arr); // Spread syntax can be used to convert an existing array\n\n// Only strings\nconst strOnly = mixed.filterType('string'); // Expected: [\"t\", \"\"]\n\n// Only arrays\nconst nestedArrsOnly = mixed.filterType('array'); // [[\"nested\", 8], [1,2,3]]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst mixed = [1, 4, 't', ['nested', 8], { foo: 'bar' }, { baz: false }, [1, 2, 3], true, ''];\n\n// Only strings\nconst strOnly = mixed.filterType('string'); // Expected: [\"t\", \"\"]\n\n// Only arrays\nconst nestedArrsOnly = mixed.filterType('array'); // [[\"nested\", 8], [1,2,3]]\n```\n\n### Types\n\n`.types()` returns an array of the target array's types.\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst mixed = usa([1, 4, 't', true, '']);\nconst types = mixed.types(); // Expected: [\"number\", \"number\", \"string\", \"boolean\", \"string\"]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst mixed = [1, 4, 't', true, ''];\nconst types = mixed.types(); // Expected: [\"number\", \"number\", \"string\", \"boolean\", \"string\"]\n```\n\n### To Array\n\n`.toArray()` returns your ArrayUSA array as a standard JavaScript array;\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr = [5, 1, 2, 2, 5, 3, 3, 4, 5];\nconst noDuplicates = usa(arr)\n  .withoutDuplicates() // Remove duplicates\n  .toArray(); // Convert ArrayUSA array to a standard JavaScript array\n\nnoDuplicates.shuffle(); // ❌ ArrayUSA methods no longer work\n```\n\n### To Str\n\n`.toStr()` returns an array of a string version of all the items in the array. _Note: Conversion is different depending on type. For example, **objects** and **arrays** will be returned stringified._\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr = [1, 4, 't', ['nested', 8], { foo: 'bar' }, { baz: false }, [1, 2, 3], true];\nconst mixed = usa(arr); // Spread syntax can be used to convert an existing array\n\nconst strArr = mixed.toStr(); // ['1','4','t','[\"nested\",8]','{\"foo\":\"bar\"}','{\"baz\":false}','[1,2,3]','true']\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst mixed = [1, 4, 't', ['nested', 8], { foo: 'bar' }, { baz: false }, [1, 2, 3], true];\nconst strArr = mixed.toStr(); // ['1','4','t','[\"nested\",8]','{\"foo\":\"bar\"}','{\"baz\":false}','[1,2,3]','true']\n```\n\n### To Num\n\n`.toNum()` returns a new array with all items converted to numbers.\n\n##### Parameters\n\n`base` - Base to parse numbers to. _(Defaults to 10)_\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr = ['1', 4, '3.2', '7', '19', 0];\nusa(arr).toNum(); // Expected: [1, 4, 3.2, 7, 19, 0]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst arr = ['1', 4, '3.2', '7', '19', 0];\narr.toNum(); // Expected: [1, 4, 3.2, 7, 19, 0]\n```\n\n### Even Indexes\n\n`.evenIndexes()` returns only the _even_ index items in an array\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr = ['foo', 'bar', 'baz', 'foobar'];\nusa(arr).evenIndexes(); // Expected: [\"foo\", \"baz\"]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst arr = ['foo', 'bar', 'baz', 'foobar'];\narr.evenIndexes(); // Expected: [\"foo\", \"baz\"]\n```\n\n### Odd Indexes\n\n`.oddIndexes()` returns only the _odd_ index items in an array\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst arr = ['foo', 'bar', 'baz', 'foobar'];\nusa(arr).oddIndexes(); // Expected: [\"bar\", \"foobar\"]\n```\n\n###### Extending Prototype\n\n```js\nrequire('unitedstatesofamerica').exposeProtos();\n\nconst arr = ['foo', 'bar', 'baz', 'foobar'];\narr.oddIndexes(); // Expected: [\"bar\", \"foobar\"]\n```\n\n### Assert\n\n`.assert()` does a deep compare on an array with any target array - Returning a boolean of if all values and nested values matched.\n\n##### Examples\n\n###### Array USA Wrapper\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst a1 = [{ foo: 'bar', bar: 4, baz: false }, [4, 3, 2, 1], 'f', 0, true, 'i'];\nconst a2 = [{ foo: 'bar', bar: 4, baz: false }, [4, 3, 2, 1], 'f', 0, true, 'i'];\n\nusa(a1).assert(a2); // Expected: true\n\nconst a3 = [{ foo: 'baz', bar: 4, baz: false, t: 4 }, [4, 3, 2, 1], 'j', 1, true, 'i'];\nconst a4 = [{ foo: 'bar', bar: 4, baz: false }, [4, 3, 2, 1], 'f', 0, true, 'i'];\n\nusa(a3).assert(a4); // Expected: false\n```\n\n###### Extending Prototype\n\n```js\nconst usa = require('unitedstatesofamerica').exposeProtos();\n\nconst a1 = [{ foo: 'bar', bar: 4, baz: false }, [4, 3, 2, 1], 'f', 0, true, 'i'];\nconst a2 = [{ foo: 'bar', bar: 4, baz: false }, [4, 3, 2, 1], 'f', 0, true, 'i'];\n\na1.assert(a2); // Expected: true\n\nconst a3 = [{ foo: 'baz', bar: 4, baz: false, t: 4 }, [4, 3, 2, 1], 'j', 1, true, 'i'];\nconst a4 = [{ foo: 'bar', bar: 4, baz: false }, [4, 3, 2, 1], 'f', 0, true, 'i'];\n\na3.assert(a4); // Expected: false\n```\n\n### To Object\n\n`.toObject()` converts an array to an object, with specified keys and values for each item\n\n##### Parameters\n\n- `cb` - **OPTIONAL** - Callback function called for each item in the array. **Must return an object with a `key` key and a `value` key** _Note: Callback function is optional. It is not needed if every item in the array is an object with a `key` key and `value` key._\n  **Callback Parameters**\n  - Array item\n  - Item Index\n  - Array\n\n##### Examples\n\n###### Array USA Wrapper\n\n**Example 1: With Callback Function**\n\n```js\nconst usa = require('unitedstatesofamerica');\n\nconst data = [\n  { id: 'abc123', score: 97 },\n  { id: 'def456', score: 82 },\n  { id: 'hij789', score: 90 },\n  { id: 'klm012', score: 78 },\n];\n\n// Expected: { abc123: 97, def456: 82, hij789: 90, klm012: 78 }\nconst scores = usa(data).toObject((item) =\u003e ({ key: item.id, value: item.score }));\n```\n\n**Example 2: Without Callback Function**\n\n```js\nconst usa = require('unitedstatesofamerica');\n\n// If array is already in [{ key, value }] format\n// No callback function is required to convert to an object\nconst houseAttributes = [\n  { key: 'sqFt', value: 2000 },\n  { key: 'yearBuilt', value: 1998 },\n  { key: 'bedrooms', value: 4 },\n  { key: 'bathrooms', value: 2.5 },\n];\n\n// Expected: { sqFt: 2000, yearBuilt: 1998, bedrooms: 4, bathrooms: 2.5 }\nconst home = usa(houseAttributes).toObject();\n```\n\n###### Extending Prototype\n\n**Example 1: With Callback Function**\n\n```js\nconst usa = require('unitedstatesofamerica').exposeProtos();\n\nconst data = [\n  { id: 'abc123', score: 97 },\n  { id: 'def456', score: 82 },\n  { id: 'hij789', score: 90 },\n  { id: 'klm012', score: 78 },\n];\n\n// Expected: { abc123: 97, def456: 82, hij789: 90, klm012: 78 }\nconst scores = data.toObject((item) =\u003e ({ key: item.id, value: item.score }));\n```\n\n**Example 2: Without Callback Function**\n\n```js\nconst usa = require('unitedstatesofamerica');\n\n// If array is already in [{ key, value }] format\n// No callback function is required to convert to an object\nconst houseAttributes = [\n  { key: 'sqFt', value: 2000 },\n  { key: 'yearBuilt', value: 1998 },\n  { key: 'bedrooms', value: 4 },\n  { key: 'bathrooms', value: 2.5 },\n];\n\n// Expected: { sqFt: 2000, yearBuilt: 1998, bedrooms: 4, bathrooms: 2.5 }\nconst home = houseAttributes.toObject();\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinkunz%2Farrayusa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustinkunz%2Farrayusa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinkunz%2Farrayusa/lists"}