New Package Monster

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    Consul Client

    A client for Hashicorp Consul written in TypeScript.

    This library currently has clients to support the Consul KV API and the Consul Catalog API.


    $ npm install --save @creditkarma/consul-client

    K/V Store

    The K/V store provides a simple JS API for getting values in and out of Consul. This API is primarily exposed through the KvStore class.

    import { KvStore, IKey, Observer } from '@creditkarma/consul-client'
     * Instantiate KvStore with location of Consul, default is localhost:8500.
     * The argument is actually an array of locations in order to support fail over.
    const kvStore: KvStore = new KvStore([ 'http://localhost:8500' ])


    The KvStore reads, writes and deletes values with Consul based on IKey objects. These are objects with one required property and one optional property. The required property is path. The path is the key name to look up. The optional property is dc. The dc is the datacenter to read from. Per the Consul docs this will default to the datacenter of the agent being queried, specified by the host address.

    // Set value for key
    kvStore.set({ path: 'key', dc: 'dc1' }, 'test').then((success: boolean) => {
      if (success) {
        // write was successful
    // Get current value of key
    kvStore.get({ path: 'key', dc: 'dc1' }).then((val: string) => {
      // val === 'test'
    // Watch a key for value changes{ path: 'key', dc: 'dc1' }).onValue((val: string) => {
      // runs anytime the value changes, initially fires with current value
    // Stop watching a value
    kvStore.unwatch({ path: 'key', dc: 'dc1' })
    // Delete key from consul
    kvStore.delete({ path: 'key', dc: 'dc1' }).then((success: boolean) => {
      if (success) {
        // delete was successful


    An Observer is the object returned from a call to watch.

    It has five public methods:

    const observer: Observer<string> ={ path: 'key', dc: 'dc1' })
    observer.onValue((val: string) => {
        // runs anytime the value changes, initially fires with current value
    observer.onError((err: Error) => {
        // runs anytime there is an error updating the value.
        // depending on the error the library may continue watching the key.
    observer.current() // Returns the current value
    observer.previous() // Returns the previous value
    observer.destroy() // Nulls out all internal state
    // Get the current value, returns null if no value
    const currentVal: string | null = observer.current()
    // Get the previous value, returns null in no previous value
    const previousVal: string | null = observer.previous()

    Request Options

    We use Request as our underlying HTTP client. As such you can pass options through to Request to customize the HTTP request for your environment. This can be done both when instantiating a new KvStore or when making a request.

    const kvStore: KvStore = new KvStore([ 'http://localhost:8500' ], { headers: { ... } })
    kvStore.get({ path: 'key' }, { headers: { ... } })

    The options given to the KvStore constructor are used on every request. Options given to a method are only used for that request. Options passed to a request method are deep merged with the instance options before performing the request.

    Available Options


    The Catalog API allows you to discover other assets registered with your Consul instance. This is useful for service discovery.

    import { Catalog } from '@creditkarma/consul-client'
     * Instantiate Catalog with location of Consul, default is localhost:8500
     * Like KvStore the Catalog supports fail over by providing a list of addresses.
    const catalog: Catalog = new Catalog([ 'http://localhost:8500' ])

    API Overview

    // List all nodes registered with Consul
    catalog.listNodes().then((res: Array<INodeDescription>) => {
        // Do something
    // List all services registered with Consul
    catalog.listServices().then((res: IServiceMap) => {
        // Do something
    // List all nodes registered with a given service
    catalog.listNodesForService('service-name').then((res: IServiceMap) => {
        // Do something
    // Get the registered address for a given service
    catalog.resolveAddress('service-name').then((res: string) => {
        // Do something
    // Watch for runtime changes to a service address
    catalog.watchAddress('service-name').onValue((res: string) => {
        // Do something


    For more information about contributing new features and bug fixes, see our Contribution Guidelines. External contributors must sign Contributor License Agreement (CLA)


    This project is licensed under Apache License Version 2.0


    npm i @creditkarma/consul-client

    DownloadsWeekly Downloads






    Unpacked Size

    77.5 kB

    Total Files


    Last publish


    • ouranosskia
    • ck-npm
    • hightimesteddy
    • nnanceck
    • wookiehangover
    • riley-stroud-ck