npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@shahidul_brur/pouchdb-upsert

v2.2.0

Published

PouchDB upsert and putIfNotExists functions

Downloads

3

Readme

PouchDB Upsert

Greenkeeper badge

Build Status

A tiny plugin for PouchDB that provides two convenience methods:

  • upsert() - update a document, or insert a new one if it doesn't exist ("upsert"). Will keep retrying (forever) if it gets 409 conflicts.
  • putIfNotExists() - create a new document if it doesn't exist. Does nothing if it already exists.

So basically, if you're tired of manually dealing with 409s or 404s in your PouchDB code, then this is the plugin for you.

Installation

Browser

bower install pouchdb-upsert

Or download from the dist/ folder and include it after pouchdb.js:

<script src="pouchdb.js"></script>
<script src="pouchdb.upsert.js"></script>

Node.js

npm install pouchdb-upsert

Then attach it to the PouchDB object:

var PouchDB = require('pouchdb');
PouchDB.plugin(require('pouchdb-upsert'));

API

Overview

db.upsert(docId, diffFunc [, callback])

Perform an upsert (update or insert) operation. If you don't specify a callback, then this function returns a Promise.

  • docId - the _id of the document.
  • diffFunc - function that takes the existing doc as input and returns an updated doc.
    • If this diffFunc returns falsey, then the update won't be performed (as an optimization).
    • If the document does not already exist, then {} will be the input to diffFunc.

Note: By design, the goal of this repo is to just provide a handler for synchronized logic. diffFunc must not make asynchronous calls.

Example 1

A doc with a basic counter:

db.upsert('myDocId', function (doc) {
  if (!doc.count) {
    doc.count = 0;
  }
  doc.count++;
  return doc;
}).then(function (res) {
  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}
}).catch(function (err) {
  // error
});

Resulting doc (after 1 upsert):

{
  _id: 'myDocId',
  _rev: '1-cefef1ec19869d9441a47021f3fd4710',
  count: 1
}

Resulting doc (after 3 upserts):

{
  _id: 'myDocId',
  _rev: '3-536ef59f3ed17a181dc683a255caf1d9',
  count: 3
}
Example 2

A diffFunc that only updates the doc if it's missing a certain field:

db.upsert('myDocId', function (doc) {
  if (!doc.touched) {
    doc.touched = true;
    return doc;
  }
  return false; // don't update the doc; it's already been "touched"
}).then(function (res) {
  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}
}).catch(function (err) {
  // error
});

Resulting doc:

{
  _id: 'myDocId',
  _rev: '1-cefef1ec19869d9441a47021f3fd4710',
  touched: true
}

The 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.

Example 3

You can also return a new object. The _id and _rev are added automatically:

db.upsert('myDocId', function (doc) {
  return {thisIs: 'awesome!'};
}).then(function (res) {
  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}
}).catch(function (err) {
  // error
});

Resulting doc:

{
  _id: 'myDocId',
  _rev: '1-cefef1ec19869d9441a47021f3fd4710',
  thisIs: 'awesome!'
}

db.putIfNotExists([docId, ] doc [, callback])

Put 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.

  • docId - the _id of the document. Optional if you already include it in the doc
  • doc - the document to insert. Should contain an _id if docId is not specified

If the document already exists, then the Promise will just resolve immediately.

Example 1

Put a doc if it doesn't exist

db.putIfNotExists('myDocId', {yo: 'dude'}).then(function (res) {
  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}
}).catch(function (err) {
  // error
});

Resulting doc:

{
  _id: 'myDocId',
  _rev: '1-cefef1ec19869d9441a47021f3fd4710',
  yo: 'dude'
}

If you call putIfNotExists multiple times, then the document will not be updated the 2nd, 3rd, or 4th time (etc.).

If 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.

Example 2

You can also just include the _id inside the document itself:

db.putIfNotExists({_id: 'myDocId', yo: 'dude'}).then(function (res) {
  // success, res is {rev: '1-xxx', updated: true, id: 'myDocId'}
}).catch(function (err) {
  // error
});

Resulting doc (same as example 1):

{
  _id: 'myDocId',
  _rev: '1-cefef1ec19869d9441a47021f3fd4710',
  yo: 'dude'
}

Breaking changes

  • 2.0.0: breaks compatibility with PouchDB <4.0.1, see #9 for details.

Building

npm install
npm run build

Testing

In Node

This will run the tests in Node using LevelDB:

npm test

You can also check for 100% code coverage using:

npm run coverage

If you have mocha installed globally you can run single test with:

TEST_DB=local mocha --reporter spec --grep search_phrase

The TEST_DB environment variable specifies the database that PouchDB should use (see package.json).

Automated browser tests in PhantomJS

npm run test-browser

Debugging in the browser

npm run test-local