mongo-locks 2.0.1 → 3.0.0

package/README.md

@@ -1,140 +1,60 @@
 # mongo-locks
+
 Simple and bountiful locks to avoid doing the same operation multiple times
 
 The purpose of this package is simply to avoid doing the same thing twice at the same time
 and make your system a bit more user-proof.
 
-Usage, if your version of node supports await/async:
+```ts
+import { LockManager } from "mongo-locks";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient("mongodb://localhost:27017");
+const lockManager = new LockManager(client.db().collection("mongo-locks"));
 
-```js
 async function doStuff() {
-  var freeLock = () => {}; //no-op, you can also use locks.noop
+  await using lock = lockManager.lock("unique string key");
 
-  //... code
+  if (!lock.locked) {
+    console.log("Lock already taken");
+    return;
+  }
 
-  try {
-    //...
-    freeLock = await locks.lock("unique string key");
+  // do stuff
 
-    //sensitive code
-  } catch(err) {
-    //...
-  } finally {
-    freeLock(); /* Gets started on releasing lock, can be awaited */
-  }
+  //lock is automatically freed
 }
 ```
 
-Locks are automatically freed within one minute or two, as the purpose of this package is just to protect against
-race conditions and doing the same action several times in a short span.
-
-For a more concrete example:
+If the process crashes while a lock is active, MongoDB will automatically free it after one minute or two.
 
-Imagine you have a "like" feature on your site, where users can like posts. Maybe you would
-process likes this way:
+If you don't want to use the `using` syntax, you can do it this way:
 
-```js
-const mongoose = require('mongoose');
+```ts
+async function doStuff() {
+  const lock = await lockManager.lock("unique string key");
 
-router.all("/like", isUserLoggedIn, (req, res, next) => {
-  /* Silently ignore attempt to like an already liked post */
-  if (req.user.doesLike(req.post.id)) {
-    return res.redirect(req.post.getLink()); 
+  if (!lock.locked) {
+    console.log("Lock already taken");
+    return;
   }
 
-  /* Add post reference to user, and increase likes for post */
-  Promise.all([
-    req.user.update({$push: {likedPosts: {ref: req.post.id, title: req.post.title}}}),
-    req.post.update({$inc: {likes: 1}})
-  ]).then(
-    () => res.redirect(req.post.getLink()), //when all done
-    next //in case of error, next(err) is called
-  );
-});
-```
-
-The problem with this is that if a user accesses the "like" url twice very fast, for whatever
-reason, the server can add the like on one hand while the silent check is already passed successfully
-on the other hand, and boom, the user liked the same post twice!
-
-This package aims to solve that problem. The code would now look like:
-
-```js
-const mongoose = require('mongoose');
-const locks = require('mongo-locks');
-
-locks.init(mongoose.connection); //do just once across the whole app
-
-router.all("/like", isUserLoggedIn, (req, res, next) => {
-  /* Silently ignore attempt to like an already liked post */
-  if (req.user.doesLike(req.post.id)) {
-    return res.redirect(req.post.getLink()); 
+  try {
+    // do stuff
+  } finally {
+    await lock.free(); // or await lock[Symbol.asyncDispose]();
   }
-
-  var freeLock = () => {};
-  /* Add post reference to user, and increase likes for post */
-  locks.lock("like", req.user.id, req.post.id).then((free) => {
-    freeLock = free;
-    return Promise.all([
-      req.user.update({$push: {likedPosts: {ref: req.post.id, title: req.post.title}}}),
-      req.post.update({$inc: {likes: 1}})
-    ]);
-  }).then(() => res.redirect(req.post.getLink()), next)
-    .then(freeLock, freeLock);
-});
+}
 ```
 
-Internally, this package creates a collection and tries to insert locks in
-that collection. It relies on MongoDB's unique indexes to guarantee an error
-is returned in case the same lock is used twice.
+## Mongoose
 
+Mongoose let's you access the underlying collection of a model, so you can use it like this:
 
