aermin/web-locks

Web Locks API(navigator.locks) polyfill, implement according to Specification

web-locks polyfill

a Web Locks API polyfill, work when the browser does not support web lock API: navigator.lock, resolve the browser compatibility issue.

• implement features according to Web Locks API Specification

• implement the unit test according to web-platform-test

• implement all the features of Web Locks API

Installation

// with npm
npm install navigator.locks

// with yarn
yarn add navigator.locks

Usage

Just import It.

import "navigator.locks";

navigator.locks.request("my_resource", async (lock) => {
  // The lock has been acquired.
  await do_something();
  await do_something_else();
  // Now the lock will be released.
});

// if you use Typescript, could import these types to use
import type {
  LockManager,
  Lock,
  LockInfo,
  LockManagerSnapshot,
  LocksInfo,
} from "navigator.locks";

navigator.locks API usage follow MDN API Doc

Online demo

demo link

You could open two tabs of this API unsupported browser, operate the lock buttons to experience

Process

All API ✅

• navigator.locks.request

• navigator.locks.request options:

  mode: exclusive | shared

  ifAvailable

  steal

  signal

• navigator.locks.query

CI/CD ✅

Unit test ✅

web-locks's Issues

Old heartbeat items are not cleared from local storage

Hey @aermin,

Nice work on the library! I've been testing this out and noticed that for every browser tab refresh, a new item gets added to local storage.

I thought about a potential fix, and looking through the code I see there is an "unload" handler in heartBeat.ts that could be modified to clear the heartbeat item. However, "unload" events are not reliably fired in many browsers so might need to think of something else.

DOMException: Lock broken by another request with the 'steal' option.

This error happens randomly, and the code acquiring the lock just blows up. This is in Firefox 91.

Make the library compatible with client/server environments where window is undefined

👋 Thanks for building this project.

I propose the following change to make it compatible with client/server frameworks like next.js.
At the moment trying to use the library with next.js throws the error window is not defined because a page can be rendered on the server side where window is undefined.

I tested locally and it should work with 2 simple changes

index.ts

const locks = (function () {
  // Add this block
  if (typeof window === "undefined") {
    return {
      request: async () => {},
      query: () => ({
        held: [],
        pending: [],
      }),
    } as Partial<LockManager>;
  }
  // existing code
})();

polyfill.ts

  constructor() {
    this._defaultOptions = {
      mode: LOCK_MODE.EXCLUSIVE,
      ifAvailable: false,
      steal: false,
    };
    // Wrap init inside a check
    if (typeof window !== "undefined") {
      this._init();
    }
  }