{"id":17699,"library":"http-problem-details","title":"HTTP Problem Details (RFC 7807)","description":"This library provides an implementation of HTTP Problem Details (RFC 7807) for Node.js applications, enabling standardized machine-readable error responses for HTTP APIs. As of version 0.1.7, it offers classes like `ProblemDocument` and `ProblemDocumentExtension` to construct detailed error objects that conform to the specification, including standard fields like `type`, `title`, `status`, `detail`, and `instance`, as well as support for extension members. The package is built with TypeScript, providing strong typing out of the box, and explicitly validates `type` and `instance` fields as valid URIs, throwing errors on invalid input. While the project is in its early stages of development (pre-1.0.0), it encourages contributions and aims for strict RFC compliance, differentiating itself by offering a focused, unopinionated foundation for problem detail generation.","status":"active","version":"0.1.7","language":"javascript","source_language":"en","source_url":"https://github.com/PDMLab/http-problem-details","tags":["javascript","http","problem","error","rfc7807","api","rest","typescript"],"install":[{"cmd":"npm install http-problem-details","lang":"bash","label":"npm"},{"cmd":"yarn add http-problem-details","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-problem-details","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ESM modules, use named imports. CommonJS `require` syntax is shown in older README examples but ESM is preferred in modern Node.js/TypeScript setups.","wrong":"const ProblemDocument = require('http-problem-details').ProblemDocument;","symbol":"ProblemDocument","correct":"import { ProblemDocument } from 'http-problem-details';"},{"note":"Use named imports for ESM. Older CJS `require` examples exist, but modern usage favors ESM. This class is for adding custom key-value pairs to the problem document.","wrong":"const ProblemDocumentExtension = require('http-problem-details').ProblemDocumentExtension;","symbol":"ProblemDocumentExtension","correct":"import { ProblemDocumentExtension } from 'http-problem-details';"},{"note":"If using CommonJS, destructure the named exports from the `require` call. Directly requiring the package without destructuring will not work as expected.","wrong":"const ProblemDocument = require('http-problem-details'); // Incorrect destructuring","symbol":"ProblemDocument and ProblemDocumentExtension (CommonJS)","correct":"const { ProblemDocument, ProblemDocumentExtension } = require('http-problem-details');"}],"quickstart":{"code":"import { ProblemDocument, ProblemDocumentExtension } from 'http-problem-details';\nimport { Request, Response } from 'express';\n\n// Example of an Express error handler generating a Problem Document\nexport const errorHandler = (err: any, req: Request, res: Response, next: Function) => {\n  console.error(err);\n\n  let problemDocument: ProblemDocument;\n\n  // Handle a specific custom error, e.g., 'InsufficientFundsError'\n  if (err.name === 'InsufficientFundsError') {\n    const extension = new ProblemDocumentExtension({\n      balance: err.currentBalance, // assuming err has currentBalance property\n      required: err.amountRequired,\n      transactions: ['/account/123/tx/456', '/account/123/tx/789']\n    });\n    problemDocument = new ProblemDocument({\n      type: 'https://example.com/probs/out-of-credit',\n      title: 'You do not have enough credit.',\n      detail: err.message || 'Your current balance is insufficient for this operation.',\n      status: 403, // Forbidden\n      instance: req.originalUrl // Reflects the specific request\n    }, extension);\n  } else if (err.status) {\n    // Handle errors that already have an HTTP status\n    problemDocument = new ProblemDocument({\n      type: 'about:blank',\n      title: err.message || 'An unexpected error occurred.',\n      status: err.status,\n      detail: err.detail,\n      instance: req.originalUrl\n    });\n  } else {\n    // Default catch-all for unknown errors\n    problemDocument = new ProblemDocument({\n      type: 'about:blank',\n      title: 'Internal Server Error',\n      status: 500,\n      detail: 'An unexpected server error occurred.',\n      instance: req.originalUrl\n    });\n  }\n\n  res.status(problemDocument.status || 500).json(problemDocument);\n};\n\n// To demonstrate usage:\n// class InsufficientFundsError extends Error {\n//   constructor(message: string, public currentBalance: number, public amountRequired: number) {\n//     super(message);\n//     this.name = 'InsufficientFundsError';\n//   }\n// }\n//\n// const mockReq: Request = { originalUrl: '/api/checkout/item/123' } as Request;\n// const mockRes: Response = { status: jest.fn().mockReturnThis(), json: jest.fn() } as unknown as Response;\n// const mockNext = jest.fn();\n//\n// const error = new InsufficientFundsError('Not enough funds to purchase item.', 30, 50);\n// errorHandler(error, mockReq, mockRes, mockNext);\n//\n// console.log(mockRes.json.mock.calls[0][0]);","lang":"typescript","description":"This quickstart demonstrates how to integrate `http-problem-details` within an Express.js error handling middleware to generate RFC 7807 compliant error responses, including custom extension members."},"warnings":[{"fix":"Ensure `type` and `instance` are valid URI strings (e.g., 'https://example.com/probs/my-error' or '/api/errors/123'). You can use a URI validation library if inputs are user-generated.","message":"The `type` and `instance` properties of `ProblemDocument` require valid URI references. Providing non-URI strings will result in an error being thrown during object construction.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Pin exact versions (e.g., `\"http-problem-details\": \"0.1.7\"`) in `package.json` to prevent unexpected breaking changes. Review release notes carefully when upgrading to new pre-1.0 versions.","message":"As the library is pre-1.0.0 (currently 0.1.7), the API is not yet considered stable. Future minor or patch releases may introduce breaking changes without a major version increment, aligning with common pre-1.0 development practices.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure the `type` property is a well-formed URI, such as 'https://example.com/errors/bad-request' or 'about:blank'.","cause":"The `type` property passed to the ProblemDocument constructor was not a valid URI string.","error":"Error: Invalid URI provided for 'type'"},{"fix":"Provide a valid URI for `instance`, typically a path or URL pointing to the specific occurrence of the problem, e.g., '/orders/12345/items/failed'.","cause":"The `instance` property passed to the ProblemDocument constructor was not a valid URI string.","error":"Error: Invalid URI provided for 'instance'"},{"fix":"For CommonJS, use `const { ProblemDocument } = require('http-problem-details');`. For ESM, use `import { ProblemDocument } from 'http-problem-details';`.","cause":"Attempting to use `require('http-problem-details')` directly as a constructor, or not correctly destructuring named exports in CommonJS.","error":"TypeError: ProblemDocument is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}