Logo for jsDocs.io

redlock

  • Version 5.0.0-beta.2
  • Published
  • 81.1 kB
  • 1 dependency
  • MIT license

Install

npm i redlock
yarn add redlock
pnpm add redlock

Overview

A node.js redlock implementation for distributed redis locks

Index

Classes

Interfaces

Type Aliases

Classes

class ExecutionError

class ExecutionError extends Error {}

    constructor

    constructor(message: string, attempts: readonly Promise<ExecutionStats>[]);

      property attempts

      readonly attempts: readonly Promise<ExecutionStats>[];

        property message

        readonly message: string;

          class Lock

          class Lock {}

            constructor

            constructor(
                redlock: Redlock,
                resources: string[],
                value: string,
                attempts: readonly Promise<ExecutionStats>[],
                expiration: number
            );

              property attempts

              readonly attempts: readonly Promise<ExecutionStats>[];

                property expiration

                expiration: number;

                  property redlock

                  readonly redlock: Redlock;

                    property resources

                    readonly resources: string[];

                      property value

                      readonly value: string;

                        method extend

                        extend: (duration: number) => Promise<Lock>;

                          method release

                          release: () => Promise<ExecutionResult>;

                            class Redlock

                            class Redlock extends EventEmitter {}

                            • A redlock object is instantiated with an array of at least one redis client and an optional options object. Properties of the Redlock object should NOT be changed after it is first used, as doing so could have unintended consequences for live locks.

                            constructor

                            constructor(
                                clients: Iterable<any>,
                                settings?: Partial<Settings>,
                                scripts?: {
                                    readonly acquireScript?: string | ((script: string) => string);
                                    readonly extendScript?: string | ((script: string) => string);
                                    readonly releaseScript?: string | ((script: string) => string);
                                }
                            );

                              property clients

                              readonly clients: Set<any>;

                                property scripts

                                readonly scripts: {
                                    readonly acquireScript: { value: string; hash: string };
                                    readonly extendScript: { value: string; hash: string };
                                    readonly releaseScript: { value: string; hash: string };
                                };

                                  property settings

                                  readonly settings: Settings;

                                    method acquire

                                    acquire: (
                                        resources: string[],
                                        duration: number,
                                        settings?: Partial<Settings>
                                    ) => Promise<Lock>;

                                    • This method acquires a locks on the resources for the duration specified by the duration.

                                    method extend

                                    extend: (
                                        existing: Lock,
                                        duration: number,
                                        settings?: Partial<Settings>
                                    ) => Promise<Lock>;

                                    • This method extends a valid lock by the provided duration.

                                    method quit

                                    quit: () => Promise<void>;

                                    • This method runs .quit() on all client connections.

                                    method release

                                    release: (lock: Lock, settings?: Partial<Settings>) => Promise<ExecutionResult>;

                                    • This method unlocks the provided lock from all servers still persisting it. It will fail with an error if it is unable to release the lock on a quorum of nodes, but will make no attempt to restore the lock in the case of a failure to release. It is safe to re-attempt a release or to ignore the error, as the lock will automatically expire after its timeout.

                                    method using

                                    using: {
                                        <T>(
                                            resources: string[],
                                            duration: number,
                                            settings: Partial<Settings>,
                                            routine?: (signal: RedlockAbortSignal) => Promise<T>
                                        ): Promise<T>;
                                        <T>(
                                            resources: string[],
                                            duration: number,
                                            routine: (signal: RedlockAbortSignal) => Promise<T>
                                        ): Promise<T>;
                                    };

                                    • Wrap and execute a routine in the context of an auto-extending lock, returning a promise of the routine's value. In the case that auto-extension fails, an AbortSignal will be updated to indicate that abortion of the routine is in order, and to pass along the encountered error.

                                      Example 1

                                      await redlock.using([senderId, recipientId], 5000, { retryCount: 5 }, async (signal) => {
                                        const senderBalance = await getBalance(senderId);
                                        const recipientBalance = await getBalance(recipientId);
                                      

                                        if (senderBalance < amountToSend) {
                                          throw new Error("Insufficient balance.");
                                        }
                                      

                                        // The abort signal will be true if:
                                        // 1. the above took long enough that the lock needed to be extended
                                        // 2. redlock was unable to extend the lock
                                        //
                                        // In such a case, exclusivity can no longer be guaranteed for further
                                        // operations, and should be handled as an exceptional case.
                                        if (signal.aborted) {
                                          throw signal.error;
                                        }
                                      

                                        await setBalances([
                                          {id: senderId, balance: senderBalance - amountToSend},
                                          {id: recipientId, balance: recipientBalance + amountToSend},
                                        ]);
                                      });

                                    class ResourceLockedError

                                    class ResourceLockedError extends Error {}

                                      constructor

                                      constructor(message: string);

                                        property message

                                        readonly message: string;

                                          Interfaces

                                          interface Settings

                                          interface Settings {}

                                          property automaticExtensionThreshold

                                          readonly automaticExtensionThreshold: number;

                                            property driftFactor

                                            readonly driftFactor: number;

                                              property retryCount

                                              readonly retryCount: number;

                                                property retryDelay

                                                readonly retryDelay: number;

                                                  property retryJitter

                                                  readonly retryJitter: number;

                                                    Type Aliases

                                                    type ClientExecutionResult

                                                    type ClientExecutionResult =
                                                        | {
                                                              client: Client;
                                                              vote: 'for';
                                                              value: number;
                                                          }
                                                        | {
                                                              client: Client;
                                                              vote: 'against';
                                                              error: Error;
                                                          };

                                                      type ExecutionResult

                                                      type ExecutionResult = {
                                                          attempts: ReadonlyArray<Promise<ExecutionStats>>;
                                                      };

                                                        type ExecutionStats

                                                        type ExecutionStats = {
                                                            readonly membershipSize: number;
                                                            readonly quorumSize: number;
                                                            readonly votesFor: Set<Client>;
                                                            readonly votesAgainst: Map<Client, Error>;
                                                        };

                                                          type RedlockAbortSignal

                                                          type RedlockAbortSignal = AbortSignal & {
                                                              error?: Error;
                                                          };

                                                            Package Files (1)

                                                            Dependencies (1)

                                                            Dev Dependencies (12)

                                                            Peer Dependencies (0)

                                                            No peer dependencies.

                                                            Badge

                                                            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/redlock.

                                                            • Markdown
                                                              [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/redlock)
                                                            • HTML
                                                              <a href="https://www.jsdocs.io/package/redlock"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>