@creditkarma/consul-client
    TypeScript icon, indicating that this package has built-in type declarations

    0.8.10 • 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.

    Install

    $ 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' ])

    IKey

    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
    kvStore.watch({ 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
      }
    })

    Observer

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

    It has five public methods:

    const observer: Observer<string> = kvStore.watch({ 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

    Catalog

    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
    })

    Contributing

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

    License

    This project is licensed under Apache License Version 2.0

    Install

    npm i @creditkarma/consul-client

    DownloadsWeekly Downloads

    98

    Version

    0.8.10

    License

    Apache-2.0

    Unpacked Size

    72.6 kB

    Total Files

    50

    Last publish

    Collaborators

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