[@types/redlock] Update definitions for redlock v4.0 (#38705)

* move to v3 folder

* definitions for redlock v4.0

* add path to redlock v3

* add comments from redlock's source code

types/redlock/index.d.ts

@@ -1,7 +1,8 @@
-// Type definitions for redlock 3.0
+// Type definitions for redlock 4.0
 // Project: https://github.com/mike-marcacci/node-redlock
 // Definitions by: Ilya Mochalov <https://github.com/chrootsu>
 //                 BendingBender <https://github.com/BendingBender>
+//                 Doug Ayers <https://github.com/douglascayers>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 3.2
 
@@ -13,28 +14,107 @@ export = Redlock;
 declare namespace Redlock {
     type Callback<T> = (err: any, value?: T) => void;
 
+    /**
+     * An object of this type is returned when a resource is successfully locked.
+     * It contains convenience methods `unlock` and `extend` which perform
+     * the associated Redlock method on itself.
+     */
     class Lock {
         redlock: Redlock;
         resource: string;
         value: string | null;
         expiration: number;
-        constructor(redlock: Redlock, resource: string, value: string | null, expiration: number);
+        attempts: number;
+        constructor(redlock: Redlock, resource: string, value: string | null, expiration: number, attempts: number);
         unlock(callback?: Callback<void>): Promise<void>;
         extend(ttl: number, callback?: Callback<Lock>): Promise<Lock>;
     }
 
+    /**
+     * Function that returns the LUA script to run on the
+     * Redis server to lock a resource.
+     *
+     * @param origScript - Redblock's default LUA script to lock a resource.
+     */
+    type LockScriptFunction = (origScript: string) => string;
+
+    /**
+     * Function that returns the LUA script to run on the
+     * Redis server to unlock a resource.
+     *
+     * @param origScript - Redblock's default LUA script to unlock a resource.
+     */
+    type UnlockScriptFunction = LockScriptFunction;
+
+    /**
+     * Function that returns the LUA script to run on the
+     * Redis server to extend the ttl of a locked resource.
+     *
+     * @param origScript - Redblock's default LUA script to extend a lock's ttl.
+     */
+    type ExtendScriptFunction = LockScriptFunction;
+
     interface Options {
+        /**
+         * The expected clock drift; for more details
+         * see http://redis.io/topics/distlock
+         *
+         * Default is 0.01
+         */
         driftFactor?: number;
+        /**
+         * The max number of times Redlock will attempt
+         * to lock a resource before erroring.
+         *
+         * Default is 10
+         */
         retryCount?: number;
+        /**
+         * The time in milliseconds between attempts.
+         *
+         * Default is 200
+         */
         retryDelay?: number;
+        /**
+         * The max time in ms randomly added to retries
+         * to improve performance under high contention
+         * see https://www.awsarchitectureblog.com/2015/03/backoff.html
+         *
+         * Default is 100
+         */
         retryJitter?: number;
-        lockScript?(origLockScript: string): string;
-        unlockScript?(origUnlockScript: string): string;
-        extendScript?(origExtendScript: string): string;
+        /**
+         * LUA script to run on the Redis server to lock a resource.
+         * https://redis.io/commands/eval
+         *
+         * Redlock has a default script.
+         * Only override if you know it's necessary to do so.
+         */
+        lockScript?: LockScriptFunction | string;
+        /**
+         * LUA script to run on the Redis server to unlock a resource.
+         * https://redis.io/commands/eval
+         *
+         * Redlock has a default script.
+         * Only override if you know it's necessary to do so.
+         */
+        unlockScript?: UnlockScriptFunction | string;
+        /**
+         * LUA script to run on the Redis server to extend a lock's ttl.
+         * https://redis.io/commands/eval
+         *
+         * Redlock has a default script.
+         * Only override if you know it's necessary to do so.
+         */
+        extendScript?: ExtendScriptFunction | string;
     }
 
+    /**
+     * This error is returned when there is an error locking a resource.
+     */
     class LockError extends Error {
         readonly name: 'LockError';
+        attempts: number;
         constructor(message?: string);
     }
 
@@ -44,8 +124,17 @@ declare namespace Redlock {
     }
 }
 
+/**
+ * Inherit all the EventEmitter methods, like `on`, and `off`.
+ */
 declare class Redlock extends EventEmitter {
+    /**
+     * Attach a reference to LockError, which allows the application to use instanceof to ensure type.
+     */
     LockError: typeof Redlock.LockError;
+    /**
+     * Attach a reference to Lock, which allows the application to use instanceof to ensure type.
+     */
     Lock: typeof Redlock.Lock;
     driftFactor: number;
     retryCount: number;
@@ -53,20 +142,135 @@ declare class Redlock extends EventEmitter {
     retryJitter: number;
     servers: Redlock.CompatibleRedisClient[];
 
+    /**
+     * 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.
+     *
+     * @param clients - you should have one client for each independent redis node
+     * @param options - optionally customize settings (advanced use only)
+     */
     constructor(clients: Redlock.CompatibleRedisClient[], options?: Redlock.Options);
 
+    /**
+     * This method runs `.quit()` on all client connections.
+     */
+    quit(callback?: Redlock.Callback<void>): Promise<void>;
+
+    /**
+     * This method locks a resource using the redlock algorithm.
+     *
+     * ```js
+     * redlock.lock(
+     *   'some-resource',       // the resource to lock
+     *   2000,                  // ttl in ms
+     *   function(err, lock) {  // callback function (optional)
+     *     ...
+     *   }
+     * )
+     * ```
+     *
+     * @param resource - one or more resources to lock
+     * @param ttl - how long to keep the lock (milliseconds)
+     */
     acquire(resource: string | string[], ttl: number, callback?: Redlock.Callback<Redlock.Lock>): Promise<Redlock.Lock>;
+
+    /**
+     * This method locks a resource using the redlock algorithm.
+     *
+     * ```js
+     * redlock.lock(
+     *   'some-resource',       // the resource to lock
+     *   2000,                  // ttl in ms
+     *   function(err, lock) {  // callback function (optional)
+     *     ...
+     *   }
+     * )
+     * ```
+     *
+     * @param resource - one or more resources to lock
+     * @param ttl - how long to keep the lock (milliseconds)
+     */
     lock(resource: string | string[], ttl: number, callback?: Redlock.Callback<Redlock.Lock>): Promise<Redlock.Lock>;
 
+    /**
+     * This method locks a resource using the redlock algorithm,
+     * and returns a bluebird disposer.
+     *
+     * ```js
+     * using(
+     *     redlock.disposer(
+     *         'some-resource',       // the resource to lock
+     *         2000                   // ttl in ms
+     *     ),
+     *     function(lock) {
+     *         ...
+     *     }
+     * );
+     * ```
+     *
+     * @param resource - one or more resources to lock
+     * @param ttl - how long to keep the lock (milliseconds)
+     * @param errorHandler -- handle any errors when disposer tries to unlock the resource
+     */
     disposer(resource: string, ttl: number, errorHandler?: Redlock.Callback<void>): Promise.Disposer<Redlock.Lock>;
 
+    /**
+     * 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 on nodes that failed to release. It is safe to re-attempt an
+     * unlock or to ignore the error, as the lock will automatically expire after its timeout.
+     *
+     * @param lock - the lock to release
+     * @param callback - be notified once lock has been released by the clients
+     */
     release(lock: Redlock.Lock, callback?: Redlock.Callback<void>): Promise<void>;
+
+    /**
+     * 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 on nodes that failed to release. It is safe to re-attempt an
+     * unlock or to ignore the error, as the lock will automatically expire after its timeout.
+     *
+     * @param lock - the lock to release
+     * @param callback - be notified once lock has been released by the clients
+     */
     unlock(lock: Redlock.Lock, callback?: Redlock.Callback<void>): Promise<void>;
 
+    /**
+     * This method extends a valid lock by the provided `ttl`.
+     *
+     * @param lock - the lock whose lease to extend
+     * @param ttl - the new time to live value (milliseconds) from now
+     * @param callback - be notified when lock's lease is extended
+     */
     extend(lock: Redlock.Lock, ttl: number, callback?: Redlock.Callback<Redlock.Lock>): Promise<Redlock.Lock>;
 
+    /*
+     * Functions inherited from EventEmitter
+     * https://nodejs.org/api/events.html#events_class_eventemitter
+     */
+
+    /**
+     * Subscribe to `clientError` events.
+     * Alias for `on(event, listener)` function.
+     */
     addListener(event: 'clientError', listener: (err: any) => void): this;
+
+    /**
+     * Subscribe to `clientError` events.
+     * Your callback is invoked every time this event is emitted.
+     */
     on(event: 'clientError', listener: (err: any) => void): this;
+
+    /**
+     * Subscribe to `clientError` events.
+     * Your callback is invoked only once for this event.
+     */
     once(event: 'clientError', listener: (err: any) => void): this;
+
+    /**
+     * Unsubscribe from the `clientError` event.
+     */
     removeListener(event: 'clientError', listener: (err: any) => void): this;
 }

types/redlock/redlock-tests.ts

@@ -4,8 +4,6 @@ import { RedisClient } from 'redis';
 import IoRedisClient = require('ioredis');
 import { using } from 'bluebird';
 
-const lock: Lock = <Lock> {};
-
 const client1 = new RedisClient({port: 6379, host: 'redis1.example.com'});
 const client2 = new RedisClient({port: 6379, host: 'redis2.example.com'});
 const client3 = new IoRedisClient({port: 6379, host: 'redis3.example.com'});
@@ -20,6 +18,39 @@ const redlock = new Redlock(
     }
 );
 
+const lock: Lock = new Redlock.Lock(
+    // redlock instance
+    redlock,
+    // name of resource to lock
+    'resource-to-lock-name',
+    // value to store with resource key in redis
+    'value-to-store-with-resource',
+    // expiration (ttl) for this lock resource
+    200,
+    // number of attempts if have to retry to lock resource
+    2,
+);
+
+const redlockWithStringScripts = new Redlock([client1, client2, client3], {
+    driftFactor: 0.01,
+    retryCount: 10,
+    retryDelay: 200,
+    retryJitter: 200,
+    lockScript: 'custom lock script',
+    unlockScript: 'custom unlock script',
+    extendScript: 'custom extend script',
+});
+
+const redlockWithFunctionScripts = new Redlock([client1, client2, client3], {
+    driftFactor: 0.01,
+    retryCount: 10,
+    retryDelay: 200,
+    retryJitter: 200,
+    lockScript: origLockScript => 'custom lock script',
+    unlockScript: origUnlockScript => 'custom unlock script',
+    extendScript: origExtendScript => 'custom extend script',
+});
+
 redlock.on('clientError', (err) => {
     console.error('A redis error has occurred:', err);
 });
@@ -45,7 +76,11 @@ redlock.extend(lock, 30).then((lock: Lock) => {});
 redlock.extend(lock, 30, (err: any, lock: Lock) => {});
 
 lock.unlock();
-lock.unlock((err) => {});
+lock.unlock(err => {
+    if (err instanceof Redlock.LockError) {
+        console.error(`attempts=${err.attempts}`);
+    }
+});
 
 lock.extend(30).then((lock: Lock) => {});
 lock.extend(30, (err: any, lock: Lock) => {});
@@ -91,6 +126,10 @@ redlock.lock('locks:account:322456', 1000, (err, lock) => {
     }
 });
 
