{"id":17279,"library":"json-patch","title":"JSON Patch and Pointer Implementation","description":"This library provides a JavaScript implementation of the JSON Patch (RFC 6902) and JSON Pointer (RFC 6901) specifications. It allows for applying changes to JSON documents, including operations like add, remove, replace, move, copy, and test. The current stable version is 0.7.0. A key characteristic is that all patch operations are applied *in-place*, directly modifying the input document, which can lead to significant side effects. The package supports usage in browsers, Node.js environments via CommonJS, and AMD modules. Given its version and the age of its last known development activity (last commit over 10 years ago on its GitHub repository), the package is considered unmaintained and has not seen updates for several years, making it unsuitable for new projects requiring active support or modern features. It adheres to the RFC standards but lacks modern JavaScript conveniences or TypeScript support.","status":"abandoned","version":"0.7.0","language":"javascript","source_language":"en","source_url":"git://github.com/bruth/jsonpatch-js","tags":["javascript","diff","patch","json","jsonpatch","jsonpointer"],"install":[{"cmd":"npm install json-patch","lang":"bash","label":"npm"},{"cmd":"yarn add json-patch","lang":"bash","label":"yarn"},{"cmd":"pnpm add json-patch","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily exports a single 'jsonpatch' object. For ESM, use a default import. For CommonJS, use `require()` to import the entire object.","wrong":"import { apply } from 'json-patch'; // The library exports a single default object, not named functions.\nconst { apply } = require('json-patch'); // Destructuring will not work as it's not a direct named export.","symbol":"jsonpatch","correct":"import jsonpatch from 'json-patch';\n// Or for CommonJS:\nconst jsonpatch = require('json-patch');"},{"note":"The `apply` function is a method available on the main `jsonpatch` object after importing the library.","wrong":"import { apply } from 'json-patch'; // 'apply' is a method on the default export, not a top-level named export.","symbol":"jsonpatch.apply","correct":"import jsonpatch from 'json-patch';\nconst document = {};\nconst patch = [];\njsonpatch.apply(document, patch);"},{"note":"Custom error constructors like `JSONPatchError`, `PatchTestFailed`, etc., are exposed as properties of the main `jsonpatch` object, not as direct named exports.","wrong":"import { JSONPatchError } from 'json-patch'; // Error classes are properties of the main 'jsonpatch' object, not named exports.","symbol":"jsonpatch.JSONPatchError","correct":"import jsonpatch from 'json-patch';\ntry { /* ... */ } catch (e) { if (e instanceof jsonpatch.JSONPatchError) { /* handle */ } }"}],"quickstart":{"code":"import jsonpatch from 'json-patch';\n\n// Example document to be patched\nconst originalDocument = { \n  id: 1,\n  user: { name: 'Alice', age: 30 },\n  tags: ['admin', 'editor'],\n  settings: { theme: 'dark' }\n};\n\n// A series of JSON Patch operations\nconst patch = [\n  { op: 'replace', path: '/user/age', value: 31 },\n  { op: 'add', path: '/tags/0', value: 'premium' },\n  { op: 'remove', path: '/settings/theme' },\n  { op: 'copy', from: '/user/name', path: '/creator' },\n  { op: 'test', path: '/user/name', value: 'Alice' } // This will pass\n];\n\nconsole.log('Original Document:', JSON.stringify(originalDocument, null, 2));\n\ntry {\n  // WARNING: jsonpatch.apply modifies the document in-place. \n  // If you need to preserve the original, clone it first.\n  const patchedDocument = jsonpatch.apply(originalDocument, patch);\n  \n  console.log('\\nPatched Document (in-place modified):', JSON.stringify(patchedDocument, null, 2));\n  console.log('Original Document after patch (also modified):', JSON.stringify(originalDocument, null, 2));\n\n  // Example of a failing test operation\n  const failingPatch = [{ op: 'test', path: '/user/age', value: 25 }];\n  console.log('\\nAttempting a failing test operation...');\n  jsonpatch.apply(originalDocument, failingPatch); // This will throw\n\n} catch (e) {\n  if (e instanceof jsonpatch.PatchTestFailed) {\n    console.error('\\nCaught a PatchTestFailed error:', e.message);\n  } else if (e instanceof jsonpatch.InvalidPatchError) {\n    console.error('\\nCaught an InvalidPatchError:', e.message);\n  } else if (e instanceof jsonpatch.InvalidPointerError) {\n    console.error('\\nCaught an InvalidPointerError:', e.message);\n  } else {\n    console.error('\\nAn unexpected error occurred:', e.message);\n  }\n}","lang":"javascript","description":"Demonstrates applying various JSON Patch operations (replace, add, remove, copy, test) to an object and handling potential errors, specifically highlighting the library's in-place modification behavior."},"warnings":[{"fix":"To prevent unintended mutations, always clone your document before applying the patch: `const clonedDocument = JSON.parse(JSON.stringify(originalDocument)); jsonpatch.apply(clonedDocument, patch);`","message":"All patch operations (add, remove, replace, move, copy, test) are applied directly 'in-place', mutating the original document object provided as the first argument. This behavior can lead to unexpected side effects if not explicitly handled by cloning the document beforehand.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Update your error handling logic to catch `jsonpatch.PatchTestFailed` instead of checking a boolean return value. Example: `try { jsonpatch.apply(doc, [{op: 'test', path: '/foo', value: 'bar'}]) } catch (e) { if (e instanceof jsonpatch.PatchTestFailed) { /* handle failure */ } }`","message":"The `test` operation's return value changed significantly in version 0.5.0. Prior to 0.5.0, it returned a boolean (true/false) indicating success or failure. Since 0.5.0, it returns the document itself on success and throws a `PatchTestFailed` error on failure, aligning with the JSON Patch specification.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"It is strongly recommended to migrate to actively maintained JSON Patch libraries such as `fast-json-patch` or `json-patch-es6` for better support, performance, and modern JavaScript features.","message":"This package is considered abandoned and unmaintained. Its last significant commit on GitHub was over 10 years ago. It does not receive security updates, bug fixes, or new feature development, making it unsuitable for new projects or production environments that require ongoing support.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Manually declare types in a `.d.ts` file (e.g., `declare module 'json-patch' { ... }`) to provide type safety, or consider switching to a modern, actively maintained library with native TypeScript support.","message":"The package does not ship with TypeScript type definitions, which is common for older JavaScript libraries. Developers using TypeScript will need to create their own declaration files (`.d.ts`) or use an external `@types/json-patch` package if one exists, though support for abandoned libraries is often limited.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the `value` provided in the `test` operation precisely matches the actual value at the `path` in the document, or adjust the patch logic to reflect the expected state.","cause":"A `test` operation within the JSON patch found that the specified path did not contain the expected value, leading to a failure and halting the patch application.","error":"Uncaught PatchTestFailed: Test operation failed"},{"fix":"Carefully verify that each object in your patch array strictly adheres to the JSON Patch RFC 6902 specification for the respective operation type.","cause":"One of the patch operations provided (e.g., add, remove, replace, etc.) has an invalid or malformed structure, or is missing required fields such as 'op', 'path', 'from', or 'value' as defined by RFC 6902.","error":"Uncaught InvalidPatchError: Expected an object, got..."},{"fix":"Review the `path` or `from` fields in your patch operations to ensure they are valid JSON Pointers and accurately correspond to the structure of your target document.","cause":"A JSON Pointer path (e.g., `/foo/bar`) used in a patch operation is syntactically incorrect, malformed, or references a non-existent or invalid segment within the document structure (e.g., attempting to access `/foo/bar` when `foo` is not an object).","error":"Uncaught InvalidPointerError: Invalid pointer: ..."},{"fix":"For CommonJS, use `const jsonpatch = require('json-patch');`. For ESM, use `import jsonpatch from 'json-patch';`. Always access functions via the `jsonpatch` object: `jsonpatch.apply(...)`.","cause":"This error commonly occurs when attempting to destructure `apply` as a named export in ESM or CommonJS, or when the `jsonpatch` object itself is not correctly imported (e.g., it might be undefined or an empty object). The library exports a single object, not individual functions.","error":"TypeError: jsonpatch.apply is not a function"}],"ecosystem":"npm","meta_description":null}