{"id":13630403,"url":"https://github.com/pouchdb/upsert","last_synced_at":"2025-04-30T21:09:59.826Z","repository":{"id":25968297,"uuid":"29410246","full_name":"pouchdb/upsert","owner":"pouchdb","description":"PouchDB plugin for upsert() and putIfNotExists() functions","archived":false,"fork":false,"pushed_at":"2021-09-08T23:05:17.000Z","size":31259,"stargazers_count":149,"open_issues_count":19,"forks_count":25,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-30T21:09:39.646Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pouchdb.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}},"created_at":"2015-01-18T00:09:33.000Z","updated_at":"2025-02-08T01:45:41.000Z","dependencies_parsed_at":"2022-08-31T00:01:03.036Z","dependency_job_id":null,"html_url":"https://github.com/pouchdb/upsert","commit_stats":null,"previous_names":["nolanlawson/pouchdb-upsert"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fupsert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fupsert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fupsert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb%2Fupsert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pouchdb","download_url":"https://codeload.github.com/pouchdb/upsert/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251782776,"owners_count":21642987,"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-08-01T22:01:41.370Z","updated_at":"2025-04-30T21:09:59.807Z","avatar_url":"https://github.com/pouchdb.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"PouchDB Upsert\n=====\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/pouchdb/upsert.svg)](https://greenkeeper.io/)\n\n[![Build Status](https://travis-ci.org/pouchdb/upsert.svg)](https://travis-ci.org/pouchdb/upsert)\n\nA tiny plugin for PouchDB that provides two convenience methods:\n\n* `upsert()` - update a document, or insert a new one if it doesn't exist (\"upsert\"). Will keep retrying (forever) if it gets 409 conflicts.\n* `putIfNotExists()` - create a new document if it doesn't exist. Does nothing if it already exists.\n\nSo basically, if you're tired of manually dealing with 409s or 404s in your PouchDB code, then this is the plugin for you.\n\nInstallation\n------\n\n### Browser\n\n```\nbower install pouchdb-upsert\n```\n\nOr download from the `dist/` folder and include it after `pouchdb.js`:\n\n```html\n\u003cscript src=\"pouchdb.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"pouchdb.upsert.js\"\u003e\u003c/script\u003e\n```\n\n### Node.js\n\n```\nnpm install pouchdb-upsert\n```\n\nThen attach it to the `PouchDB` object:\n\n```js\nvar PouchDB = require('pouchdb');\nPouchDB.plugin(require('pouchdb-upsert'));\n```\n\nAPI\n--------\n\n\n### Overview\n\n* [`db.upsert(docId, diffFunc [, callback])`](#dbupsertdocid-difffunc--callback)\n* [`db.putIfNotExists([docId, ] doc [, callback])`](#dbputifnotexistsdocid--doc--callback)\n\n### db.upsert(docId, diffFunc [, callback])\n\nPerform an upsert (update or insert) operation. If you don't specify a `callback`, then this function returns a Promise.\n\n* `docId` - the `_id` of the document.\n* `diffFunc` - function that takes the existing doc as input and returns an updated doc.\n  * If this `diffFunc` returns falsey, then the update won't be performed (as an optimization).\n  * If the document does not already exist, then `{}` will be the input to `diffFunc`.\n\n**Note:** By design, the goal of this repo is to just provide a handler for synchronized logic. ```diffFunc``` must not make asynchronous calls.\n\n##### Example 1\n\nA doc with a basic counter:\n\n```js\ndb.upsert('myDocId', function (doc) {\n  if (!doc.count) {\n    doc.count = 0;\n  }\n  doc.count++;\n  return doc;\n}).then(function (res) {\n  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}\n}).catch(function (err) {\n  // error\n});\n```\n\nResulting doc (after 1 `upsert`):\n\n```js\n{\n  _id: 'myDocId',\n  _rev: '1-cefef1ec19869d9441a47021f3fd4710',\n  count: 1\n}\n```\n\nResulting doc (after 3 `upsert`s):\n\n```js\n{\n  _id: 'myDocId',\n  _rev: '3-536ef59f3ed17a181dc683a255caf1d9',\n  count: 3\n}\n```\n\n##### Example 2\n\nA `diffFunc` that only updates the doc if it's missing a certain field:\n\n```js\ndb.upsert('myDocId', function (doc) {\n  if (!doc.touched) {\n    doc.touched = true;\n    return doc;\n  }\n  return false; // don't update the doc; it's already been \"touched\"\n}).then(function (res) {\n  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}\n}).catch(function (err) {\n  // error\n});\n```\n\nResulting doc:\n\n```js\n{\n  _id: 'myDocId',\n  _rev: '1-cefef1ec19869d9441a47021f3fd4710',\n  touched: true\n}\n```\n\nThe next time you try to `upsert`, the `res` will be `{rev: '1-xxx', updated: false, id: 'myDocId'}`. The `updated: false` indicates that the `upsert` function did not actually update the document, and the `rev` returned will be the previous winning revision.\n\n##### Example 3\n\nYou can also return a new object. The `_id` and `_rev` are added automatically:\n\n```js\ndb.upsert('myDocId', function (doc) {\n  return {thisIs: 'awesome!'};\n}).then(function (res) {\n  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}\n}).catch(function (err) {\n  // error\n});\n```\n\nResulting doc:\n\n```js\n{\n  _id: 'myDocId',\n  _rev: '1-cefef1ec19869d9441a47021f3fd4710',\n  thisIs: 'awesome!'\n}\n```\n\n### db.putIfNotExists([docId, ] doc [, callback])\n\nPut a new document with the given `docId`, if it doesn't already exist. If you don't specify a `callback`, then this function returns a Promise.\n\n* `docId` - the `_id` of the document. Optional if you already include it in the `doc`\n* `doc` - the document to insert. Should contain an `_id` if `docId` is not specified\n\nIf the document already exists, then the Promise will just resolve immediately.\n\n##### Example 1\n\nPut a doc if it doesn't exist\n\n```js\ndb.putIfNotExists('myDocId', {yo: 'dude'}).then(function (res) {\n  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}\n}).catch(function (err) {\n  // error\n});\n```\n\nResulting doc:\n\n```js\n{\n  _id: 'myDocId',\n  _rev: '1-cefef1ec19869d9441a47021f3fd4710',\n  yo: 'dude'\n}\n```\n\nIf you call `putIfNotExists` multiple times, then the document will not be updated the 2nd, 3rd, or 4th time (etc.).\n\nIf it's not updated, then the `res` will be `{rev: '1-xxx', updated: false, id: 'myDocId'}`, where `rev` is the first revision and `updated: false` indicates that it wasn't updated.\n\n##### Example 2\n\nYou can also just include the `_id` inside the document itself:\n\n```js\ndb.putIfNotExists({_id: 'myDocId', yo: 'dude'}).then(function (res) {\n  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}\n}).catch(function (err) {\n  // error\n});\n```\n\nResulting doc (same as example 1):\n\n```js\n{\n  _id: 'myDocId',\n  _rev: '1-cefef1ec19869d9441a47021f3fd4710',\n  yo: 'dude'\n}\n```\n\nBreaking changes\n----\n\n* 2.0.0: breaks compatibility with PouchDB \u003c4.0.1, see [#9](https://github.com/pouchdb/upsert/pull/9) for details.\n\n\nBuilding\n----\n    npm install\n    npm run build\n\n\nTesting\n----\n\n### In Node\n\nThis will run the tests in Node using LevelDB:\n\n    npm test\n\nYou can also check for 100% code coverage using:\n\n    npm run coverage\n\n\nIf you have mocha installed globally you can run single test with:\n```\nTEST_DB=local mocha --reporter spec --grep search_phrase\n```\n\nThe `TEST_DB` environment variable specifies the database that PouchDB should use (see `package.json`).\n\n### Automated browser tests in PhantomJS\n\n    npm run test-browser\n\n### Debugging in the browser\n\n    npm run test-local\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb%2Fupsert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpouchdb%2Fupsert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb%2Fupsert/lists"}