{"id":13555373,"url":"https://github.com/pouchdb-community/socket-pouch","last_synced_at":"2025-12-28T04:32:54.631Z","repository":{"id":30285734,"uuid":"33837319","full_name":"pouchdb-community/socket-pouch","owner":"pouchdb-community","description":"PouchDB and CouchDB over WebSockets, using Engine.io","archived":false,"fork":false,"pushed_at":"2017-05-29T08:50:53.000Z","size":1293,"stargazers_count":205,"open_issues_count":13,"forks_count":45,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-04-24T19:04:05.015Z","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-community.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-04-12T22:57:53.000Z","updated_at":"2022-07-03T11:21:26.000Z","dependencies_parsed_at":"2022-07-13T08:11:03.862Z","dependency_job_id":null,"html_url":"https://github.com/pouchdb-community/socket-pouch","commit_stats":null,"previous_names":["nolanlawson/socket-pouch"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fsocket-pouch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fsocket-pouch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fsocket-pouch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouchdb-community%2Fsocket-pouch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pouchdb-community","download_url":"https://codeload.github.com/pouchdb-community/socket-pouch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246965549,"owners_count":20861889,"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-01T12:03:10.732Z","updated_at":"2025-12-28T04:32:49.606Z","avatar_url":"https://github.com/pouchdb-community.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","others"],"sub_categories":[],"readme":"socket-pouch [![Build Status](https://travis-ci.org/nolanlawson/socket-pouch.svg)](https://travis-ci.org/nolanlawson/socket-pouch)\n=====\n\n```js\n// This pouch is powered by web sockets!\nvar db = new PouchDB('mydb', {adapter: 'socket', url: 'ws://localhost:80'});\n```\n\nAdapter plugin that proxies all PouchDB API calls to another PouchDB running on the server in Node.js. The communication mechanism is [Engine.io](https://github.com/Automattic/engine.io), the famous core of [Socket.io](http://socket.io/).\n\nThis means that instead of syncing over HTTP, socket-pouch syncs over WebSockets. Thanks to Engine.io, it falls back to XHR polling in browsers that don't support WebSockets.\n\nThe socket-pouch library has two parts:\n\n* **A Node.js server**, which can create local PouchDBs or proxy to a remote CouchDB.\n* **A JavaScript client**, which can run in Node.js or the browser.\n\nThis adapter passes [the full PouchDB test suite](https://travis-ci.org/nolanlawson/socket-pouch). It requires PouchDB 5.0.0+.\n\nUsage\n---\n\n    $ npm install socket-pouch\n\n#### Server\n\n```js\nvar socketPouchServer = require('socket-pouch/server');\n\nsocketPouchServer.listen(80);\n```\n\n#### Client\n\n##### In the browser\n    \nWhen you `npm install socket-pouch`, the client JS file is available at `node_modules/socket-pouch/dist/socket-pouch.client.js`. Or you can just download it from Github above.\n\nThen include it in your HTML, after PouchDB:\n\n```html\n\u003cscript src=\"pouchdb.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"socket-pouch.client.js\"\u003e\u003c/script\u003e\n```\n\nThen you can create a socket-powered PouchDB using:\n\n```js\nvar db = new PouchDB('mydb', {\n  adapter: 'socket',\n  url: 'ws://localhost:80'\n});\n```\n\n##### In Node.js/Browserify\n\nThe same rules apply, but you have to notify PouchDB of the new adapter:\n\n```js\nvar PouchDB = require('pouchdb');\nPouchDB.adapter('socket', require('socket-pouch/client'));\n```\n\nAPI\n----\n\n### Server\n\n```js\nvar socketPouchServer = require('socket-pouch/server');\n\nsocketPouchServer.listen(80, {}, function () {\n  // server started\n});\n```\n\n#### socketPouchServer.listen(port [, options] [, callback])\n\n##### Arguments\n\n* **port**: the port to listen on. You should probably use 80 or 443 if you plan on running this in production; most browsers are finicky about other ports. 8080 may work in Chrome during debugging.\n* **options**: (optional) options object\n  * **remoteUrl**: tells socket-pouch to act as a proxy for a remote CouchDB at the given URL (rather than creating local PouchDB databases)\n  * **pouchCreator**: alternatively, you can supply a custom function that takes a string and returns any PouchDB object however you like. (See examples below.) \n  * **socketOptions**: (optional) options passed verbatim to Engine.io. See [their documentation](https://github.com/Automattic/engine.io/#methods) for details.\n* **callback**: (optional) called when the server has started\n\nCreate a server which creates local PouchDBs, named by the user and placed in the current directory:\n\n```js\nsocketPouchServer.listen(80, {}, function () {\n  console.log('server started!');\n});\n```\n\nCreate a server which acts as a proxy to a remote CouchDB (or CouchDB-compliant database):\n\n```js\nsocketPouchServer.listen(80, {\n  remoteUrl: 'http://localhost:5984'\n});\n```\n\nSo e.g. when the user requests a database called 'foo', it will use a remote database at `'http://localhost:5984/foo'`. Note that authentication is not handled, so you may want the `pouchCreator` option instead.\n\nCreate a MemDOWN-backed PouchDB server:\n\n```js\nsocketPouchServer.listen(80, {\n  pouchCreator: function (dbName) {\n    return new PouchDB(dbName, {\n      db: require('memdown')\n    });\n  }\n});\n```\n\nNote that this `dbName` is supplied by the client ver batim, meaning **it could be dangerous**. In the example above, everything is fine because MemDOWN databases can have any string as a name.\n\nAlternatively, your `pouchCreator` can return a `Promise` if you want to do something asynchronously, such as authenticating the user. In that case you must wrap the object in `{pouch: yourPouchDB}`:\n\n```js\nsocketPouchServer.listen(80, {\n  pouchCreator: function (dbName) {\n    return doSomethingAsynchronously().then(function () {\n      return {\n        pouch: new PouchDB('dbname')\n      };\n    });\n  }\n});\n```\n\n### Client\n\n```js\nvar db = new PouchDB({\n  adapter: 'socket',\n  name: 'mydb',\n  url: 'ws://localhost:80',\n  socketOptions: {}\n});\n```\n\nThe `name` and `url` are required and must point to a valid `socketPouchServer`. The `socketOptions`, if provided, are passed ver batim to Engine.io, so refer to [their documentation](https://github.com/Automattic/engine.io-client/#nodejs-with-certificates) for details.\n\n### Replication\n\nThe `db` object acts like a PouchDB that communicates remotely with the `socketPouchServer` In other words, it's analogous to a PouchDB created like `new PouchDB('http://localhost:5984/mydb')`.\n\nSo you can replicate using the normal methods:\n\n```js\nvar localDB = new PouchDB('local');\nvar remoteDB = new PouchDB({adapter: 'socket', name: 'remote', url: 'ws://localhost:80'});\n\n// replicate from local to remote\nlocalDB.replicate.to(remoteDB);\n\n// replicate from remote to local\nlocalDB.replicate.from(remoteDB);\n\n// replicate bidirectionally\nlocalDB.sync(remoteDB);\n```\n\nFor details, see the official [`replicate()`](http://pouchdb.com/api.html#replication) or [`sync()`](http://pouchdb.com/api.html#sync) docs.\n\n### Remote API\n\n```js\nvar remoteDB = new PouchDB({adapter: 'socket', name: 'remote', url: 'ws://localhost:80'});\n```\n\nYou can also talk to this `remoteDB` as if it were a normal PouchDB. All the standard methods like `info()`, `get()`, `put()`, and `putAttachment()` will work. The [Travis tests](https://travis-ci.org/nolanlawson/socket-pouch) run the full PouchDB test suite.\n\n### Debugging\n\nSocketPouch uses [debug](https://github.com/visionmedia/debug) for logging. So in Node.js, you can enable debugging by setting a flag:\n\n```\nDEBUG=pouchdb:socket:*\n```\n\nIn the browser, you can enable debugging by using PouchDB's logger:\n\n```js\nPouchDB.debug.enable('pouchdb:socket:*');\n```\n\nQ \u0026 A\n---\n\n#### How does it communicate?\n\nSocketPouch communicates using the normal Engine.io APIs like `send()` and `on('message')`.\n\nNormally it sends JSON text data, but in the case of attachments, binary data is sent. This means that SocketPouch is actually more efficient than regular PouchDB replication, which (as of this writing) uses base64-string encoding to send attachments between the client and server.\n\n#### Does it work in a web worker or service worker?\n\nUnfortuantely, not at the moment.\n\n#### How is it implemented?\n\nThis is a custom PouchDB adapter. Other examples of PouchDB adapters include the built-in IndexedDB, WebSQL, LevelDB, and HTTP (Couch) adapters, as well as a partial adapter written for [pouchdb-replication-stream](https://github.com/nolanlawson/pouchdb-replication-stream) and [worker-pouch](https://github.com/nolanlawson/worker-pouch), which is a fork of this repo.\n\nChangelog\n---\n\n- 2.0.0\n  - Support for PouchDB 6.0.0, drop support for PouchDB \u003c=5\n- 1.0.0\n  - Initial release\n\nBuilding\n----\n\n    npm install\n    npm run build\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\nRun certain tests:\n```\nGREP=foo npm test\n```\n\n### In the browser\n\nRun `npm run dev` and then point your favorite browser to [http://127.0.0.1:8000/test/index.html](http://127.0.0.1:8000/test/index.html).\n\nThe query param `?grep=mysearch` will search for tests matching `mysearch`.\n\n### Automated browser tests\n\nYou can run e.g.\n\n    CLIENT=selenium:firefox npm test\n    CLIENT=selenium:phantomjs npm test\n\nThis will run the tests automatically and the process will exit with a 0 or a 1 when it's done. Firefox uses IndexedDB, and PhantomJS uses WebSQL.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb-community%2Fsocket-pouch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpouchdb-community%2Fsocket-pouch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouchdb-community%2Fsocket-pouch/lists"}