Proposal: Support function-less `navigator.locks.request()` returning a disposable lock object

[juner]

Summary

I would like to propose an additional overload of navigator.locks.request() that returns a Lock-like object when called without a callback function. This would allow developers to manually release the lock or use JavaScript’s await using (AsyncDisposable) syntax for automatic cleanup.

Motivation

Currently, the Web Locks API usage looks like this:

await navigator.locks.request("name", async lock => {
  // work
});

While this callback style is convenient in some scenarios, it can be limiting in others, such as:

• When you want to pass the lock object around different scopes.
• When using libraries like disposable-lock that rely on explicit lock objects and automatic disposal patterns.
• When you want to integrate with ECMAScript await using / AsyncDisposable syntax for safer automatic cleanup.

The desired additional usage would be:

// Case 1: explicit release
const lock = await navigator.locks.request("name");
// do work...
await lock.release();

Or:

// Case 2: using / auto-release
{
  await using lock = await navigator.locks.request("name");
  // do work...
}
// lock is automatically released

Proposed API

interface LockManager {
  request(name: string, options?: { ifAvailable?: boolean }): Promise<DisposableLock | null>;
}

Where DisposableLock could be defined as:

interface DisposableLock {
  readonly name: string;
  readonly mode: LockMode;

  release(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>; // for ECMAScript using support
}

This allows developers to safely use await using even if the lock was not obtained.

---

Potential Concerns / Considerations

• Backward compatibility with the existing callback-based API
• Ensuring locks are always released even if the user forgets release()
• Aligning the behavior with current lifetime rules in the Web Locks API
• Interaction with reentrancy and contention handling
• Handling ifAvailable: true cases consistently with both DisposableLock and null

References

• Web Locks API Editor’s Draft
• disposable-lock npm package
• ECMAScript await using / AsyncDisposable proposal: TC39 AsyncDisposable

Update:

Based on recent feedback from TC39 regarding AsyncDisposable, disposable-lock has been updated so that navigator.locks.request() now returns:

• a ReleasableLock object when the lock is successfully acquired, or
• null when the lock could not be obtained (e.g., ifAvailable: true).

This ensures compatibility with await using and aligns with the language-level guidance that await using x = null works safely.

Example usage:

{
  await using lock = await navigator.locks.request("name", { ifAvailable: true });
  if (lock) {
    // lock was acquired, work can proceed
  } else {
    // lock was not acquired, safe to skip
  }
}

[asutherland]

What does !lock return for a NotHaveLock lock?

[juner]

@asutherland Thank you for the question!

Currently, NotHaveLock is designed as an object with only the [Symbol.asyncDispose] method:

interface NotHaveLock {
  [Symbol.asyncDispose](): Promise<void>;
}

As such, in JavaScript, it is truthy, so !lock would evaluate to false. This means you cannot reliably use if (!lock) to check whether the lock was acquired.

The intended way to handle the ifAvailable: true case is:

const lock = await navigator.locks.request("name", { ifAvailable: true });

if ('release' in lock) {
  // lock was successfully acquired
  await lock.release();
} else {
  // lock was not acquired
}

Or, in TypeScript, you can use a type guard:

function isDisposableLock(lock: DisposableLock | NotHaveLock): lock is DisposableLock {
  return 'release' in lock;
}

This design choice ensures that await using lock = ... works safely regardless of whether the lock was acquired or not, without needing a separate null/undefined value.

We are open to discussion on whether returning null/undefined might be more convenient for users who want to use !lock checks, but using NotHaveLock keeps the API fully compatible with await using and AsyncDisposable patterns.

[juner]

@asutherland

Based on recent TC39 guidance regarding AsyncDisposable, we have updated the proposal and the disposable-lock implementation:

• navigator.locks.request() now returns a ReleasableLock object when the lock is successfully acquired.
• If the lock could not be obtained (e.g., ifAvailable: true), it now returns null instead of a separate NotHaveLock object.

This change ensures full compatibility with await using and aligns with the language-level guidance that await using x = null works safely.

The proposal text has been updated to reflect this new behavior, and example usage demonstrating the null case has been added.

[bakkot]

Incidentally, a fairly similar API is proposed in the shared structs proposal, and in the concurrency control proposal. Both of those early-stage proposals currently refer to the thing returned when successfully acquiring a lock as a "token", although this is subject to change.

You may wish to try to coordinate with those proposals.

(Rust uses "MutexGuard" for their similar concept, but the guard actually provides access to a resource and is checked by the Rust type system, so it's pretty different.)

[juner]

Thank you for pointing this out, @bakkot.

We'll take a look at the Shared Structs and Concurrency Control proposals, particularly around the idea of "token", and see whether it makes sense to align terminology or API design.

Any suggestions on how best to coordinate with the authors of those proposals would be appreciated.