@types/redlock - npm Package Compare versions

Comparing version 3.0.4 to 4.0.0

redlock/index.d.ts

@@ -1,5 +0,6 @@
-// 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
@@ -16,2 +17,7 @@ // TypeScript Version: 3.2
 
+    /**
+     * 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 {
@@ -22,3 +28,4 @@ redlock: Redlock;
         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>;
@@ -28,14 +35,87 @@ 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);
@@ -50,4 +130,13 @@ }
 
+/**
+ * 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;
@@ -60,18 +149,133 @@ driftFactor: number;
 
+    /**
+     * 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;
 }

redlock/package.json

 {
     "name": "@types/redlock",
-    "version": "3.0.4",
+    "version": "4.0.0",
     "description": "TypeScript definitions for redlock",
@@ -16,2 +16,7 @@ "license": "MIT",
             "githubUsername": "BendingBender"
+        },
+        {
+            "name": "Doug Ayers",
+            "url": "https://github.com/douglascayers",
+            "githubUsername": "douglascayers"
         }
@@ -30,4 +35,4 @@ ],
     },
-    "typesPublisherContentHash": "fbee25ba0e1c2ee617ade7476909af295ad857024f399f1f6d1a3c2e0ad6c7d4",
+    "typesPublisherContentHash": "e88b95d467c416711da96f3228f2fff95bae008c8d93eb92b5866b996a32032d",
     "typeScriptVersion": "3.2"
 }

redlock/README.md

@@ -11,3 +11,3 @@ # Installation
 Additional Details
- * Last updated: Mon, 01 Jul 2019 22:01:43 GMT
+ * Last updated: Wed, 02 Oct 2019 21:10:25 GMT
  * Dependencies: @types/bluebird
@@ -17,2 +17,2 @@ * Global values: none
 # Credits
-These definitions were written by Ilya Mochalov <https://github.com/chrootsu>, and BendingBender <https://github.com/BendingBender>.
+These definitions were written by Ilya Mochalov <https://github.com/chrootsu>, BendingBender <https://github.com/BendingBender>, and Doug Ayers <https://github.com/douglascayers>.

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

12514

increased by133.64%

Lines of code

252

increased by334.48%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes