@prairielearn/named-locks 1.3.3 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @prairielearn/named-locks
 
+## 1.5.0
+
+### Minor Changes
+
+- cdb0f2109: Add optional `onNotAcquired` function to `doWithLock` and `tryWithLock`
+
+## 1.4.0
+
+### Minor Changes
+
+- 297bbce5a: Allow `tryLockAsync` and `tryWithLock` to accept a timeout
+
+### Patch Changes
+
+- 2b003b4d9: Upgrade all dependencies
+- Updated dependencies [2b003b4d9]
+  - @prairielearn/postgres@1.7.2
+
 ## 1.3.3
 
 ### Patch Changes

package/README.md

@@ -16,7 +16,7 @@ await init(
   },
   (err) => {
     throw err;
-  }
+  },
 );
 ```
 
@@ -42,7 +42,7 @@ await doWithLock(
   },
   async () => {
     console.log('Doing some work');
-  }
+  },
 );
 ```
 

package/dist/index.d.ts

@@ -27,7 +27,9 @@ interface LockOptions {
      */
     autoRenew?: boolean;
 }
-type TryLockOptions = Omit<LockOptions, 'timeout'>;
+interface WithLockOptions<T> extends LockOptions {
+    onNotAcquired?: () => Promise<T> | T;
+}
 export declare const pool: PostgresPool;
 /**
  * Initializes a new {@link PostgresPool} that will be used to acquire named locks.
@@ -45,7 +47,7 @@ export declare function close(): Promise<void>;
  *
  * @param name The name of the lock to acquire.
  */
-export declare function tryLockAsync(name: string, options?: TryLockOptions): Promise<Lock | null>;
+export declare function tryLockAsync(name: string, options?: LockOptions): Promise<Lock | null>;
 export declare const tryLock: (arg1: string, callback: (err: NodeJS.ErrnoException, result: Lock | null) => void) => void;
 /**
  * Wait until a lock can be successfully acquired.
@@ -65,12 +67,19 @@ export declare const releaseLock: (arg1: Lock, callback: (err: NodeJS.ErrnoExcep
 /**
  * Acquires the given lock, executes the provided function with the lock held,
  * and releases the lock once the function has executed.
+ *
+ * If the lock cannot be acquired, the function is not executed. If an `onNotAcquired`
+ * function was provided, this function is called and its return value is returned.
+ * Otherwise, an error is thrown to indicate that the lock could not be acquired.
  */
-export declare function doWithLock<T>(name: string, options: LockOptions, func: () => Promise<T>): Promise<T>;
+export declare function doWithLock<T, U = never>(name: string, options: WithLockOptions<U>, func: () => Promise<T>): Promise<T | U>;
 /**
  * Tries to acquire the given lock, executes the provided function with the lock held,
- * and releases the lock once the function has executed. If the lock cannot be acquired,
- * the function is not executed and null is returned.
+ * and releases the lock once the function has executed.
+ *
+ * If the lock cannot be acquired, the function is not executed. If an `onNotAcquired`
+ * function was provided, this function is called and its return value is returned.
+ * Otherwise, `null` is returned.
  */
-export declare function tryWithLock<T>(name: string, options: TryLockOptions, func: () => Promise<T>): Promise<T | null>;
+export declare function tryWithLock<T, U = null>(name: string, options: WithLockOptions<U>, func: () => Promise<T>): Promise<T | U>;
 export {};

package/dist/index.js

