{"id":22616313,"url":"https://github.com/xpepermint/etcd-grpc","last_synced_at":"2025-04-11T12:23:40.389Z","repository":{"id":57230677,"uuid":"91389500","full_name":"xpepermint/etcd-grpc","owner":"xpepermint","description":"A gRPC based etcd client for NodeJS targeting etcd V3.","archived":false,"fork":false,"pushed_at":"2023-02-10T03:16:06.000Z","size":216,"stargazers_count":22,"open_issues_count":4,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-21T18:01:35.470Z","etag":null,"topics":["api","client","etcd","grpc","nodejs","v3"],"latest_commit_sha":null,"homepage":null,"language":"Protocol Buffer","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xpepermint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2017-05-15T22:12:59.000Z","updated_at":"2024-06-10T01:33:27.000Z","dependencies_parsed_at":"2024-12-08T19:12:11.652Z","dependency_job_id":"8d8a2a73-4574-410c-a4e6-b4d81aab4851","html_url":"https://github.com/xpepermint/etcd-grpc","commit_stats":{"total_commits":27,"total_committers":1,"mean_commits":27.0,"dds":0.0,"last_synced_commit":"0f65f88ba287b6d27e696ebcd9ab36df27e203be"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpepermint%2Fetcd-grpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpepermint%2Fetcd-grpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpepermint%2Fetcd-grpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpepermint%2Fetcd-grpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xpepermint","download_url":"https://codeload.github.com/xpepermint/etcd-grpc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248401388,"owners_count":21097328,"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":["api","client","etcd","grpc","nodejs","v3"],"created_at":"2024-12-08T19:12:06.193Z","updated_at":"2025-04-11T12:23:40.368Z","avatar_url":"https://github.com/xpepermint.png","language":"Protocol Buffer","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Build Status](https://travis-ci.org/xpepermint/etcd-grpc.svg?branch=master)\u0026nbsp;[![NPM Version](https://badge.fury.io/js/etcd-grpc.svg)](https://badge.fury.io/js/etcd-grpc)\u0026nbsp;[![Dependency Status](https://gemnasium.com/xpepermint/etcd-grpc.svg)](https://gemnasium.com/xpepermint/etcd-grpc)\n\n# [etcd](https://github.com/coreos/etcd)-[grpc](http://www.grpc.io/)\n\n\u003e A gRPC based etcd client for NodeJS targeting etcd V3.\n\n[Etcd](https://github.com/coreos/etcd) is a distributed reliable key-value store for the most critical data of a distributed system.\n\nThis NPM package provides a high performance [gRPC](http://www.grpc.io/) based promisified clients for [Etcd V3](https://github.com/coreos/etcd). It's open-source and it's written with  [TypeScript](https://www.typescriptlang.org).\n\nThe source code is available on [GitHub](https://github.com/xpepermint/etcd-grpc) where you can also find our [issue tracker](https://github.com/xpepermint/etcd-grpc/blob/master/issues).\n\n## Installation\n\nRun the command below to install the package.\n\n```\nnpm install --save etcd-grpc\n```\n\n## Getting Started\n\nBefore you start make sure that [etcd](https://github.com/coreos/etcd) is running on your local machine. Code snippets below expect that [etcd](https://github.com/coreos/etcd) is listening locally on the default port `2379`. To make the code clean, the examples are written in [TypeScript](https://www.typescriptlang.org/).\n\n### Initialization\n\n[Etcd](https://github.com/coreos/etcd) API consists of multiple [gRPC](http://www.grpc.io/) services. This package provides all these functionalities through a unified API.\n\nYou start by initializing a new client.\n\n```ts\nimport { Etcd } from \"etcd-grpc\";\n\nconst client = new Etcd();\n```\n\n### KV Service\n\nThe `KV` etcd service provides the API for reading, updating and deleting keys stored in etcd.\n\nWe can set the `name` key with value `John` as show below. Note that `key` and `value` must be of type `Buffer`.\n\n```ts\nclient.put({\n  key: new Buffer(\"name\"),\n  value: new Buffer(\"John\"),\n}).then((res) =\u003e {\n  console.log(res);\n});\n```\n\nThe connection to the `etcd` server can sometimes fail thus the performing commands can fail. A command will throw an error in case of connectivity problem which we can catch and then reconnect the client manually.\n\n```ts\nimport { getErrorKind, ErrorKind } from \"etcd-grpc\";\n\npromise.catch((err) =\u003e {\n  if (getErrorKind(err) === ErrorKind.CONNECTION_FAILED) {\n    client.reconnect(); // reconnect the client to the next available endpoint (round-robin style)\n    client.put({ ... }); // try-again code\n  } else {\n    throw err;\n  }\n});\n```\n\nWe can read one or many keys from the server using the `range` method. In the following example we retrieve a single key `name`.\n\n```ts\nclient.range({\n  key: new Buffer(\"name\"),\n}).then((res) =\u003e {\n  console.log(res);\n});\n```\n\nThere are some parts of etcd that could represent an endless source of confusion. Etcd stores keys in a sequence and there is a special key `\\0` which you can use to target the first or the last key in the store.\n\n```ts\nclient.range({\n  key: new Buffer(\"\\0\"), // first key\n  rangeEnd: new Buffer(\"\\0\"), // last key\n}).then((res) =\u003e {\n  console.log(res);\n});\n```\n\nAnother trick is that if you set `rangeEnd` to the `key` plus one byte, the etcd will read keys from `key` to the last key prefixed with `key` (all keys of a directory). This means that if the `key` name is `/aaa`, then to get the rest of the keys of that prefix, we need to set `rangeEnd` to `aab`. You can use the [incstr](https://www.npmjs.com/package/incstr) NPM module to increment strings or check the [Stackoverflow](https://stackoverflow.com/q/38352497/132257) page.\n\n```ts\nclient.range({\n  key: new Buffer(\"name/aaa\"), // start key\n  rangeEnd: new Buffer(\"name/aab\"), // get all keys `name/{something}` from `name/aaa`\n}).then((res) =\u003e {\n  console.log(res);\n});\n```\n\nKeys can be deleted from the server using the `rangeDelete` method. In the following example we delete a single key `name`.\n\n```ts\nclient.rangeDelete({\n  key: new Buffer(\"name\"),\n}).then((res) =\u003e {\n  console.log(res);\n});\n```\n\nWe can also perform multiple operations in transaction using the `txn` method. The following example sets the `name` key to `bar` if that key already exists with a value set to `foo`.\n\n```js\nimport { CompareResult, CompareTarget } from \"etcd-grpc\";\n\nclient.txn({\n  compare: {\n    result: CompareResult.EQUAL, // must be equal to\n    target: CompareTarget.VALUE, // check the value\n    key: new Buffer(\"name\"), // key name\n    value: new Buffer(\"foo\"), // key value\n  },\n  success: [{ // run these operations if the `compare` successeeds\n    requestPut: {\n      key: new Buffer(\"name\"),\n      value: new Buffer(\"bar\"),\n    }\n  }],\n  failure: [{ // run these operations if the `compare` fails\n    requestPut: {\n      key: new Buffer(\"name\"),\n      value: new Buffer(\"foo\"),\n    }\n  }],\n}).then((res) =\u003e {\n  console.log(res);\n});\n```\n\nThere's more so please use TypeScript or check the [source files](https://github.com/xpepermint/etcd-grpc/blob/master/src/lib/rpc.ts).\n\n### Lease Service\n\nThe `Lease` service provides an interface for managing keys TTL. We can use that to set the automatic expiration for one or multiple keys. The following example shows how to set a key which is automatically removed after 10s.\n\n```js\nclient.leaseGrant({\n  ttl: 5,\n  id: 100\n}).then(({ id }) =\u003e {\n  return client.put({\n    key: new Buffer(\"name\"),\n    value: new Buffer(\"John\"),\n    lease: id, // attach this key to lease\n  });\n});\n```\n\nThere's more so please use TypeScript or check the [source files](https://github.com/xpepermint/etcd-grpc/blob/master/src/lib/rpc.ts).\n\n### Watch Service\n\nThe `Watch` service allows us to connect to the `etcd` server and listen for changes. The example below shows how to quickly setup a watcher.\n\n```js\nconst watcher = client.createWatcher();\nwatcher.on(\"data\", console.log);\nwatcher.on(\"finish\", console.log);\nwatcher.on(\"end\", console.log);\nwatcher.on(\"close\", console.log);\nwatcher.on(\"error\", console.log);\nwatcher.watch({ // watch the `name` key\n  key: new Buffer(\"name\"),\n});\n```\n\nThe `watch()` command can be called multiple times. It will automatically cose the previous watch request. This is handy when handling a reconnect.\n\n```ts\nimport { getErrorKind, ErrorKind } from \"etcd-grpc\";\n\nwatcher.on(\"error\", (err) =\u003e {\n  if (getErrorKind(err) === ErrorKind.CONNECTION_FAILED) {\n    client.reconnect(); // reconfigure the client\n    watcher.watch({ ... }); // start watching through reconfigured client\n  }\n});\n```\n\nWatcher can be closed by calling the `close()` method.\n\nThere's more so please use TypeScript or check the [source files](https://github.com/xpepermint/etcd-grpc/blob/master/src/lib/watch.ts).\n\n## Related Packages\n\n* [etcd3](https://github.com/WatchBeam/etcd3)\n* [node-etcd3](https://github.com/CitySim/node-etcd3)\n\n## License (MIT)\n\n```\nCopyright (c) 2016+ Kristijan Sedlak \u003cxpepermint@gmail.com\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated modelation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpepermint%2Fetcd-grpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxpepermint%2Fetcd-grpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpepermint%2Fetcd-grpc/lists"}