etcd3

library0.12.0jsnpmunverified

The `etcd3` library provides a robust, production-ready Node.js client for the etcd v3 API, which is based on Protocol Buffers. Currently at stable version `1.1.2`, the project demonstrates an active release cadence with frequent patch and minor updates, typically every few weeks to months. Key differentiators include comprehensive features such as intelligent load balancing, resilient fault handling with automatic reconnections (leveraging Cockatiel), atomic transactions, Software Transactional Memory (STM), high-level query builders, sophisticated lease management, real-time watchers, user and role administration, and leader election mechanisms. It also offers full type-safety for TypeScript users, ensuring a robust development experience, and is maintained by Microsoft.

database

npm install etcd3

github ↗package ↗

INSTALL

IMPORT

SIG · ETCD3

etcd3

databasejavascriptv0.12.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Etcd3

✓ import { Etcd3 } from 'etcd3';

✗ const { Etcd3 } = require('etcd3');

While CommonJS `require` might work in older Node.js versions, `etcd3` officially supports Node.js >=16 and ships TypeScript types, favoring ESM `import` for modern usage.

IOptions

✓ import type { IOptions } from 'etcd3';

✗ import { IOptions } from 'etcd3';

This is a TypeScript interface for configuration options; use `import type` to prevent accidental runtime imports and ensure cleaner bundling.

Lease

✓ import { Lease } from 'etcd3';

✗ const Lease = require('etcd3').Lease;

Specific helper classes like `Lease`, `WatchBuilder`, `Election`, and `ComparatorBuilder` are named exports.

This example initializes an `etcd3` client, connects to an etcd server, demonstrates putting and getting a key-value pair, querying keys with a prefix, and finally deleting all keys. It includes basic error handling and uses `ETCD_ADDR` for host configuration.

import { Etcd3 } from 'etcd3'; const client = new Etcd3({ hosts: process.env.ETCD_ADDR ?? '127.0.0.1:2379' // Default etcd address }); (async () => { try { console.log('Putting key "foo" with value "bar"...'); await client.put('foo').value('bar'); console.log('Key "foo" put successfully.'); const fooValue = await client.get('foo').string(); console.log('Retrieved "foo" value:', fooValue); console.log('Fetching all keys starting with "f"...'); const allFValues = await client.getAll().prefix('f').keys(); console.log('All keys starting with "f":', allFValues); console.log('Deleting all keys...'); await client.delete().all(); console.log('All keys deleted.'); } catch (error) { console.error('An error occurred:', error.message); } finally { client.close(); // Important to close the client connection } })();

Debug

Known issues

gotchaA race condition in `Host.resetAllServices` could lead to unexpected behavior during service resets.

fix

Upgrade to `etcd3@1.1.2` or newer to incorporate the fix.

affects: <1.1.2

gotchaUser-defined errors within watcher event listeners could cause backoffs in the underlying gRPC stream, potentially leading to connection issues or missed events.

fix

Ensure all watcher event listener callbacks are robustly error-handled. Upgrade to `etcd3@1.1.0` or newer, which includes a fix to prevent this from affecting the underlying stream.

affects: <1.1.0

gotchaTypeScript typings for `Namespace.get(key)` incorrectly disallowed Buffer values, leading to type errors when attempting to retrieve binary data.

fix

Upgrade to `etcd3@1.1.0` or newer for correct Buffer typings. For older versions, type assertions might be necessary, but this is not recommended.

affects: <1.1.0

gotchaIncompatible TypeScript types with the `cockatiel` dependency could cause compilation issues in projects using strict type checking.

fix

Upgrade to `etcd3@1.0.2` or newer, which includes an updated `cockatiel` version resolving these type conflicts.

affects: <1.0.2

gotchaRunning the official test suite or connecting to a non-default etcd server requires a running etcd instance and proper configuration via the `ETCD_ADDR` environment variable.

fix

Ensure an etcd server is running and accessible. Set `export ETCD_ADDR=localhost:2379` (or your etcd host:port) before running applications or tests that connect to etcd.

affects: >=1.0.0

Errors

Common errors & fixes

Error: 14 UNAVAILABLE: failed to connect to all addresses

The etcd server is not running, is inaccessible from the client, or the configured host/port is incorrect.

fix

Verify that your etcd server is running and listening on the expected host and port. Ensure the `ETCD_ADDR` environment variable or the `hosts` option in the `Etcd3` client constructor is correctly set to your etcd endpoint (e.g., '127.0.0.1:2379').

TypeError: Etcd3 is not a constructor

Attempting to use `const client = new Etcd3();` with CommonJS `require` syntax when `Etcd3` is primarily designed for ES Modules or when the import is incorrect.

fix

When using ES Modules (type: 'module' in package.json or .mjs files), use `import { Etcd3 } from 'etcd3';`. If using CommonJS, ensure your environment properly handles the module export or consider using `require('etcd3').Etcd3` if applicable, although ESM is preferred.

Upgrade

Version history

0.12.0latest on npm

Audit

Dependencies

cockatielrequiredProvides fault handling and reconnection capabilities, as indicated by fixes related to its TypeScript types.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/microsoft/etcd3 ↗

packagehttps://www.npmjs.com/package/etcd3 ↗