+redlock.quit();
+redlock.quit(() => {});
+redlock.quit().then(() => {});
+
 new Object() instanceof redlock.Lock;
 
 new Error() instanceof redlock.LockError;

types/redlock/v3/index.d.ts

@@ -0,0 +1,72 @@
+// Type definitions for redlock 3.0
+// Project: https://github.com/mike-marcacci/node-redlock
+// Definitions by: Ilya Mochalov <https://github.com/chrootsu>
+//                 BendingBender <https://github.com/BendingBender>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 3.2
+
+import * as Promise from 'bluebird';
+import { EventEmitter } from 'events';
+
+export = Redlock;
+
+declare namespace Redlock {
+    type Callback<T> = (err: any, value?: T) => void;
+
+    class Lock {
+        redlock: Redlock;
+        resource: string;
+        value: string | null;
+        expiration: number;
+        constructor(redlock: Redlock, resource: string, value: string | null, expiration: number);
+        unlock(callback?: Callback<void>): Promise<void>;
+        extend(ttl: number, callback?: Callback<Lock>): Promise<Lock>;
+    }
+
+    interface Options {
+        driftFactor?: number;
+        retryCount?: number;
+        retryDelay?: number;
+        retryJitter?: number;
+        lockScript?(origLockScript: string): string;
+        unlockScript?(origUnlockScript: string): string;
+        extendScript?(origExtendScript: string): string;
+    }
+
+    class LockError extends Error {
+        readonly name: 'LockError';
+        constructor(message?: string);
+    }
+
+    interface CompatibleRedisClient {
+        eval(args: any[], callback?: (err: Error | null, res: any) => void): any;
+        eval(...args: any[]): any;
+    }
+}
+
+declare class Redlock extends EventEmitter {
+    LockError: typeof Redlock.LockError;
+    Lock: typeof Redlock.Lock;
+    driftFactor: number;
+    retryCount: number;
+    retryDelay: number;
+    retryJitter: number;
+    servers: Redlock.CompatibleRedisClient[];
+
+    constructor(clients: Redlock.CompatibleRedisClient[], options?: Redlock.Options);
+
+    acquire(resource: string | string[], ttl: number, callback?: Redlock.Callback<Redlock.Lock>): Promise<Redlock.Lock>;
+    lock(resource: string | string[], ttl: number, callback?: Redlock.Callback<Redlock.Lock>): Promise<Redlock.Lock>;
+
+    disposer(resource: string, ttl: number, errorHandler?: Redlock.Callback<void>): Promise.Disposer<Redlock.Lock>;
+
+    release(lock: Redlock.Lock, callback?: Redlock.Callback<void>): Promise<void>;
+    unlock(lock: Redlock.Lock, callback?: Redlock.Callback<void>): Promise<void>;
+
+    extend(lock: Redlock.Lock, ttl: number, callback?: Redlock.Callback<Redlock.Lock>): Promise<Redlock.Lock>;
+
+    addListener(event: 'clientError', listener: (err: any) => void): this;
+    on(event: 'clientError', listener: (err: any) => void): this;
+    once(event: 'clientError', listener: (err: any) => void): this;
+    removeListener(event: 'clientError', listener: (err: any) => void): this;
+}

