{"id":16741550,"url":"https://github.com/duaraghav8/matrix-parser","last_synced_at":"2025-04-10T13:22:55.299Z","repository":{"id":57292536,"uuid":"61427409","full_name":"duaraghav8/matrix-parser","owner":"duaraghav8","description":"Node.js middleware for parsing Matrix URIs","archived":false,"fork":false,"pushed_at":"2016-07-22T04:54:03.000Z","size":17,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T12:09:02.770Z","etag":null,"topics":["expressjs","matrix-uri","nodejs","parsing","uri"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/matrix-parser","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/duaraghav8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-18T09:56:50.000Z","updated_at":"2024-05-31T16:45:21.000Z","dependencies_parsed_at":"2022-08-27T16:41:08.059Z","dependency_job_id":null,"html_url":"https://github.com/duaraghav8/matrix-parser","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/duaraghav8%2Fmatrix-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duaraghav8%2Fmatrix-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duaraghav8%2Fmatrix-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duaraghav8%2Fmatrix-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duaraghav8","download_url":"https://codeload.github.com/duaraghav8/matrix-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247856541,"owners_count":21007620,"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":["expressjs","matrix-uri","nodejs","parsing","uri"],"created_at":"2024-10-13T01:03:28.255Z","updated_at":"2025-04-10T13:22:55.266Z","avatar_url":"https://github.com/duaraghav8.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"matrix-parser is a Node.js Middleware for parsing [Matrix URIs](https://www.w3.org/DesignIssues/MatrixURIs.html)\n\n#Install\n```bash\nnpm install matrix-parser\n```\n\n#Run Tests\ntraverse to the root directory 'matrix-parser' and:\n```bash\nnpm install\nnpm test\n```\n\n#API\n```javascript\nvar matrixParser = require ('matrix-parser');\n```\n\nThe ```matrixParser``` object exposes a single function - the Middleware to parse matrix-style URIs. When used, it creates the matrix Array inside the request object, which can be accessed like ```req.matrix```\n\n##Options\nYou can pass an ```options``` object when calling matrixParser (). The object currently supports the ```maxKeys``` field, used to specify **the maximum number of keys allowed per segment**. Keys are added into the matrix object from left to right.\n\nFor example, using ```matrixParser ({ maxKeys: 2 })``` and a URI ```http://example.com/home;k1=v1;k2=v2;k3=v3``` will simply neglect all key-value pairs after k2.\n\n**NOTE:** The middleware currently doesn't support Matrix URIs to be used in combination with query strings.\nYou could use matrix parameters **before** the '?', followed by query parameters, but mixing is not currently supported.\n\n#Rules\nHere are the rules matrix-parser follows to parse Matrix URIs. Check out [this thread](https://github.com/medialize/URI.js/issues/181) to understand in more detail.\n\n\t\t1. The semicolon ';' is used to delimit key-value pairs (unlike the ampersand '\u0026' in query strings)\n\t\t\teg- /index;a=b;c=d\n\n\t\t2. '=' is used to delimit the keys and values\n\n\t\t3. The string between / and the first ; is the segment name.\n\t\t\teg- /index;hello=world\n\t\t\there, segment = \"index\"\n\n\t\t4. All keys are unique. For compatibility, the key's last declaration is used to assign its value\n\t\t\teg- /index;key1=value1;key2=v2;key1=helloworld\n\t\t\there, the value of key1 = 'helloworld' (NOT value1)\n\n\t\t5. Comma ',' is used to assign multiple values to a key\n\t\t\teg- /index;list=1,2,3,4\n\t\t\there, list = [1,2,3,4] (array containing the comma-separated values)\n\n\t\t6. Spaces are encoded as %20 instead of +\n\t\t\teg- /index;msg=hello%20world\n\n\t\t7. If a key is not followed by the delimiter '=' and value, it is discarded\n\t\t\teg- /index;a=b;noValueKey;c=d\n\t\t\there, noValueKey will be discarded and will not be present in the matrix\n\n\t\t8. If a key is followed by the delimiter '=' but not a value, its value is set to ''\n\t\t\teg- /index;key=;a=b\n\t\t\there, key = ''\n\n\t\t9. If no segment name is given, it defaults to ''\n\t\t\teg- http://example.com/;key=value\n\t\t\there, segment = '' and key = 'value'\n\n\t\t10. If the path name is empty, req.matrix defaults an array of single object with segment = '' and matrix = {}\n\t\t\teg- http://example.com/\n\t\t\there, req.matrix = [ {segment: \"\", matrix: {}} ]\n\n#Format\nA typical Matrix URI looks like:\n```\nhttp://\u003cDOMAIN\u003e:\u003cPORT\u003e/\u003cSEGMENT-0\u003e;\u003cKEY1\u003e=\u003cVALUE1\u003e;\u003cKEY2\u003e=\u003cVALUE2\u003e/\u003cSEGMENT-1\u003e;\u003cKEY1\u003e=\u003cVALUE1\u003e\n```\n\nThe constructed req.matrix looks like:\n```\n[\n\t{\n\t\tsegment: \u003cSEGMENT-0\u003e,\n\t\tmatrix: {\n\t\t\t\u003cKEY1\u003e : \u003cVALUE1\u003e,\n\t\t\t\u003cKEY2\u003e : \u003cVALUE2\u003e\n\t\t}\n\t},\n\t{\n\t\tsegment: \u003cSEGMENT-1\u003e,\n\t\tmatrix: {\n\t\t\t\u003cKEY2\u003e : \u003cVALUE2\u003e\n\t\t}\n\t}\n]\n```\n\n#Examples\n\n###Express: Top-level generic\n```javascript\nvar app = require ('express') (),\n\tmatrixParser = require ('matrix-parser');\n\napp\n\t.use (matrixParser ())\n\t.get ('*', function (req, res, next) {\n\t\tres.header ('Content-Type', 'text/plain');\n\t\tres.write ('You posted: ');\n\t\tres.end (JSON.stringify (req.matrix, null, 2));\n\t})\n\t.listen (8080, function () {\n\t\tconsole.log ('listening on port 8080');\n\t});\n```\n\n###Test:\n```bash\ncurl 'http://localhost:8080/index;name=RAGHAV%20DUA;house=targaryen/profile;age=20;email=duaraghav8%40gmail.com'\n```\n\nNOTICE THE %20 USED TO INDICATE SPACE INSTEAD OF +\n\nOutput Construct of ```req.matrix```:\n```javascript\n[\n\t{\n\t\tsegment: 'index',\n\t\tmatrix: {\n\t\t\tname: 'RAGHAV DUA',\n\t\t\thouse: 'targaryen'\n\t\t}\n\t},\n\t{\n\t\tsegment: 'profile',\n\t\tmatrix: {\n\t\t\tage: 20,\n\t\t\temail: 'duaraghav8@gmail.com'\n\t\t}\n\t}\n]\n```\n\n**NOTE:** If you want to allow Matrix on a specific route (like '/index'), then you have to append '*' to it like\n```javascript\napp.get ('/index*', function (req, res) {\n\t/*\n\t\tthis means that the first segment of the matrix is always \"index\"\n\t\tand only URIs starting with /index are valid, like:\n\t\thttp://example.com/index;hello=world\t\t(VALID)\n\t\thttp://example.com/home;hello=world\t\t\t(INVALID)\n\t*/\n\tassert (req.matrix [0].segment === \"index\");\t//no assertion errors =)\n});\n```\n\n###Express: Route-specific\n```javascript\nvar app = require ('express') (),\n\tmatrixParser = require ('matrix-parser');\n \nvar colorCodes = {\n\t\"white\": \"#FFFFFF\",\n\t\"black\": \"#000000\"\n};\n\nvar mpMiddleware = matrixParser ({ maxKeys: 1 });\t//notice the use of the maxKeys option\n \napp\n\t.get ('/index*', mpMiddleware, function (req, res, next) {\n\t\tvar color = req.matrix [0].matrix.color; //req.matrix [0] refers to parameters provided in the /index segment \n\t\tres.send ('Color code for ' + color + ' is ' + colorCodes [color]);\n\t})\n\t.listen (8080, function () {\n\t\tconsole.log ('listening on port 8080');\n\t});\n```\n\n###Test 1:\n```bash\ncurl 'http://localhost:8080/index;color=white'\n```\n\nOutput: ```Color code for white is #FFFFFF```\n\n###Test 2:\n```bash\ncurl 'http://localhost:8080/index;color=indigo'\n```\n\nOutput: ```Color code for white is undefined```\n(because color code for indigo is not defined in colorCodes object in our script)\n\n#License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduaraghav8%2Fmatrix-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduaraghav8%2Fmatrix-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduaraghav8%2Fmatrix-parser/lists"}