New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More
Socket
Sign inDemoInstall
Socket

patch

Package Overview
Dependencies
Maintainers
1
Versions
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

patch

an object patching tool

  • 0.0.1
  • latest
  • npm
  • Socket score

Version published
Weekly downloads
909
increased by2.36%
Maintainers
1
Weekly downloads
 
Created
Source

patch

Patch is yet another jQuery.extend clone, but with a few extra quirks. It implements a protocol for "patching" objects in aribtrary ways, rather than simply "extending" objects. That is, rather than simply adding or replacing values in an object, it is possible to modify or delete existing values, too.

overview

patch takes 3 or more arguments: options, the object to modify, and the object(s) to pull modifications from. The default behavior (i.e. with an empty options parameter) should seem intuitive, it will simply create a copy of the last argument:

var patch = require('patch')

var patched = patch({}, {}, {key: "value"})
// patched = {key: "value"}

How about something a bit fancier? Let's tell patch to delete certain keys in the object being modified:

var obj = {
    hello: "world",
    name: "steve"
}
var options = {
    delete: "delete this one"
}
patch(options, obj, {hello: "delete this one"}
// => {name: "steve"}

Cool. Any key being updated to the value specified in the "delete" option is deleted instead. Note that keys that already have the "delete" value are not deleted.

What about arrays? Most extend clones simply replace values in the destination object, so if you have a large array you want to modify, you have to modify it and then pass in the whole thing. patch provides options for modifying existing arrays in-place, so you only have to pass in the new values:

var obj = {
    numbers: [1,2,3,4,5]
}
var options = {
    arrays: 'prepend'
}
patch(options, obj, {numbers: [-2, -1, 0]})
//=> {numbers: [-2, -1, 0, 1, 2, 3, 4, 5]}

Note that if the value does not exist in yet in the original object, the 'arrays' option is ignored.

Valid values for the "arrays" option are:

  • prepend - prepend the given values to the existing array
  • append - append the given values
  • replace - throw out the old array and replace it with the new one (default behavior)
  • splice - call Array.splice, passing in the new values as arguments to splice (uses Array.prototype.splice.apply(oldArr, newArr) under the hood). This allows arbirary modifications to an array - add/remove/replace arbitrary elements
  • join - tired of that pesky array? Make it into a string in one fell swoop by calling "join". Specify a separator too, if you'd like.

options

All options supported by patch:

  • deep - boolean - default false - when true, patching is recursive on child objects and arrays, creating a deep copy
  • arrays - prepend|append|replace|splice|join - default 'replace' - define patch behavior when an array already exists in the destination object
  • delete - any - default none - any value being updated to this value will be deleted rather than updated

why?

Why build yet another extend-like module? patch was designed to support partial object updates in a REST API. RFC 5789 defines the HTTP PATCH verb. Using the PATCH verb can save bandwidth compared to PUT or POST when updating resources, since a client only needs to send the updated bits. The RFC also describes some other advantages of using PATCH over other methods.

Consider a simple key-value REST API that stores JSON documents (see patchstore for an example) that supports partial updates. Some challenges come up in writing such an API:

  • what do you do with JSON documents with arbitrarily nested objects?
  • How do you handle arrays? What if there is a long array that needs only a minor modification?
  • How do you update a document, deleting a key rather than changing its value?

Using the patch module, such an API is easy to implement.

FAQs

Package last updated on 23 Feb 2013

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc