{"id":20760513,"url":"https://github.com/blueoakjs/bos-couchdb","last_synced_at":"2025-03-11T16:50:15.077Z","repository":{"id":88550874,"uuid":"52110509","full_name":"BlueOakJS/bos-couchdb","owner":"BlueOakJS","description":"Integrate with CouchDB servers from your BlueOakJS project with ease.","archived":false,"fork":false,"pushed_at":"2016-11-01T11:58:12.000Z","size":34,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-10T13:39:22.455Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlueOakJS.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-19T19:17:10.000Z","updated_at":"2017-11-08T16:06:39.000Z","dependencies_parsed_at":"2023-07-16T05:16:21.377Z","dependency_job_id":null,"html_url":"https://github.com/BlueOakJS/bos-couchdb","commit_stats":{"total_commits":37,"total_committers":5,"mean_commits":7.4,"dds":0.4864864864864865,"last_synced_commit":"4e032567ba60245f4893092a95bcf36f1c15e99d"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fbos-couchdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fbos-couchdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fbos-couchdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueOakJS%2Fbos-couchdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlueOakJS","download_url":"https://codeload.github.com/BlueOakJS/bos-couchdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243076664,"owners_count":20232437,"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-11-17T10:13:55.661Z","updated_at":"2025-03-11T16:50:15.033Z","avatar_url":"https://github.com/BlueOakJS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bos-couchdb\n\n[![Build Status](https://travis-ci.org/BlueOakJS/bos-couchdb.svg?branch=master)](https://travis-ci.org/BlueOakJS/bos-couchdb)\n[![npm version](https://img.shields.io/npm/v/bos-couchdb.svg)](https://www.npmjs.com/package/bos-couchdb)\n\nThis is a [CouchDB](https://couchdb.apache.org/) service for [BlueOak Server](https://github.com/BlueOakJS/blueoak-server).\nThe service provides a convenient way of accessing couchdb servers through BlueOak Server.\nUnder the covers the service uses [nano](https://github.com/dscape/nano).\n\n## Installation\n\n```bash\n$ npm install bos-couchdb\n```\n\n## Configuration\n\nThis service can be configured through the _couchdb_ field of the BlueOak Server config.\n\n### Connections\n\nConnections are named based on key specified in the `connections` section of the couchdb config block.\nThe configuration below defines two connections, one to a remote Cloudant server named _cloudant_ and another to a local couchdb server name _local_.\n\n### Databases\n\nEach connection can include on more databases defined in the `databases` field of the connection.\nThe key used will correspond to the name of an actual database on the couchdb server.\nThe configuration below defines two databases: _profiles_ belonging to the cloudant connection, and _devices_ belonging to the local connection.\n\n```json\n\"couchdb\": {\n  \"connections\": {\n    \"cloudant\": {\n      \"url\": \"https://example.cloudant.com/\",\n      \"username\": \"foo\",\n      \"password\": \"passw0rd\",\n      \"databases\": {\n        \"profiles\": {}\n      }\n    },\n    \"local\": {\n      \"url\": \"http://127.0.0.1:5984/\",\n      \"databases\": {\n        \"devices\": {}\n      }\n    }\n  }\n}\n```\n\n### Scoped Config Options\n\nScoped config are options that can be set on the root couchdb object, the connection, or the database.\nThe database-specific value has precedence over the connection-specific value.\nThe connection-specific value has precedence over the root value.\n\nThis allows the definition of global values that can be overridden as desired.\n\nValid options are:\n\n* *validateConnection* (default `true`) - verify the ability to connect to the database when the server starts.\n* *createDatabase* (default `false`) - attempt to create the database if it doesn't exist when the server starts.\n* *updateDesigns* (default `false`) - attempt to update the (changed) designs when the server starts.\n\n## Managing Views\n\n`bos-couchdb` can be used to update views (design documents) based on the content of the `couchdb` directory in your BOS project.\nThis makes it easier to keep these designs local to your project, in source control, as well as simplifying and standardizing their installation/update on the server(s) your BOS server connects to in every environment.\nYou can configure `bos-couchdb` to update any changed designs on startup by setting the *updateDesigns* config option, or on any event by calling the `updateDatabases` function.\n\n### `couchdb/`\n\nDesigns to be mannaged by `bos-couchdb` should be placed in a tree structure in the `couchdb` directory that defines to what database they apply.\n\ne.g.:\n```\n    couchdb/\n        conn1/\n            dba/\n                designx.js\n                designy.js\n            dbb/\n                designz.js\n        conn2/\n            dbc/\n                designp.js\n            dbd/\n                designq.js\n```\n\ni.e. the design implementation for a given view will be in a BOS project at: `couchdb/$conn_name/$db_name/$design_name.js`\n\n### Sturcture of Design Documents\n\nThe design documents to be used to update the views, either on startup with the *updateDesigns* option, or on-demand with the `updateDesigns` function, need to:\n\n1. export an object with a key `views`\n2. that contains an object named for of every view to be managed/updated\n3. which has `toString()`'d functions named `map` and `reduce`\n\ne.g., `couchdb/conn1/dba/designx.js`:\n```js\nmodule.exports = {\n  views: {\n    'ExampleView': {\n      map: (function (doc) {\n        if (!(doc.event === 'seenAnnouncement' || doc.event === 'seenBlog')) {\n          emit([doc.userId, doc.campaignId], {\n            timestamp: doc.timestamp, \n            event: doc.event\n          });\n        }\n      }).toString(),\n      reduce: (function (keys, values, rereduce) {\n        // identicial implementation for reduce and rereduce\n        values.sort(function (a, b) {\n          return b.timestamp - a.timestamp;\n        });\n        return (values[0].event === 'resetPreferences') ? null : values[0];\n      }).toString()\n    }\n  }\n};\n```\n\n(Probably other fields from the [CouchDB design doc format](http://guide.couchdb.org/draft/design.html) can be include in the export -\nif you do so and confirm it works, please submit a pull request to update the docs (and tests - pretty please).)\n\n## Usage\n\nThe bos-couchdb service can be injected into services or handlers through a `bosCouchdb` parameter on the init method.\n\n```js\nexports.init = function(config, logger, bosCouchdb) {\n  ...\n}\n```\n\n### getConnection(connectionName)\n\nThe `getConnection` function will return a named connection where _connectionName_ corresponds to a connection specified in the configuration.\nThe nano [database](https://github.com/dscape/nano#database-functions) functions can be used on the connection object.\n\n```js\nvar conn = bosCouchdb.getConnection('local');\nconn.list(function(err, results) {\n  //results is a list of databases on the connection\n});\n```\n\n### get(dbName) (getDatabase(dbName))\n\nThe `get` function will return a database where dbName corresponds to a database defined in the configuration.\nThe nano [document](https://github.com/dscape/nano#document-functions) functions can be used on the db object.\n\n```js\nvar profilesDb = bosCouchdb.get('profiles');\nprofilesDb.get('foo' /*doc id*/, function(err, body) {\n  if (!err)\n    console.log(body);\n});\n```\n\nSince it's possible that more than one connection will share a database name, the database name can be prefixed with the connection name.\nThis will avoid any possible ambiguity in looking up a database.\n\n```js\nvar profilesDb = bosCouchdb.get('cloudant:profiles');\nvar devicesDb = bosCouchdb.get('local:devices');\n```\n\n### updateDesigns([designPaths], callback)\n\nThe `updateDesigns` function takes an optional array of paths to design names, e.g.:\n```js\n['conn1.dba.designx', 'conn2.dbd.designq']\n``` \nwhich would cause only the designs at `couchdb/conn1/dba/designx.js` and `couchdb/conn2/dbd/designq.js` to be updated (if changed).\n\nBy default, if the `designs` parameter is not included, all designs will be updated (if changed).\n\nThe `updateDesigns` function will not change the design in the database if the local version `_.isEqual()` to the design installed on the CouchDB server.\n\n**N.B.**: the design docs are read once at startup\n\n### updateDesign(dbName, designName, designDoc, callback)\n\nThe `updateDesign` function allows you to pass an arbitrary design document (`designDoc` - which should be an object that follows the CouchDB design document format) and have it applied to a given database design (`designName` in database `dbName` - which, like `get()`, is an optionally connection qualified database name).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueoakjs%2Fbos-couchdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblueoakjs%2Fbos-couchdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueoakjs%2Fbos-couchdb/lists"}