@upstash/lock - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

dist/index.d.ts

@@ -68,2 +68,20 @@ import { Redis } from '@upstash/redis';
 type LockStatus = "ACQUIRED" | "FREE";
+type DebounceConfig = {
+    /**
+     * Upstash Redis client instance for locking operations.
+     */
+    redis: Redis;
+    /**
+     * Unique identifier associated with the lock.
+     */
+    id: string;
+    /**
+     * Duration (in ms) for which to wait before executing the callback.
+     */
+    wait: number;
+    /**
+     * The callback function to execute after the wait time.
+     */
+    callback: (...args: any[]) => any;
+};
 
@@ -105,2 +123,2 @@ declare class Lock {
 
-export { Lock, LockAcquireConfig, LockConfig, LockCreateConfig, LockStatus, RetryConfig };
+export { DebounceConfig, Lock, LockAcquireConfig, LockConfig, LockCreateConfig, LockStatus, RetryConfig };

package.json

@@ -7,3 +7,3 @@ {
   "types": "./dist/index.d.ts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "keywords": ["redis", "lock", "upstash", "redlock"],
@@ -10,0 +10,0 @@ "author": "Meshan Khosla <[e-mail]>",

README.md

@@ -11,15 +11,32 @@ <div align="center">
 
-`@upstash/lock` offers a distributed lock implementation using Upstash Redis.
+> [!NOTE]  
+> **This project is in the Experimental Stage.**
+>
+> We declare this project experimental to set clear expectations for your usage. There could be known or unknown bugs, the API could evolve, or the project could be discontinued if it does not find community adoption. While we cannot provide professional support for experimental projects, we’d be happy to hear from you if you see value in this project!
 
+`@upstash/lock` offers a distributed lock and debounce implementation using Upstash Redis.
+
+### Disclaimer
+
+Please use this lock implementation for efficiency purposes; for example to avoid doing an expensive work more than once or to perform a task _mostly_ once in a best-effort manner.
+Do not use it to guarantee correctness of your system; such as leader-election or for the tasks requiring _exactly_ once execution.
+
+Upstash Redis uses async replication between replicas, and a lock can be acquired by multiple clients in case of a crash or network partition. Please read the post [How to do distributed locking](https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html) by Martin Kleppman to learn more about the topic.
+
 ### Quick Start
 
 NPM
+
 ```bash
 npm install @upstash/lock
 ```
+
 PNPM
+
 ```bash
 pnpm add @upstash/lock
 ```
+
 Bun
+
 ```bash
@@ -29,8 +46,12 @@ bun add @upstash/lock
 
+### Locking Demo
+
+To see a demo of the lock in action, visit [https://lock-upstash.vercel.app](https://lock-upstash.vercel.app)
+
 To create the Redis instance, you can use the `Redis.fromEnv()` method to use an Upstash Redis instance from environment variables. More options can be found [here](https://github.com/upstash/upstash-redis#quick-start).
 
-### Example Usage
+### Lock Example Usage
 
 ```typescript
-import { Lock } from '@upstash/lock';
+import { Lock } from "@upstash/lock";
 import { Redis } from "@upstash/redis";
@@ -54,4 +75,33 @@
 
-### API
+### Debounce Example Usage
 
+```typescript
+import { Lock } from "@upstash/lock";
+import { Redis } from "@upstash/redis";
+import { expensiveWork } from "my-app";
+
+const debouncedFunction = new Debounce({
+  id: "unique-function-id",
+  redis: Redis.fromEnv(),
+
+  // Wait time of 1 second
+  // The debounced function will only be called once per second across all instances
+  wait: 1000,
+
+  // Callback function to be debounced
+  callback: (arg) => {
+    doExpensiveWork(arg);
+  },
+});
+
+// This example function is called by our app to trigger work we want to only happen once per wait period
+async function triggerExpensiveWork(arg: string) {
+  // Call the debounced function
+  // This will only call the callback function once per wait period
+  await debouncedFunction.call(arg)
+}
+```
+
+### Lock API
+
 #### `Lock`
@@ -63,11 +113,12 @@
   redis: Redis, // ie. Redis.fromEnv(), new Redis({...})
-  lease?: number, // default: 10000 ms
-  retry?: {
-    attempts?: number, // default: 3
-    delay?: number, // default: 100 ms
+  lease: number, // default: 10000 ms
+  retry: {
+    attempts: number, // default: 3
+    delay: number, // default: 100 ms
   },
-})
+});
 ```
 
 #### `Lock#acquire`
+
 Attempts to acquire the lock. Returns `true` if the lock is acquired, `false` otherwise.
@@ -82,2 +133,3 @@
 #### `Lock#release`
+
 Attempts to release the lock. Returns `true` if the lock is released, `false` otherwise.
@@ -90,2 +142,3 @@
 #### `Lock#extend`
+
 Attempts to extend the lock lease. Returns `true` if the lock lease is extended, `false` otherwise.
@@ -98,2 +151,3 @@
 #### `Lock#getStatus`
+
 Returns whether the lock is `ACQUIRED` or `FREE`.
@@ -105,6 +159,32 @@
 
-| Option           | Default Value | Description                                                 |
-|------------------|---------------|-------------------------------------------------------------|
+| Option           | Default Value | Description                                                                       |
+| ---------------- | ------------- | --------------------------------------------------------------------------------- |
 | `lease`          | `10000`       | The lease duration in milliseconds. After this expires, the lock will be released |
-| `retry.attempts` | `3`           | The number of attempts to acquire the lock.                |
-| `retry.delay`    | `100`         | The delay between attempts in milliseconds.                 |
+| `retry.attempts` | `3`           | The number of attempts to acquire the lock.                                       |
+| `retry.delay`    | `100`         | The delay between attempts in milliseconds.                                       |
+
+### Debounce API
+
+#### `Debounce`
+
+Creates a new debounced function.
+
+```typescript
+new Debounce({
+  id: string,
+  redis: Redis, // ie. Redis.fromEnv(), new Redis({...})
+  wait: number, // default: 1000 ms
+  callback: (...arg: any[]) => any // The function to be debounced
+});
+```
+
+#### `Debounce#call`
+
+Calls the debounced function. The function will only be called once per `wait` period.
+When called there is a best-effort guarantee that the function will be called once per `wait` period.
+
+Note: Due to the implementation of the debounce, there is always a delay of `wait` milliseconds before the function is called (even if the callback is not triggered when you use the call function).
+
+```typescript
+async call(...args: any[]): Promise<void>
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

38254

increased by10.86%

Lines of code

438

increased by4.29%

Number of lines in readme file

183

increased by77.67%

No dependency changes