# datastore-lock

> distributed lock based on google datastore

Latest version **0.1.1** (published 2018-10-11) · ISC license · 0 weekly downloads

## Install

```sh
npm install datastore-lock
pnpm add datastore-lock
yarn add datastore-lock
bun add datastore-lock
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2018-10-11 |
| First published | 2018-10-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 13.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | nishant chaturvedi |
| Maintainers | nishant.c |
| Keywords | Google, Datastore |

## Links

- npm: https://www.npmjs.com/package/datastore-lock
- Repository: https://github.com/nishch/datastore-lock
- Homepage: https://github.com/nishch/datastore-lock#readme
- Issues: https://github.com/nishch/datastore-lock/issues
- npm.io page: https://npm.io/package/datastore-lock

## Dependencies (1)

- [@google-cloud/datastore](https://npm.io/package/@google-cloud/datastore.md) ^2.0.0

## Recent versions

- 0.1.1 (latest) — 2018-10-11
- 0.1.0 — 2018-10-10

## README

## datastore-lock
A lightweight implementation of the distributed lock which is based on [Google Datastore](https://cloud.google.com/datastore/).

### Where to use?
Mainly useful for the application level distributed locks. 

Example Scenario: you have a an application which sends an email based on an external event. If your application is running multiple instances of it and external event triggers an action in all the instances, you might be required to use distributed locks to ensure that NOT all instances end up sending the email and only one mail is being sent.

### What does it offer?
It allows an application to acquire lock for a leased period of time (by default 1 minute, but can be configured using `options`) which will prevent other application instance who complete for it from acquiring the lock, till the first application either releases the lock or leased time gets expired.

### How to use?

1. Download via npm `npm install datastore-lock`.
2. Instantiate
``` js
const dslock = new DSLock(options);
```
3. acquire lock 

``` js
dslock.lock()
    .then(locked => {
        if(locked){
            // lock acquired, do something exclusively
        } else{
            // failed to acquire the lock, not safe to run exclusive logic
        }
    });
```
4. release the lock once done
``` js
dslock.unlock()
    .then(unlocked => {
        if(unlocked){
            // lock released
        } else{
            // could not release the lock
        }
    });
```

### Options

while instantiation you can pass options to configure the datastore-lock

``` js
const dslock = new DSLock(options)
```

`options` object can have following values:

- `projectId` - (required if `dsClient` is not set) google project id which will be used to connect to Google Datastore
- `leaseFor` - (optional) max number of seconds the lock would be available for, after this time runs out and lock is not released, it will automatically get expired. Default value is 60.
- `dsClient` - (required if `projectId` is not set) an instance of Datastore client as described [here](https://cloud.google.com/nodejs/docs/reference/datastore/1.4.x/).
- `keyFilename` - (optional) file path of the Google service account credentials, alternatively you can set `GOOGLE_APPLICATION_CREDENTIALS` env variable.
- `lockKeyName` - (optional) name of the key which will be used while creating the lock in the Datastore. Useful in cases where you want more than one locks in the same application for different functionalities. Default value if *lockKeyName*.
- `namespace` - (optional) Google Datastore namespace to create and store the lock. Default value is *dslock*.

---
_Source: https://npm.io/package/datastore-lock · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._