@nolanlawson @daleharvey: I would normally timebomb this by now, but since this is a pretty big change I would like a +1 on the general concept (as described in my first post) first at least. Could one of you look at it?

@marten-de-vries Sorry for not giving this a lookover sooner. Holidays. :)

In general, I like this approach. It renders pouchdb-express-router obsolete, which makes me a lot less nervous, because we don't have to support two codebases.

Just a few suggestions:

1. This is a nit, but JavaScript files should use kebab-case, not snake_case.

2. I feel like the name profile is confusing, due to semantic overload with "profiling" (e.g. for performance). I would prefer the name mode, and instead of custom/complete/core, I would suggest: custom/fullCouchDB/minimumForReplication.

Of course, how confusing this system is will depend on how it's presented in the README. :) I think this is one of those unfortunate cases where the developers could not agree on a single option, so we are creating multiple options and inviting users to try to guess what our thought process was. But I think if we simply explain: "this one's the kitchen sink, it's a full CouchDB-like database, whereas this one is just the minimum you need for replication," then it should be clear.

Also when this is complete, let's deprecate/unpublish express-pouchdb-router and remove it from the Travis tests. @daleharvey do you agree?

Oh, and I also think profileDiff adds unnecessary confusion. Let's just let users use custom and define all the features they want; probably only 0.001% of users will want such a feature anyway. 😛

@nolanlawson Good point about the file names. I'm not particularly attached to any specific names for the new options. minimumForReplication is not an exact description as things like views are included too (everything to pass the PouchDB test suite), but I can't come up with anything better really. Let's go with your suggestions for now.

Custom would still need profileDiff/modeDiff for any customisation to actually be done, though. Maybe the mode would better be called 'nothing' or 'empty' or something similar, since that's what it actually is. Might be confusing though, so for now I would stick with 'custom'. In the end, whatever name it gets, it's something that needs more explaining in README. (Not yet included, I want to change the README file in one go and also include the config and http proxy info at the same time.)

Maybe minimumForPouchDB?

As for profileDiff, I thought with custom you could just enumerate all the modules you wanted to include? I think requiring users to write it all out by hand is fine, rather than diffing it against some other preset.

minimumForPouchDB seems fine to me.

I like the diff concept for cases like 'just add Fauxton' or 'authentication clashes with my own auth mechanism (e.g. because both support http basic auth), just disable express-pouchdb's'. I believe that with those two examples added to the readme, the concept will be clear enough and that it'll be worth it.

But, if those use cases don't sound convincing enough, I guess I don't care enough about them to keep advocating their inclusion further and am ok with scrapping them. If that's the case, I suggest as api instead of mode: 'custom' we could just do mode: ['routes/document', 'routes/db', ...] next to mode: 'minimumForPouchDB'.

Maybe I misunderstood what profileDiff was for. If you think it's the clearest, then let's go with that, but I would probably have to see a README update first to understand how it's supposed to work :).

A concept version of what would be added to the readme. (It's incomplete, but hopefully enough to make a descision on profileDiff, which I renamed to overrideMode here. Examples haven't been run yet):

API

express-pouchdb exports a single function that builds an express application object. Its function signature is:

require('express-pouchdb')([PouchDB[, options]])

• PouchDB: the PouchDB object used to access databases. Optional.
• options: Optional. These options are supported:
  • configPath: a path to the configuration file to use. Defaults to './config.json'.
  • mode: determines which parts of the HTTP API express-pouchdb offers are enabled. There are three values:
    • 'fullCouchDB': enables every part of the HTTP API, which makes express-pouchdb very close to a full CouchDB replacement. This is the default.
    • 'minimumForPouchDB': just exposes parts of the HTTP API that map 1-1 to the PouchDB api. This is the minimum required to make the PouchDB test suite run, and a nice start when you just need an HTTP API to replicate with.
    • 'custom': no parts of the HTTP API are enabled. You can add parts yourself using the opts.overrideMode discussed below.
  • overrideMode: Sometimes the preprogrammed modes are insufficient for your needs, or you chose the 'custom' mode. In that case, you can set this to an object. This object can have the following properties:
    • 'include': a javascript array that specifies parts to include on top of the ones specified by opts.mode. Optional.
    • 'exclude': a javascript array that specifies parts to exclude from the ones specified by opts.mode. Optional.

Examples

// Example 1: builds an HTTP API using all the defaults, and lets it listen on port 5985:
var app = require('express-pouchdb')(require('pouchdb'));
app.listen(5985);

// Example 2: builds an http api that exposes a minimal HTTP interface, but adds Fauxton
// as an extra to debug it.
var app = require('express-pouchdb')({
  mode: 'minimumForPouchDB',
  overrideMode: {
    include: ['fauxton']
  }
});
// when not specifying PouchDB as an argument to the main function, you need to specify
// it like this before requests are routed to ``app``
app.setPouchDB(require('pouchdb'));

// Example 3: builds a full HTTP API but excludes express-pouchdb's authentication logic
// (say, because it interferes with custom authentication logic used in our own express
// app):
var app2 = require('express-pouchdb')(require('pouchdb'), {
  mode: 'fullCouchDB' // specified for clarity. It's the default so not necessary.
  overrideMode: {
    exclude: [
      'routes/authentication',
      // disabling the above, gives error messages which require you to disable the
      // following parts too. Which makes sense since they depend on it.
      'routes/authorization',
      'routes/session'
    ]
  }
});

Looking very good to me. A strong +1, but gonna wait for @daleharvey to second it since it's a big change.

The commit above gets the code up-to-date with everything discussed so far. (snake_case -> kebab-case for files, profile -> mode, profileDiff -> overrideMode, core -> minimumForPouchDB & complete -> fullCouchDB).

Oh, forgot to modify the commit message to use 'mode' instead of 'profile'. That can be fixed when merging.

+1

Merged: 3920710