{"id":20281784,"url":"https://github.com/edufresne/express-api-responder","last_synced_at":"2025-04-11T07:57:53.451Z","repository":{"id":68948349,"uuid":"115941230","full_name":"edufresne/express-api-responder","owner":"edufresne","description":"A small package for Express.js containing convenience methods for returning JSON responses.","archived":false,"fork":false,"pushed_at":"2018-04-03T03:59:39.000Z","size":62,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-04T16:48:04.827Z","etag":null,"topics":["api","express-js","expressjs","json","middleware","response","response-system"],"latest_commit_sha":null,"homepage":null,"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/edufresne.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-01T19:18:27.000Z","updated_at":"2020-04-25T09:01:45.000Z","dependencies_parsed_at":"2023-06-01T23:46:06.397Z","dependency_job_id":null,"html_url":"https://github.com/edufresne/express-api-responder","commit_stats":{"total_commits":24,"total_committers":1,"mean_commits":24.0,"dds":0.0,"last_synced_commit":"2b521a064b1af664c655a5524c8a1131b9c04c5d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edufresne%2Fexpress-api-responder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edufresne%2Fexpress-api-responder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edufresne%2Fexpress-api-responder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edufresne%2Fexpress-api-responder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edufresne","download_url":"https://codeload.github.com/edufresne/express-api-responder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248360092,"owners_count":21090651,"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":["api","express-js","expressjs","json","middleware","response","response-system"],"created_at":"2024-11-14T14:06:50.281Z","updated_at":"2025-04-11T07:57:53.442Z","avatar_url":"https://github.com/edufresne.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# express-api-responder\n[![version](https://img.shields.io/npm/v/express-api-responder.svg)](https://www.npmjs.org/package/express-api-responder)\n[![MIT Licence](https://badges.frapsoft.com/os/mit/mit.svg?v=103)](https://opensource.org/licenses/mit-license.php)\n[![Build Status](https://travis-ci.org/edufresne/express-api-responder.svg?branch=master)](https://travis-ci.org/edufresne/express-api-responder)\n[![Coverage Status](https://coveralls.io/repos/github/edufresne/express-api-responder/badge.svg?branch=master)](https://coveralls.io/github/edufresne/express-api-responder?branch=master)\n\nA small Express.js Middleware for conveniently formatting JSON responses. This package builds into the Express.js \nresponse object and allows you to return data in the following:\n- A response after a successful request\n- Paginated data for a list\n- An error for a bad request or other errors\n- No content after a deletion\n- Signing a request with a JWT auth token\n- Catch a server error and return an error message without important knowledge of the system\n\n### Setup\n```\nnpm install express-api-responder --save\n```\nCan be used by your whole app or a router\n```javascript\nvar repsonder = require('express-api-responder');\napp.use(responder());\n//or\nvar router = express.Router();\nrouter.use(responder({}));\n\n//How to use\nrouter.get('/messages', function(req, res) {\n  res.success({hello: 'world'});\n})\n```\nOutputs `200`\n```json\n{\n  \"hello\": \"world\"\n}\n```\n\n### Return Success Response\n\nReturns a JSON body. By default returns HTTP status code 200 but a code can be passed.\n```javascript\nres.success({item1: 'Hello', item2: false}, 201);\n```\nOutput `200`\n```json\n{\n  \"item1\": \"Hello\",\n  \"item2\": false\n}\n```\n### Return Error Response\n\nReturns a JSON body with a message field for error handling. Defaults the HTTP status\ncode to 400. The message also defaults to a description based on the code\n\n```javascript\nres.error('Cant find your message', 404);\n//Or default to the code descriptor\nres.error(null, 404);\n```\n\nOutput `404`\n```json\n{\n  \"message\": \"Cant find your message\"\n}\n```\nor\n```json\n{\n  \"message\": \"Not Found\"\n}\n```\n\n### Paginated Responses\n\nReturns a JSON object with a list of data as well as some useful fields. Defaults 200 HTTP status code\n```javascript\nvar data = [{name: 'Eric'}, {name: 'Dufresne'}, ...];\nvar totalCount = 50;\nvar page = 1;\nvar limit = 25;\nres.paginate(data, totalCount, page, limit);\n```\n\nOutput: `200`\n```json\n{\n  \"list\": [\n    {\n      \"name\": \"Eric\"\n    },\n    {\n      \"name\": \"Dufresne\"\n    }\n  ],\n  \"limit\": 25,\n  \"page\": 1,\n  \"count\": \"50\",\n  \"pages\": 2\n}\n```\n\n### Catch Internal Server Error\nReturns an error message based on the HTTP status code given for an unexpected error.\nDefaults to HTTP status code 500 but a code can be passed.\n\n```javascript\nres.catch(err);\n```\nIn production environment `500`\n```json\n{\n  \"message\": \"Internal Server Error\"\n}\n```\nif not in a production environment `500`\n```json\n{\n  \"message\": \"Table \\\"messages\\\" doesn't exist...\"\n}\n```\n\n### Signing Responses\nMust provide a JWT secret or private key to the responder options.\n```javascript\napp.use(responder({\n  signing: {\n    jwtSecret: 'some-super-secret'\n  }\n}));\n\nres.sign({hello: 'world', id: 32});\n```\nResponse `200`\n```json\n{\n  \"data\": {\n    \"id\": 32,\n    \"hello\": \"world\"\n  },\n  \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJoZWxsbyI6IndvcmxkIiwiaWQiOjMyLCJpYXQiOjE1MTUzNzI0NzN9.uU_9EoOSodk6tR4LdzxYaAVefkVjXtdxfCfSM_OynKo\"\n}\n```\n\n### No Content\n```javascript\nres.noContent();\n```\n\n### Extra Options\nYou can include the status code as well as a success flag in all the JSON responses\nby passing extra options to the middleware.\n```javascript\napp.use(responder({\n  includeCode: 'status',\n  includeSuccess: 'success'\n}));\n\nres.error(null, 409);\n```\nResponse `409`\n```json\n{\n  \"success\": false,\n  \"status\": 409,\n  \"message\": \"Conflict\"\n}\n```\n\n### Run Tests\nTests use a mock server with the middleware in place. Can run using mocha as well as with istanbul\n```\nnpm run test\nnpm run cover\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedufresne%2Fexpress-api-responder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedufresne%2Fexpress-api-responder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedufresne%2Fexpress-api-responder/lists"}