{"id":15497485,"url":"https://github.com/heapwolf/porter","last_synced_at":"2025-04-15T06:12:27.616Z","repository":{"id":65126509,"uuid":"1427654","full_name":"heapwolf/Porter","owner":"heapwolf","description":"Resource oriented abstraction layer for JSON-REST","archived":false,"fork":false,"pushed_at":"2012-01-17T16:30:58.000Z","size":890,"stargazers_count":155,"open_issues_count":4,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-15T06:12:22.937Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/heapwolf.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":"2011-03-01T20:11:29.000Z","updated_at":"2023-12-11T07:56:40.000Z","dependencies_parsed_at":"2023-01-03T09:18:31.478Z","dependency_job_id":null,"html_url":"https://github.com/heapwolf/Porter","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/heapwolf%2FPorter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heapwolf%2FPorter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heapwolf%2FPorter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heapwolf%2FPorter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heapwolf","download_url":"https://codeload.github.com/heapwolf/Porter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249016638,"owners_count":21198833,"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-10-02T08:38:32.081Z","updated_at":"2025-04-15T06:12:27.598Z","avatar_url":"https://github.com/heapwolf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Alt text](https://github.com/hij1nx/Porter/raw/master/doc/logo.png)\u003cbr/\u003e\n\n### porter is a lightweight, resourced oriented, abstraction layer for JSON-REST. It will generate methods needed to access resources based on a JSON configuration. It will balance your code's signal to noise ratio by simplifying the communication interfaces.\n\n```javascript\nvar porter = Porter({\n\n  users: {\n    list: ['get', '/api/users/:partialname'],\n    update: ['post', '/api/apps/:username']\n  },\n\n  apps: {\n    list: ['get', '/api/apps/:username'],\n    create: ['post', '/api/apps/:username/:appname']\n  }\n\n});\n```\n\nProduces the following methods.\n\n```javascript\n  porter.users.list(/* ... */);\n  porter.users.update(/* ... */);\n  porter.apps.list(/* ... */);\n  porter.apps.create(/* ... */);\n```\n\nThe Porter constructor takes a single object literal containing members grouped by resource. Resources are then expressed as arrays. In the case of defining a REST call, there is a verb and a path, where each path can have tokens in it that will get supplanted when used. Here is the above definition put in use...\n\n### Payload and Parameters\n\n```javascript\nporter.users.list(\n\n  { partialname: 'bill' }, // replaces the ':partialname' token in the 'list' resource's URI.\n  { foo: 10, bar: 20 }, // appends '?foobar=10\u0026bar=20' to the URL when the method is a GET, adds as a message body for a POST.\n  function(error, response) {\n    // do something...\n  }\n\n);\n```\n\nThe `list` function was generated from its definition in the `users` group. We pass it 1) an object literal that supplants the token in the request url and 2) a callback function that will process when the request is done.\n\n### Adding inbound and outbound data validation, and more complex resource organization.\n\n```javascript\nfunction hasData(data) { // a simple data validator.\n  if(typeof data !== 'undefined') {\n    return true;\n  }\n}\n\nvar porter = Porter({\n\n  admin: {\n    users: {\n      list: ['get', '/api/users/:partialname', { outbound: hasData, inbound: hasData }],\n      update: ['post', '/api/apps/:username']\n    },\n\n    apps: {\n      list: ['get', '/api/apps/:username'],\n      create: ['post', '/api/apps/:username/:appname']\n    }\n  }\n});\n```\nAny arbitrary function can be applied to assert the inbound and outbound data of a request, as seen above. If a validating function returns anything other than true, it is considered invalid and the callback for the resource will will have its 'error' parameter populated with either the exception or the return value of the validator.\n\n### Specifying settings that apply to all calls that get made.\n\n```javascript\nvar porter = Porter({\n\n  users: {\n    list: ['get', '/api/users/:partialname', { outbound: hasData, inbound: hasData }],\n    update: ['post', '/api/apps/:username', { inbound: hasData }]\n  },\n\n  apps: {\n    list: ['get', '/api/apps/:username', { inbound: hasData }],\n    create: ['post', '/api/apps/:username/:appname', { inbound: hasData }]\n  }\n\n}).use({\n  port: 8080,\n  inbound: hasData,\n  outbound: hasData,\n  headers: { 'Accept': 'application/json' }\n});\n```\n\nThe `use` function sets the defaults for all calls that get made. It accepts an object literal containing the following members...\n\n`port` Number - The port of the server that will accept the requests.\u003cbr/\u003e\n`inbound` Object - A JSONSchema object that will validate against every incoming request.\u003cbr/\u003e\n`outbound` Object - A JSONSchema object that will validate against every outgoing request.\u003cbr/\u003e\n`host` String - An IP address of the host server that will accept the requests.\u003cbr/\u003e\n`headers` Object - An object literal of HTTP request headers that will be attached to each request.\u003cbr/\u003e\n`protocol` String - The protocol to be used for all requests, ie 'http', 'https'.\u003cbr/\u003e\n`lib` Object - If you want to use a more full featured, cross-browser friendly ajax library ****add this back!****.\u003cbr/\u003e\n\nAnd here is the above code in use...\n\n```javascript\nporter.headers['Authorization'] = 'Basic ' + encodeBase64('username:password');\n\nporter.users.update(\n  \n  { partialname: 'bill' },\n  { address: '555 Mockingbird Ln' },\n  \n  function(error, response) {\n    // do something...\n  }\n);\n```\n\nThe `update` function was generated from its definition in the `users` group. We pass it a payload object, some data to replace the url tokens with and a callback function for when the request has finished processing. The app object will also expose the headers collection, this is simply an object literal that contains the headers to be used for the request.\n\n### Specifying what to do with the response.\n\n```javascript\nvar porter = Porter({\n\n  users: {\n    list: ['get', '/api/users/:partialname']\n  }\n\n}).use({\n  port: 8080,\n  host: 'google.com'\n}).on({\n  '500': function(err, response) {\n    // do something...\n  },\n  '404': function(err, response) {\n    // do something...\n  }\n});\n```\n\nIn a lot of cases you'll want to handle http responses based on their response code. using the `on` method will allow you to associate methods with these response codes. In some cases you'll want to explicitly override these http response code handlers. you can do this by replacing the regular callback method with an object literal containing the items to overwrite.\n\n```javascript\nporter.users.update(\n  \n  { partialname: 'bill' },\n  { address: '555 Mockingbird Ln' },\n  \n  {\n    '404': function(err, response) {\n      // do something...\n    },\n    '500': function(err, response) {\n      // do something...\n    }\n  }\n);\n```\n\n\n### Testing and debugging.\n\nPorter provides a simple Node.js server to complement it's test suite.\nYou may find this a useful starting point for your own test suite.\nRunning `npm install \u0026\u0026 npm test` from root folder of this project will start\ndevelopment server that will be used for serving tests.\n![Alt text](https://github.com/hij1nx/Porter/raw/master/doc/test.png)\u003cbr/\u003e\n\n\n## Credits\n\nAuthor: @hij1nx\n\nContributors: @indexzero, @marak, @indutny\n\n## Licence\n\n(The MIT License)\n\nCopyright (c) 2011 hij1nx \u003chttp://www.twitter.com/hij1nx\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheapwolf%2Fporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheapwolf%2Fporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheapwolf%2Fporter/lists"}