{"id":21592943,"url":"https://github.com/jonabrams/arity","last_synced_at":"2025-04-10T23:26:55.489Z","repository":{"id":8667582,"uuid":"10323802","full_name":"JonAbrams/arity","owner":"JonAbrams","description":"Makes sure that JavaScript functions are called with the expected number and/or types of parameters.","archived":false,"fork":false,"pushed_at":"2013-09-07T22:58:04.000Z","size":200,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T19:05:09.461Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","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/JonAbrams.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":"2013-05-27T22:40:41.000Z","updated_at":"2018-10-11T04:47:48.000Z","dependencies_parsed_at":"2022-07-09T20:46:15.413Z","dependency_job_id":null,"html_url":"https://github.com/JonAbrams/arity","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonAbrams%2Farity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonAbrams%2Farity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonAbrams%2Farity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JonAbrams%2Farity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JonAbrams","download_url":"https://codeload.github.com/JonAbrams/arity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248313945,"owners_count":21082947,"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":[],"created_at":"2024-11-24T17:10:35.455Z","updated_at":"2025-04-10T23:26:55.456Z","avatar_url":"https://github.com/JonAbrams.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arity\n\nMakes sure that JavaScript functions are called with the expected number and/or types of parameters.\n\n[![Build Status](https://travis-ci.org/JonAbrams/arity.png?branch=master)](https://travis-ci.org/JonAbrams/arity) [![NPM version](https://badge.fury.io/js/arity.png)](http://badge.fury.io/js/arity)\n\n## Background\n\nJust like in any programming language JavaScript functions take parameters. Unlike many other programming languages, JavaScript does not require functions to be called with the defined number (or types) of parameters.\n\nFor example:\n\n```js\nfunction sum(a, b) {\n  return a + b;\n}\nsum(1, 2); // returns 3\nsum(2); // returns NaN, not too helpful eh?\n```\n\nDepending on the situation, it might be preferred that an error is thrown when the wrong number of parameters are passed in.\n\nA common situation where you might want to enforce this is with a JavaScript library. You may want to make sure that your publically exposed functions are being called in the way you expect. _Arity_ can help users of your library catch errors earlier, and save you support headaches.\n\n## Usage\n\nFirst, [install the library](https://github.com/JonAbrams/arity#installing-for-nodejs).\n\nThen, it's as simple as wrapping your function with `ar`:\n\n```js\nvar sum = ar(function (a, b) {\n  return a + b;\n});\nsum(1, 2); // returns 3\nsum(2); // throws \"Wrong number of parameters. Excpected 2, got 1. Params: a, b.\"\n```\n\nIt's even easier in CoffeeScript (isn't everything?):\n\n```coffee\nsum = ar (a, b) -\u003e a + b\nsum(1, 2) # returns 3\nsum(1, 2, 3) # throws \"Wrong number of parameters. Excpected 2, got 3. Params: a, b.\"\n```\n\nBy default, `ar` will detect the number of parameters your function is expecting an enforce it by throwing an error when it is called with a different number of parameters.\n\n### Variable Number of Parameters\n\nIf you want your function to accept a range of number of parameters (e.g. it can take 2 to 4 parameters), the pass in a min or max value as the 1st and/or 2nd value.\n\nTo specify just a minimum number (note that this is in CoffeeScript, it was too long to write in JS):\n\n```coffee\nsum = ar 2, (nums...) -\u003e nums.reduce (t,s) -\u003e t + s\nsum(1, 5) # Returns 6\nsum(2) # Throws \"Wrong number of parameters. Excpected 2 or more, got 1.\"\n```\n\nTo specify a range:\n\n```coffee\nsum = ar 2, 4, (nums...) -\u003e nums.reduce (t,s) -\u003e t + s\nsum(1, 5) # Returns 6\nsum(2) # Throws \"Wrong number of parameters. Excpected 2..4, got 1.\"\nsum(2, 5, 2, 7, 9) # Throws \"Wrong number of parameters. Excpected 2..4, got 5.\"\n```\n\n### Specifying Parameter Types\n\nIf you want, you can easily enforce the type of variables that are passed into your function.\n\nJust pass in the types as strings into `ar` before passing in your function:\n\n```coffee\nsum = ar \"number\", \"number\", (a, b) -\u003e a + b\nsum(1, '2') # Throws \"Invalid parameter. Expected parameter 1 to be of type 'Number' but got 'String'.\"\n```\n\nIn addition to supporting native JavaScript types like \"number\", \"string\", \"boolean\", \"function\", and \"object\", it also supports user defined types/classes).\n\nExample in JavaScript:\n\n```js\nfunction Lannister(name) {\n  this.name = name;\n}\n\nfunction Stark(name) {\n  this.name = name;\n}\n\nvar lannisterMotto = ar(\"Lannister\", function (person) {\n  return person.name + \" always pays his debts.\";\n});\n\nlannisterMotto( new Lannister(\"Tyrion\") ); // Returns \"Tyrion always pays his debts.\"\nlannisterMotto( new Stark(\"Ned\") ); // Throws \"Invalid parameter. Expected parameter 0 to be of type 'Lannister' but got 'Stark'.\"\n```\n\nExample in CoffeeScript:\n\n```coffee\nclass House\n  constructor: (@name) -\u003e\n\nclass Lannister extends House\nclass Stark extends House\n\nlannisterMotto = ar \"Lannister\", (person) -\u003e\n  \"#{person.name} always pays his debts.\"\n\nlannisterMotto( new Lannister(\"Tyrion\") ); # Returns \"Tyrion always pays his debts.\"\nlannisterMotto( new Stark(\"Ned\") ); # \"Throws Invalid parameter. Expected parameter 0 to be of type 'Lannister' but got 'Stark'.\"\n```\n\n### Enforcing object structure\n\nIn JS, you'll often have a bunch of parameters passed in via an object literal. The contents of these can also be checked for type.\n\nExample in CoffeeScript:\n\n```coffee\n# Example 1\nmagicNumSchema = i: \"number\", r: \"number\"\n# iSum is a function that takes two imaginary numbers and sums them\niSum = ar magicNumSchema, magicNumSchema, (a,b) -\u003e i: a.i + b.i, r: a.r + b.r\nmagic1 = i: 5, r: 3\nmagic2 = i: 2, r: '7'\niSum(magic1, magic2) # Throws an exception since 'magic[r]' is of the wrong type\n\n# Example 2\nmagic1 = i: 5, r: 3, comment: \"This will be ignored since it isn't in magicNumSchema\"\nmagic2 = i: 2, r: 7\niSum(magic1, magic2) # Returns { i: 7, r: 10 }\n```\n\n### Wildcard\n\nIf you want to specify the type that some parameters should be, but don't care about others, you can specify them by passing in `\"*\"`.\n\n```coffee\n# Assign key/value if it doesn't exist\nsafeInserter = (obj, key, value) -\u003e\n  obj[key] = value if key not of obj\nsafeInserter = ar \"object\", \"string\", \"*\", safeInserter\n\nperson = { name: \"Jake\" }\nsafeInserter(person, \"name\", \"Fran\") # Does nothing\nsafeInserter(person, \"age\", 30) # Inserts a new key and value\n```\n\n## Installing for Node.js\n\nFrom the command-line:\n\n    npm install arity\n\nFrom your app:\n\n    var ar = require(\"arity\");\n\n## Installing for the browser\n\nDownload `arity.js` and put it in your `js` folder with your project.\n\nYou can also install it using [bower](https://github.com/bower/bower): `bower install arity`\n\nThen include it in your page like so:\n\n    \u003cscript src=\"js/arity.js\"\u003e\u003c/script\u003e\n\nYou now have access to the `ar` function.\n\n## Tests\n\n    npm install # Installs mocha\n    make test\n\n## Credit\n\nCreated by [Jon Abrams](http://twitter.com/JonathanAbrams).\n\nInspired by the [rethinkDB's implementation](https://github.com/rethinkdb/rethinkdb/blob/next/drivers/javascript/src/base.coffee#L11).\n\nI found out about it from [this blog post](http://andrewberls.com/blog/post/javascript-tricks-enforcing-function-arity) written by Andrew Berls.\n\n## License\n\nThe MIT License (MIT)\n\nCopyright (c) 2013 Jonathan Abrams\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonabrams%2Farity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonabrams%2Farity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonabrams%2Farity/lists"}