• Version 2.1.3
  • Published
  • 3 dependencies
  • ISC license


npm i zk-lock
yarn add zk-lock
pnpm add zk-lock


A distributed lock using zookeeper



class ZookeeperLock

class ZookeeperLock extends EventEmitter {}


    constructor(config: ZookeeperLockConfiguration);
    • create a new zk lock

      Parameter config

    property checkLock

    static checkLock: (key: string) => Promise<boolean>;
    • check if a lock exists for a path using the static config

      Parameter key



    property checkLocked

    checkLocked: (key: string) => Promise<boolean>;
    • check if a lock exists, connecting to zk client if not connected

      Parameter key



    property client

    client: zk.Client;

      property connect

      connect: (delay?: number) => Promise<any>;
      • connect underlying zookeeper client, with optional delay

        Parameter delay



      property destroy

      destroy: () => Promise<boolean>;
      • destroy the lock, disconnect and remove all listeners from the 'signal' event emitter



      property disconnect

      disconnect: () => Promise<any>;
      • disconnect zookeeper client, and remove all event listeners from it



      property initialize

      static initialize: (config: any) => void;
      • set static config to use by static helper methods

        Parameter config

      property key

      key: string;

        property lock

        static lock: (key: string, timeout?: number) => Promise<ZookeeperLock>;
        • create a new lock and lock it using the static stored config, with optional timeout

          Parameter key

          Parameter timeout



        property lock

        lock: (key: string, timeout?: number) => Promise<any>;
        • wait for a lock to become free for a given key and acquire it, with an optional timeout upon which the lock will fail. if not currently connected to zookeeper, this will connect, and on timeout, the lock will disconnect from zookeeper

          Parameter key

          Parameter timeout



        property lockFactory

        static lockFactory: () => ZookeeperLock;
        • create a new lock using the static stored config



        property path

        path: string;

          property Signals

          static Signals: { LOST: string; TIMEOUT: string };

            property state

            state: string;

              property States

              static States: {
              ALREADY_LOCKED: string;
              DESTROYED: string;
              ERROR: string;
              LOCKED: string;
              LOCKING: string;
              LOST: string;
              TIMEOUT: string;
              UNLOCKED: string;
              UNLOCKING: string;

                property unlock

                unlock: (destroy?: boolean) => Promise<any>;
                • unlock a lock, removing the key from zookeeper, and disconnecting the zk client and all event listeners. By default this also destroys the lock and removes event listeners on the locks 'signals' event

                  Parameter destroy

                  remove listeners from lock in addition to disconnecting zk client on completion, defaults to true



                class ZookeeperLockAlreadyLockedError

                class ZookeeperLockAlreadyLockedError extends Error {}
                • Error thrown by locking action when config.failImmediate == true when a lock is already locked


                constructor(message: string, path: string);

                  property lockPath

                  lockPath: string;

                    class ZookeeperLockConfiguration

                    class ZookeeperLockConfiguration {}

                      property autoDestroyOnUnlock

                      autoDestroyOnUnlock?: boolean;
                      • when true, all calls to unlock will destroy the lock, detaching all event listeners, in addition to the normal disconnect. defaults to true to reduce the chance of leaky usage

                      property enableTraceLog

                      enableTraceLog?: boolean;
                      • if set to true, set a timeout defaulting to 10 seconds to give status updates on the lock while it is connected to zookeeper, used to help debug working with the locks to detect leaks or what not, visible by launching the app with the environment variable NODE_DEBUG=zk-lock set

                      property failImmediate

                      failImmediate?: boolean;
                      • when true, if the lock is not obtainable immediately, fail with a ZookeeperLockAlreadyLockedError and disconnect or destroy depending on autoDestroyOnUnlock the lock

                      property maxConcurrentHolders

                      maxConcurrentHolders?: number;
                      • allowed number of maximum concurrent holders of a lock, defaults to 1 for traditional lock-like behavior. Note that this value is NOT enforced, it's merely an agreement that all lock clients agree to follow when working with this lock path, but allows using the zookeeper lock for additional cluster orchestration roles like controlling the maximum number of concurrent workers

                      property pathPrefix

                      pathPrefix?: string;
                      • prefix which will be placed in front of all locks created from this lock

                      property retries

                      retries?: number;
                      • milliseconds, dual function parameter, functioning both as zookeeper lock 'reconnect' limit as well as internal zookeeper client retries

                      property serverLocator

                      serverLocator?: Locator;
                      • locators (https://github.com/metamx/locators) compatible zookeeper server locator

                      property sessionTimeout

                      sessionTimeout?: number;
                      • zookeeper client session timeout

                      property spinDelay

                      spinDelay?: number;
                      • milliseconds, dual function parameter, functioning both as zookeeper lock 'reconnect' delay as well as internal zookeeper client spinDelay

                      property traceLogQuietPeriod

                      traceLogQuietPeriod?: number;
                      • milliseconds, the quiet period after a lock is connected until the traceLog will begin reporting long held locks and suspected connection leaks in a more verbose manner

                      property traceLogRefresh

                      traceLogRefresh?: number;
                      • milliseconds, the rate at which debug trace logs are emitted when enableTraceLog is set to true

                      class ZookeeperLockTimeoutError

                      class ZookeeperLockTimeoutError extends Error {}
                      • Error thrown by locking action when blocking wait for lock reaches a timeout period


                      constructor(message: string, path: string, timeout?: number);

                        property lockPath

                        lockPath: string;

                          property timeout

                          timeout?: number;

                            Package Files (2)

                            Dependencies (3)

                            Dev Dependencies (7)

                            Peer Dependencies (0)

                            No peer dependencies.


                            To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                            You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/zk-lock.

                            • Markdown
                            • HTML
                              <a href="https://www.jsdocs.io/package/zk-lock"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>