@@ -109,9 +109,21 @@ exports.releaseLock = util_1.default.callbackify(releaseLockAsync);
 /**
  * Acquires the given lock, executes the provided function with the lock held,
  * and releases the lock once the function has executed.
+ *
+ * If the lock cannot be acquired, the function is not executed. If an `onNotAcquired`
+ * function was provided, this function is called and its return value is returned.
+ * Otherwise, an error is thrown to indicate that the lock could not be acquired.
  */
 async function doWithLock(name, options, func) {
-    const lock = await waitLockAsync(name, options);
+    const lock = await tryLockAsync(name, options);
+    if (!lock) {
+        if (options.onNotAcquired) {
+            return await options.onNotAcquired();
+        }
+        else {
+            throw new Error(`failed to acquire lock: ${name}`);
+        }
+    }
     try {
         return await func();
     }
@@ -122,19 +134,17 @@ async function doWithLock(name, options, func) {
 exports.doWithLock = doWithLock;
 /**
  * Tries to acquire the given lock, executes the provided function with the lock held,
- * and releases the lock once the function has executed. If the lock cannot be acquired,
- * the function is not executed and null is returned.
+ * and releases the lock once the function has executed.
+ *
+ * If the lock cannot be acquired, the function is not executed. If an `onNotAcquired`
+ * function was provided, this function is called and its return value is returned.
+ * Otherwise, `null` is returned.
  */
 async function tryWithLock(name, options, func) {
-    const lock = await tryLockAsync(name, options);
-    if (lock == null)
-        return null;
-    try {
-        return await func();
-    }
-    finally {
-        await releaseLockAsync(lock);
-    }
+    return await doWithLock(name, {
+        onNotAcquired: () => null,
+        ...options,
+    }, func);
 }
 exports.tryWithLock = tryWithLock;
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/named-locks",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "main": "./dist/index.js",
   "repository": {
     "type": "git",
@@ -13,10 +13,10 @@
   },
   "devDependencies": {
     "@prairielearn/tsconfig": "^0.0.0",
-    "@types/node": "^18.16.16",
-    "typescript": "^5.1.3"
+    "@types/node": "^18.16.19",
+    "typescript": "^5.1.6"
   },
   "dependencies": {
-    "@prairielearn/postgres": "^1.7.1"
+    "@prairielearn/postgres": "^1.7.2"
   }
 }

package/src/index.ts

@@ -19,6 +19,7 @@ interface Lock {
 interface LockOptions {
   /** How many milliseconds to wait (anything other than a positive number means forever) */
   timeout?: number;
+
   /**
    * Whether or not this lock should automatically renew itself periodically.
    * By default, locks will not renew themselves.
@@ -30,7 +31,9 @@ interface LockOptions {
   autoRenew?: boolean;
 }
 
-type TryLockOptions = Omit<LockOptions, 'timeout'>;
+interface WithLockOptions<T> extends LockOptions {
+  onNotAcquired?: () => Promise<T> | T;
+}
 
 /*
  * The functions here all identify locks by "name", which is a plain
@@ -84,13 +87,13 @@ let renewIntervalMs = 60_000;
 export async function init(
   pgConfig: PoolConfig,
   idleErrorHandler: (error: Error, client: PoolClient) => void,
-  namedLocksConfig: NamedLocksConfig = {}
+  namedLocksConfig: NamedLocksConfig = {},
 ) {
   renewIntervalMs = namedLocksConfig.renewIntervalMs ?? renewIntervalMs;
   await pool.initAsync(pgConfig, idleErrorHandler);
   await pool.queryAsync(
     'CREATE TABLE IF NOT EXISTS named_locks (id bigserial PRIMARY KEY, name text NOT NULL UNIQUE);',
-    {}
+    {},
   );
 }
 
@@ -109,10 +112,7 @@ export async function close() {
  *
  * @param name The name of the lock to acquire.
  */
-export async function tryLockAsync(
-  name: string,
-  options: TryLockOptions = {}
-): Promise<Lock | null> {
+export async function tryLockAsync(name: string, options: LockOptions = {}): Promise<Lock | null> {
   return getLock(name, { timeout: 0, ...options });
 }
 
@@ -148,13 +148,26 @@ export const releaseLock = util.callbackify(releaseLockAsync);
 /**
  * Acquires the given lock, executes the provided function with the lock held,
  * and releases the lock once the function has executed.
+ *
+ * If the lock cannot be acquired, the function is not executed. If an `onNotAcquired`
+ * function was provided, this function is called and its return value is returned.
+ * Otherwise, an error is thrown to indicate that the lock could not be acquired.
  */
-export async function doWithLock<T>(
+export async function doWithLock<T, U = never>(
   name: string,
-  options: LockOptions,
-  func: () => Promise<T>
-): Promise<T> {
-  const lock = await waitLockAsync(name, options);
+  options: WithLockOptions<U>,
+  func: () => Promise<T>,
+): Promise<T | U> {
+  const lock = await tryLockAsync(name, options);
+
+  if (!lock) {
+    if (options.onNotAcquired) {
+      return await options.onNotAcquired();
+    } else {
+      throw new Error(`failed to acquire lock: ${name}`);
+    }
+  }
+
   try {
     return await func();
   } finally {
@@ -164,21 +177,25 @@ export async function doWithLock<T>(
 
 /**
  * Tries to acquire the given lock, executes the provided function with the lock held,
- * and releases the lock once the function has executed. If the lock cannot be acquired,
- * the function is not executed and null is returned.
+ * and releases the lock once the function has executed.
+ *
+ * If the lock cannot be acquired, the function is not executed. If an `onNotAcquired`
+ * function was provided, this function is called and its return value is returned.
+ * Otherwise, `null` is returned.
  */
-export async function tryWithLock<T>(
+export async function tryWithLock<T, U = null>(
   name: string,
-  options: TryLockOptions,
-  func: () => Promise<T>
-): Promise<T | null> {
-  const lock = await tryLockAsync(name, options);
-  if (lock == null) return null;
-  try {
-    return await func();
-  } finally {
-    await releaseLockAsync(lock);
-  }
+  options: WithLockOptions<U>,
+  func: () => Promise<T>,
+): Promise<T | U> {
+  return await doWithLock<T, U>(
+    name,
+    {
+      onNotAcquired: () => null as U,
+      ...options,
+    },
+    func,
+  );
 }
 
 /**
@@ -192,7 +209,7 @@ export async function tryWithLock<T>(
 async function getLock(name: string, options: LockOptions) {
   await pool.queryAsync(
     'INSERT INTO named_locks (name) VALUES ($name) ON CONFLICT (name) DO NOTHING;',
-    { name }
+    { name },
   );
 
   const client = await pool.beginTransactionAsync();
@@ -206,7 +223,7 @@ async function getLock(name: string, options: LockOptions) {
       await pool.queryWithClientAsync(
         client,
         `SET LOCAL lock_timeout = ${client.escapeLiteral(options.timeout.toString())}`,
-        {}
+        {},
       );
     }