-## API
+```ts
+import { LockManager } from "mongo-locks";
+import mongoose from "mongoose";
 
-All the functions except for getting and setting the parameters return Promises.
-
-### .init(connection: mongoose.connection[, options])
-
-Initialize the connection to the mongo database, needed before any calls to the other functions.
-
-`options` is made of the following:
-
-#### collection 
-
-The collection this module will create and use to store locks, by default `locks`
-
-### .lock([action1[, action2[, action3[, ...])
-
-Create a lock for the combination of said actions, return a Promise that is rejected if lock creation failed.
-
-The lock's id will actually be the various arguments converted to string and joined with `"-"`, so passing objects
-to this function is ill-advised.
-
-If lock creation succeeds, the Promise resolves to a function to free the lock.
-
-If lock creation fails, an exception is thrown.
-
-### .free([action1[, action2[, action3[, ...])
-
-Frees the lock. If you want to wait until the lock is freed, you can chain it with `.then`.
-
-### .resfresh([action1[, action2[, action3[, ...])
-
-Refreshes the lock, giving it one minute more. Chainable.
-
-## MongoDb model
-
-Model created:
-
-``` js
-// This module will create a Mongoose model 
-// collection with schema:
-Locks = new mongoose.Schema({
-    createdAt:     Date,
-    refreshedAt:   Date,  //indexed, expires after 60 seconds
-    action:        String //uniquely indexed
-});
+const lockManager = new LockManager(mongoose.model("Lock").collection);
+// ...
 ```
-
-The collection is called "locks" by default, but you can set the name you want in the `options`
-parameter of the `init()` function.

package/dist/index.js

@@ -10,47 +10,108 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MongoLocksError = void 0;
-const schema_1 = require("./src/schema");
+const mongodb_1 = require("mongodb");
 class MongoLocksError extends Error {
     constructor(message) {
         super(message);
     }
 }
 exports.MongoLocksError = MongoLocksError;
-const makeLockId = (array) => Array.prototype.slice.apply(array).join(":");
-class LockManager {
-    constructor() {
-        this.Locks = null;
-        this.MongoLocksError = MongoLocksError;
-        this.noop = () => __awaiter(this, void 0, void 0, function* () { });
+const makeKey = (key) => {
+    // Arrays mess up the unique MongoDB indexes
+    return Array.isArray(key) ? { _key_array: key } : key;
+};
+class Lock {
+    constructor(_id, action, collection, locked) {
+        this._id = _id;
+        this.action = action;
+        this.collection = collection;
+        this.locked = locked;
+        if (this.locked) {
+            (() => __awaiter(this, void 0, void 0, function* () {
+                while (this.locked) {
+                    yield new Promise((resolve) => setTimeout(resolve, 10000));
+                    yield this.refresh().catch(() => {
+                        console.error("Failed to refresh lock", action);
+                    });
+                }
+            }))();
+        }
     }
-    init(connection, options) {
-        options = options || {};
-        this.Locks = connection.model(options.collection || "Locks", schema_1.default);
+    /**
+     * Instead of calling `this.free` directly you can use the `using` syntax
+     *
+     * @returns true if the lock was successfully released. False if the lock was not found
+     */
+    free() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.locked) {
+                return false;
+            }
+            const result = yield this.collection.deleteOne({ _id: this._id });
+            return result.deletedCount === 1;
+        });
     }
-    lock(...actions) {
+    /**
+     * Refreshes the lock's TTL
+     *
+     * Automatically called every 10 seconds if the lock is still active, no
+     * need to call this manually
+     *
+     * @returns true if the lock was successfully refreshed. False if the lock was not found
+     */
+    refresh() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (!this.Locks) {
-                throw new MongoLocksError("You must initialize mongo-locks with a mongoose connection");
+            if (!this.locked) {
+                return false;
             }
-            const lockId = makeLockId(actions);
-            const l = new this.Locks();
-            l.action = lockId;
-            yield l.save();
-            return () => this.Locks.deleteOne({ action: lockId }).exec();
+            const res = yield this.collection.updateOne({ _id: this._id }, { $set: { refreshedAt: new Date(), expiresAt: new Date(Date.now() + 60000) } });
+            this.locked = res.matchedCount === 1;
+            return this.locked;
         });
     }
-    refresh(...actions) {
-        if (!this.Locks) {
-            throw new MongoLocksError("You must initialize mongo-locks with a mongoose connection");
-        }
-        return this.Locks.updateOne({ action: makeLockId(actions) }, { $set: { refreshedAt: Date.now() } }, { upsert: true }).exec();
+    [Symbol.dispose]() {
+        this.free();
     }
-    free(...actions) {
-        if (!this.Locks) {
-            throw new MongoLocksError("You must initialize mongo-locks with a mongoose connection");
-        }
-        return this.Locks.deleteOne({ action: makeLockId(actions) }).exec();
+    [Symbol.asyncDispose]() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.free();
+        });
+    }
+}
+class LockManager {
+    constructor(collection) {
+        this.MongoLocksError = MongoLocksError;
+        this.collection = collection;
+        collection.createIndex({ action: 1 }, { unique: true });
+        collection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+    }
+    /**
+     * Creates a DB lock based on the key provided
+     *
+     * @returns a function that when called will release the lock
+     */
+    lock(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const lockId = makeKey(key);
+            const id = new mongodb_1.ObjectId();
+            try {
+                yield this.collection.insertOne({
+                    _id: id,
+                    action: lockId,
+                    createdAt: new Date(),
+                    refreshedAt: new Date(),
+                    expiresAt: new Date(Date.now() + 60000),
+                });
+                return new Lock(id, lockId, this.collection, true);
+            }
+            catch (err) {
+                if (err instanceof Error && "code" in err && err.code === 11000) {
+                    return new Lock(id, lockId, this.collection, false);
+                }
+                throw err;
+            }
+        });
     }
 }
-exports.default = new LockManager();
+exports.default = LockManager;

package/index.ts

@@ -1,5 +1,4 @@
-import * as mongoose from "mongoose";
-import lockSchema from "./src/schema";
+import { Collection, ObjectId } from "mongodb";
 
 export class MongoLocksError extends Error {
   constructor(message?: string) {
@@ -7,50 +6,123 @@ export class MongoLocksError extends Error {
   }
 }
 
-const makeLockId = (array: any[]) => Array.prototype.slice.apply(array).join(":");
+const makeKey = (key: unknown) => {
+  // Arrays mess up the unique MongoDB indexes
+  return Array.isArray(key) ? { _key_array: key } : key;
+};
 
-class LockManager {
-  Locks: mongoose.Model<any> | null = null;
-  MongoLocksError = MongoLocksError;
-  noop: () => Promise<any> = async () => {};
+interface LockModel {
+  _id: ObjectId;
+  action: unknown;
+  createdAt: Date;
+  refreshedAt: Date;
+  expiresAt: Date;
+}
 
-  init(connection: mongoose.Connection, options?: { collection?: string }) {
-    options = options || {};
-    this.Locks = connection.model(options.collection || "Locks", lockSchema);
+class Lock {
+  constructor(
+    public _id: ObjectId,
+    public action: unknown,
+    public collection: Collection<LockModel>,
+    public locked: boolean
+  ) {
+    if (this.locked) {
+      (async () => {
+        while (this.locked) {
+          await new Promise((resolve) => setTimeout(resolve, 10_000));
+          await this.refresh().catch(() => {
+            console.error("Failed to refresh lock", action);
+          });
+        }
+      })();
+    }
   }
 
-  async lock(...actions: any[]): Promise<() => Promise<any>> {
-    if (!this.Locks) {
-      throw new MongoLocksError("You must initialize mongo-locks with a mongoose connection");
+  /**
+   * Instead of calling `this.free` directly you can use the `using` syntax
+   *
+   * @returns true if the lock was successfully released. False if the lock was not found
+   */
+  async free(): Promise<boolean> {
+    if (!this.locked) {
+      return false;
     }
 
-    const lockId = makeLockId(actions);
-
-    const l = new this.Locks();
-    l.action = lockId;
-    await l.save();
-    return () => this.Locks!.deleteOne({ action: lockId }).exec()
+    const result = await this.collection.deleteOne({ _id: this._id });
+    return result.deletedCount === 1;
   }
 
-  refresh(...actions: any[]) {
-    if (!this.Locks) {
-      throw new MongoLocksError("You must initialize mongo-locks with a mongoose connection");
+  /**
+   * Refreshes the lock's TTL
+   *
+   * Automatically called every 10 seconds if the lock is still active, no
+   * need to call this manually
+   *
+   * @returns true if the lock was successfully refreshed. False if the lock was not found
+   */
+  async refresh(): Promise<boolean> {
+    if (!this.locked) {
+      return false;
     }
 
-    return this.Locks.updateOne(
-      { action: makeLockId(actions) },
-      { $set: { refreshedAt: Date.now() } },
-      { upsert: true }
-    ).exec();
+    const res = await this.collection.updateOne(
+      { _id: this._id },
+      { $set: { refreshedAt: new Date(), expiresAt: new Date(Date.now() + 60_000) } }
+    );
+
+    this.locked = res.matchedCount === 1;
+
+    return this.locked;
   }
 
-  free(...actions: any[]) {
-    if (!this.Locks) {
-      throw new MongoLocksError("You must initialize mongo-locks with a mongoose connection");
-    }
+  [Symbol.dispose]() {
+    this.free();
+  }
+
+  async [Symbol.asyncDispose]() {
+    return this.free();
+  }
+}
+
+class LockManager {
+  collection: Collection<LockModel>;
+  MongoLocksError = MongoLocksError;
+
+  constructor(collection: Collection) {
+    this.collection = collection as unknown as Collection<LockModel>;
 
-    return this.Locks.deleteOne({ action: makeLockId(actions) }).exec();
+    collection.createIndex({ action: 1 }, { unique: true });
+    collection.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 });
+  }
+
+  /**
+   * Creates a DB lock based on the key provided
+   *
+   * @returns a function that when called will release the lock
+   */
+  async lock(key: unknown): Promise<Lock> {
+    const lockId = makeKey(key);
+    const id = new ObjectId();
+
+    try {
+      await this.collection.insertOne({
+        _id: id,
+        action: lockId,
+        createdAt: new Date(),
+        refreshedAt: new Date(),
+        expiresAt: new Date(Date.now() + 60_000),
+      });
+
+      return new Lock(id, lockId, this.collection, true);
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === 11000) {
+        return new Lock(id, lockId, this.collection, false);
+      }
+
+      throw err;
+    }
   }
 }
 
-export default new LockManager();
+export default LockManager;
+export type { LockModel, Lock };

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "mongo-locks",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Simple and bountiful locks to avoid doing the same operation multiple times",
   "main": "dist/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "npm run clean && tsc",
+    "clean": "rm -Rf dist"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/coyotte508/mongo-locks.git"
   },
   "keywords": [
     "mongo",
-    "mongoose",
+    "mongodb",
     "lock",
     "mutex",
     "multiple"
@@ -21,21 +26,17 @@
   },
   "homepage": "https://github.com/coyotte508/mongo-locks#readme",
   "peerDependencies": {
-    "mongoose": ">=4.7.6"
+    "mongodb": ">=4"
   },
   "devDependencies": {
-    "mongoose": "^6.0.2",
-    "typescript": "^4.0.1"
+    "@types/node": "^20.12.7",
+    "mongodb": "^6.5.0",
+    "typescript": "^5.4.5"
   },
   "files": [
-    "src",
     "dist",
     "index.d.ts",
     "index.ts",
     "tsconfig.json"
-  ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "clean": "rm -Rf dist"
-  }
-}
+  ]
+}

package/dist/src/schema.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const mongoose = require("mongoose");
-const Schema = mongoose.Schema;
-// define the schema for our user model
-const lockSchema = new Schema({
-    createdAt: {
-        type: Date,
-        default: Date.now
-    },
-    refreshedAt: {
-        type: Date,
-        default: Date.now,
-        // Locks are not supposed to last longer than a minute
-        expires: 60
-    },
-    action: {
-        type: String,
-        unique: true,
-        required: true
-    }
-});
-exports.default = lockSchema;

package/src/schema.ts

@@ -1,23 +0,0 @@
-import * as mongoose from "mongoose";
-const Schema = mongoose.Schema;
-
-// define the schema for our user model
-const lockSchema = new Schema({
-  createdAt: {
-    type: Date,
-    default: Date.now
-  },
-  refreshedAt: {
-    type: Date,
-    default: Date.now,
-    // Locks are not supposed to last longer than a minute
-    expires: 60
-  },
-  action: {
-    type: String,
-    unique: true,
-    required: true
-  }
-});
-
-export default lockSchema;