{"id":19560073,"url":"https://github.com/plotdb/ews","last_synced_at":"2026-02-14T09:04:29.470Z","repository":{"id":63549339,"uuid":"480707749","full_name":"plotdb/ews","owner":"plotdb","description":"elastic websocket","archived":false,"fork":false,"pushed_at":"2025-12-22T11:26:40.000Z","size":1916,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-23T22:41:57.634Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"LiveScript","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/plotdb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-12T07:52:07.000Z","updated_at":"2025-12-22T11:26:03.000Z","dependencies_parsed_at":"2023-11-07T15:32:53.333Z","dependency_job_id":"18bfa623-7a93-4260-bc27-5ca866a53796","html_url":"https://github.com/plotdb/ews","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/plotdb/ews","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fews","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fews/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fews/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fews/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plotdb","download_url":"https://codeload.github.com/plotdb/ews/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fews/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29441111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T07:24:13.446Z","status":"ssl_error","status_checked_at":"2026-02-14T07:23:58.969Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-11T05:05:49.009Z","updated_at":"2026-02-14T09:04:29.435Z","avatar_url":"https://github.com/plotdb.png","language":"LiveScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @plotdb/ews\n\nelastic websocket.\n\n\n## Usage\n\nConstructor options:\n\n - `ws`: websocket object to use. auto-greated if omitted and `url` is derivable.\n - `scheme`: scheme of the URL to use. ignored if `url` or `ws` is provided. default `ws` if omitted\n - `domain`: domain of the URL to use. ignored if `url` or `ws` is provided. `window.location.host` is used if omitted\n - `path`: path of the URL to use. ignored if `url` or `ws` is provided. default `` if omitted.\n - `url`: url for websocket connection.\n   - ignored if `ws` is provided.\n   - derived from `scheme`, `domain` and `path` above if both `ws` and `url` are omitted\n - `scope`: scope of this socket. default ``\n - `pingInterval`: optional. interval between ping. default 60s, minimal 20s.\n\n\nAPI (ews):\n\n - `pipe(scope)`: return a scoped `ews` object piped from this ews object.\n - `ws()`: return the real websocket object used.\n - `ensure()`: ensure connection. return Promise, resolves when connected\n - `disconnect()`: disconnect websocket from server.\n   - return Promise when disconnected.\n - `connect(opt)`: reconnect websocket if disconnected. return a Promise which is resolved when connected.\n   - options:\n     - `retry`: automatically retry if set to true. default true.\n     - `delay`: delay ( in millisecond) before first connection attmpt. default 0\n     - `now`: reset current reconnection attempts and start a new attempt immediately\n - `cancel()`: cancel connection. return Promise, resolves when connection canceled.\n   - reject lderror 1026 if no connection to cancel.\n - `status()`: get connection status. return a integer with following possible values:\n   - `0`: not connected\n   - `1`: connecting\n   - `2`: connected\n - `ping(opt)`: periodically ping remote server (heartbeat) to prevent disconnecting.\n   - `opt` is an object with following field:\n     - `now`: default false. if false, ping message is sent after ping interval;\n              otherwise it will be sent immediately.\n     - `interval: optional. interval of ping. default 60s, minimal 20s.\n - `unping()`: stop ping.\n\nAPI (from original WebSocket):\n\n - `send`\n - `close`\n - `addEventListener`\n - `dispatchEvent`\n - `removeEventListener`\n - `on`: (TBD) used by websocket-json-stream\n\n\n## Events\n\nExcept original WebSocket events, we provide additional events as follows:\n\n - `offline`: when network goes offline, this event is fired.\n    - `close` somehow may not yet fired when `offline` is fired, so this can be used to hint user about a dying socket.\n\n\n## Sharedb\n\nSharedb is bundled in this repo, in following files:\n\n - `dist/sharedb.min.js`: standalone sharedb bundle, expose `sharedb` object.\n - `dist/sdb-client.min.js`: client side sharedb wrapper\n - `dist/sdb-server.min.js`: server side sharedb wrapper\n\n\n### sdb-client\n\nprepare a `ews` object:\n\n      ws = new ews({url: ...});\n\ncreate a sdb-client everytime the ews object (re)connected:\n\n      ws.on(\"open\", function() {\n        sdb = new ews.sdb-client({ws: ws});\n        sdb.connect().then( ... );\n      });\n\nAdditionally, following events are available in sdb-client:\n\n - `close`: socket is closed.\n - `error`: fired when receiving `error` events from sharedb `Doc` or `Connection`.\n   - NOTE please always handle `error` event to keep your doc up to date.\n\n\n### sdb-server\n\nuse `http` and `ws` module to create a WebSocket server ( use `express` as example ):\n\n    sdbServer = require(\"@plotdb/ews/sdb-server\")\n    app = express();\n    server = http.createServer(express());\n    wss = new ws.Server({ server: server });\n    ret = sdb-server({io: {postgres configuration ...} , wss})\n    wss.on(\"connection\", function(ws, req) {\n      /* you can still use the created ws object */\n      var myws = new ews({ws});\n      ...\n    });\n\n\n### Metadata\n\nIf `metadata(opt)` function is provided, it will be called when `commit` hook is triggered with an object including following parameters:\n\n - `m`: the metadata object from sharedb op.\n - `type`: either `readSnapshots` or `submit`.\n - `collection`: target collection.\n - `id`: target doc id. This will be null if there are multiple doc ids - in this case, check `snapshots` instead.\n - `req`: the express request object.\n - `session`: shorthand for `req.session` from `express-session`.\n - `user`: shorthand for `session.user` from `passport`.\n\nedit the `m` field directly to inject necessary metadata. For example, add user id:\n\n    metadata = ({m, user, session, collection, id, snaptshos}) -\u003e m.user = (if user? =\u003e user.key else 0)\n\n\n### Access Control\n\nIf `access` is function provided, it will be called in following hooks:\n\n - `readSnapshots`\n - `submit`\n\n`access(opt)` is called with an object containing following paramters:\n\n - `type`: either `readSnapshots` or `submit`.\n - `collection`: target collection.\n - `id`: target doc id. This will be null if there are multiple doc ids - in this case, check `snapshots` instead.\n - `snapshots`: array of snapshots. Only provided when called by `readSnapshots` hook.\n - `req`: the express request object.\n - `session`: shorthand for `req.session` from `express-session`.\n - `user`: shorthand for `session.user` from `passport`.\n\n`access(opt)` should return a Promise which only resolve when access is granted. By default the returned promise reject a lderror id 1012 error when access is denied.\n\nHere is an example to prevent new document creation: \n\n    access = ({snapshots}) -\u003e\n      if snapshots and !(snapshots.0.id) =\u003e\n        return lderror.reject 1012\n      return Promise.resolve!\n\nPlease note that ShareDB logs rejected errors (by recognizing its `stack` attribute) and wrap errors in `{code, message}` format. Consider rejecting a plain lderror object as above example, `@plotdb/ews` will wrap/parse your lderror objects for you so you can receive a correct lderror object in frontend.\n\n\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplotdb%2Fews","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplotdb%2Fews","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplotdb%2Fews/lists"}