{"id":17749547,"url":"https://github.com/oresoftware/pragmatik","last_synced_at":"2025-10-09T12:44:04.620Z","repository":{"id":95712988,"uuid":"72224977","full_name":"ORESoftware/pragmatik","owner":"ORESoftware","description":"Parse arguments for variadic functions accordingly.","archived":false,"fork":false,"pushed_at":"2018-12-14T07:58:22.000Z","size":102,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-18T16:54:45.397Z","etag":null,"topics":["arguments","dynamic","dynamic-typing","function","nodejs","parse","varargs","variadic"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ORESoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-28T16:43:26.000Z","updated_at":"2018-12-14T07:58:24.000Z","dependencies_parsed_at":"2023-05-21T15:15:38.862Z","dependency_job_id":null,"html_url":"https://github.com/ORESoftware/pragmatik","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ORESoftware/pragmatik","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fpragmatik","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fpragmatik/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fpragmatik/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fpragmatik/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ORESoftware","download_url":"https://codeload.github.com/ORESoftware/pragmatik/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fpragmatik/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263379483,"owners_count":23457850,"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":["arguments","dynamic","dynamic-typing","function","nodejs","parse","varargs","variadic"],"created_at":"2024-10-26T11:23:43.421Z","updated_at":"2025-10-09T12:43:59.571Z","avatar_url":"https://github.com/ORESoftware.png","language":"JavaScript","readme":"\n# Pragmatik\n\nThis library attempts to solve an age-old problem in JavaScript =\u003e how do we correctly parse the arguments inside a function\nthat accepts a variable number of arguments? (See \"variadic functions\" and \"varargs\"). \n\nThis library allows you to elegantly parse arguments at runtime and assign them to the \ncorrect/expected variable in the function signature, according to the parsing rules you define.\nIt is most useful for public and private APIs where we want to give our users the convenience of omitting variables,\nand not requiring them to pass ```null``` or other placeholder values. Of course, you should design your APIs well,\nwith simple function calls with limited number of variation in the signature. Using options objects is a great\ndesign pattern to keep things simple, but at some point variadic functions become convenient and we must handle \nthem well, without writing buggy code that will fail silently in edge cases.\n\n\n### Disclaimer =\u003e the Pragmatik library is in beta\n\nI have seen so many people roll their own solution to this problem - I would be willing to bet at least 1000 JS libraries have public APIs that accept\nvariable number of arguments and/or optional arguments. \nAt best we get bad error messages or no error messages. At worst, we end up with runtimes using the \nwrong values, until something breaks, or worse until something succeeds. Pragmatik is designed to fail-fast =\u003e \n(1) if your function parsing rules are not valid, an error is thrown (2) if any function cannot be parsed successfully given the runtime arguments and the parsing rules, \nan error is thrown.\n\nExtensive testing needs to be completed before this library is totally proven. Also need some sanity checks to make sure this is exactly what people\nneed and want. We will incorporate other \"types\" that can be easily and reliably checked, like 'array'. \nUnfortunately, type checking beyond simple primitive types is not an effective strategy because you don't know whether the user passed \nin the argument in the wrong place in the signature or if they passed the wrong value for the right argument.\n\n## Basic Usage\n\nThe Pragmatik library exports two functions: ```parse``` and ```signature```\n\nThe following is a function that accepts varargs, and we use Pragmatik to parse the arguments:\n\n```js\nconst pragmatik = require('pragmatik');\n\nfunction foo(){\n const [a,b,c,d,e] = pragmatik.parse(arguments, rules);\n  \n}\n```\n\nso we can call foo above, like so:\n\n```foo(true, {zim:'zam'}, function(){});```\n\nand Pragmatik can be used to parse the values as they are expected to appear, for example, first we\nuse signature() to define the parsing rules:\n\n```js\nconst pragmatik = require('pragmatik');\n\nconst r = pragmatik.signature({\n\n    mode: 'strict',                        // does not allow two adjacent non-required types to be the same\n    allowExtraneousTrailingVars: false,    // no more than 5 arguments allowed\n    args: [\n      {\n        type: 'string',\n        required: false,\n      },\n      {\n        type: 'boolean',\n        required: true,\n      },\n      {\n        type: 'object',\n        required: true,\n      },\n      {\n        type: 'boolean',\n        required: false,\n      },\n      {\n        type: 'function',\n        required: false,\n      }\n    ]\n });\n\n\nfunction foo(){\n const [a,b,c,d,e] = pragmatik.parse(arguments, rules);\n \n console.log(a,b,c,d,e); \n // a =\u003e undefined\n // b =\u003e true\n // c =\u003e {zim:'zam'}\n // d =\u003e undefined\n // e =\u003e function(){}\n \n}\n```\n\nif you want better better IDE support, you can do the following instead, but it's fairly unnecessary, (especially\nconsidering the purpose of the library is to support varargs):\n\n```js\nfunction foo(a,b,c,d,e){\n var [a,b,c,d,e] = pragmatik.parse(arguments, rules);\n  \n}\n```\n\n\n\n# Motivation\n\nAs JS is a dynamic language, we can omit arguments completely and still call functions.\n\nFor example,\n\n```js\nfunction foo(a,b,c){\n\n}\n```\n\nwe can call foo without any arguments at all:\n\n```js\nfoo();\n```\n\nand this is valid, of course. But in statically typed languages, this probably won't even compile, let alone run :)\n\nSo, what if argument a is \"optional\", but b and c are \"required\"?\n\nfoo might look like:\n\n```js\nfunction foo(a,b,c){\n  a = a || 'temp';\n  // yadda yadda\n  console.log('a:',a,', b:',b,', c:',c);\n}\n```\n\nif we call foo like this:\n\n```js\nfoo('this is b', 'this is c');\n```\n\nthen of course, we will get:\n\n```a: this is b , b: this is c , c: undefined```\n\nWhich is totally incorrect, according to our intentions. And the problem only gets\nworse in more complicated function calls.\n\nWe could solve this, by requiring users to always pass 3 arguments, no more, no less, which would be:\n\n```js\nfoo(null, 'this is b', 'this is c');\n```\n\nBut what if we want to make our APIs as beautiful as possible and give our users the convenience of omitting\nvariables?\n\n**Enter pragmatik.**\n\n\n\n## Advanced usage\n\n\nPragmatik first validates your rules object, to make sure the rules you define are valid according to the way\nthis library works. Parsing varargs is more difficult than you might think, and you have to settle \non a good strategy.\n\nPragmatik uses types ('function','object','string') as a building block for determining if you passed in the \nexpected variable at the given argument index.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foresoftware%2Fpragmatik","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foresoftware%2Fpragmatik","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foresoftware%2Fpragmatik/lists"}