types/redlock/v3/redlock-tests.ts

@@ -0,0 +1,99 @@
+import Redlock = require('redlock');
+import { Lock } from 'redlock';
+import { RedisClient } from 'redis';
+import IoRedisClient = require('ioredis');
+import { using } from 'bluebird';
+
+const lock: Lock = <Lock> {};
+
+const client1 = new RedisClient({port: 6379, host: 'redis1.example.com'});
+const client2 = new RedisClient({port: 6379, host: 'redis2.example.com'});
+const client3 = new IoRedisClient({port: 6379, host: 'redis3.example.com'});
+
+const redlock = new Redlock(
+    [client1, client2, client3],
+    {
+        driftFactor: 0.01,
+        retryCount: 10,
+        retryDelay: 200,
+        retryJitter: 200
+    }
+);
+
+redlock.on('clientError', (err) => {
+    console.error('A redis error has occurred:', err);
+});
+
+redlock.acquire('resource', 30).then((lock: Lock) => {});
+redlock.acquire('resource', 30, (err: any, lock: Lock) => {});
+redlock.lock('resource', 30).then((lock: Lock) => {});
+redlock.lock('resource', 30, (err: any, lock: Lock) => {});
+
+using<Lock, void>(redlock.disposer('locks:account:322456', 1000, err => console.error(err)), (lock) => {
+    return Promise.resolve();
+});
+using<Lock, void>(redlock.disposer('locks:account:322456', 1000, err => console.error(err)), (lock) => {
+    return lock.extend(1000).then((extended: Lock) => {});
+});
+
+redlock.release(lock);
+redlock.release(lock, (err: any) => {});
+redlock.unlock(lock);
+redlock.unlock(lock, (err: any) => {});
+
+redlock.extend(lock, 30).then((lock: Lock) => {});
+redlock.extend(lock, 30, (err: any, lock: Lock) => {});
+
+lock.unlock();
+lock.unlock((err) => {});
+
+lock.extend(30).then((lock: Lock) => {});
+lock.extend(30, (err: any, lock: Lock) => {});
+
+redlock.lock('locks:account:322456', 1000).then((lock) => {
+    return lock
+        .unlock()
+        .catch((err) => {
+            console.error(err);
+        });
+});
+
+redlock.lock('locks:account:322456', 1000).then(lock => {
+    return lock
+        .extend(1000)
+        .then(lock => {
+            return lock
+                .unlock()
+                .catch(err => {
+                    console.error(err);
+                });
+        });
+});
+
+redlock.lock('locks:account:322456', 1000, (err, lock) => {
+    if (err || !lock) {
+    } else {
+        lock.unlock(err => {
+            console.error(err);
+        });
+    }
+});
+
+redlock.lock('locks:account:322456', 1000, (err, lock) => {
+    if (err || !lock) {
+    } else {
+        lock.extend(1000, (err, lock) => {
+            if (err || !lock) {
+            } else {
+                lock.unlock();
+            }
+        });
+    }
+});
+
+new Object() instanceof redlock.Lock;
+
+new Error() instanceof redlock.LockError;
+
+redlock.LockError.prototype;
+const lockError: Redlock.LockError = new redlock.LockError();

types/redlock/v3/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": false,
+        "baseUrl": "../../",
+        "typeRoots": [
+            "../../"
+        ],
+        "paths": {
+            "redlock": [
+                "redlock/v3"
+            ]
+        },
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "redlock-tests.ts"
+    ]
+}

types/redlock/v3/tslint.json

@@ -0,0 +1,8 @@
+{
+	"extends": "dtslint/dt.json",
+	"rules": {
+		// TODO
+        "no-angle-bracket-type-assertion": false,
+		"no-object-literal-type-assertion": false
+	}
+}