Installation

npm install p-lock

yarn add p-lock

pnpm add p-lock

bun add p-lock

About

This package provides a simple promise queue, which is useful for preventing race conditions between multiple promises.

Overview

First, we get a lock function:

import { getLock } from "p-lock";

const lock = getLock();

Calling the lock function returns a promise that resolves when it reaches the front of the queue.

The promise resolves with a release function, which must be called to continue the queue:

lock("example-key").then((release) => {
  // Now this callback is at the front of the queue for "example-key"
  // do something...
  release();
});

Full Example

In this example, we have two promises writing to the same file. However, we want to ensure that the first one finishes before the second one starts.

import { writeFile } from "fs";
import { getLock } from "p-lock";

const lock = getLock();

lock("file").then((release) => {
  setTimeout(() => {
    writeFile("test.txt", "hello", () => {
      release();
    });
  }, 1000);
});

lock("file").then((release) => {
  writeFile("test.txt", "world", () => {
    release();
  });
});

// Contents of test.txt will be "world"

Replace

In some cases, we may want to replace an existing promise waiting for a lock, rather than waiting for it to finish.

The replace option allows us to do this:

import { writeFile } from "fs";
import { getLock } from "p-lock";

const lock = getLock({ replace: true });

let writeCounter = 0;

lock("file").then((release) => {
  setTimeout(() => {
    writeCounter += 1;
    writeFile("test.txt", `update #${writeCounter}`, () => {
      release();
    });
  }, 1000);
});

lock("file").then((release) => {
  writeCounter += 1;
  writeFile("test.txt", `update #${writeCounter}`, () => {
    release();
  });
}).catch(() => {
  // This promise will reject, since the next one replaces.
});

lock("file").then((release) => {
  writeCounter += 1;
  writeFile("test.txt", `update #${writeCounter}`, () => {
    release();
  });
});

// Contents of test.txt will be "update #2"

MIT - MIT License