Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dizmo/functions-lock
dizmoFun: lock acquisition & release
https://github.com/dizmo/functions-lock
acquire dizmo lock release typescript
Last synced: about 15 hours ago
JSON representation
dizmoFun: lock acquisition & release
- Host: GitHub
- URL: https://github.com/dizmo/functions-lock
- Owner: dizmo
- License: isc
- Created: 2021-08-16T20:06:14.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2022-11-16T19:21:34.000Z (almost 2 years ago)
- Last Synced: 2024-04-21T08:11:26.157Z (7 months ago)
- Topics: acquire, dizmo, lock, release, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@dizmo/functions-lock
- Size: 922 KB
- Stars: 0
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://npmjs.org/package/@dizmo/functions-lock)
[](https://travis-ci.com/dizmo/functions-lock)
[](https://coveralls.io/github/dizmo/functions-lock?branch=master)
# @dizmo/functions-lock
Provides a `Lock` class, which can be used to acquire and release (enumerated) locks – where each lock can also be anonymous or named.
Per lock an internal *identity context* is associated, where the corresponding data is stored as an (`ephemeral-id`, `session-id`) tuple. The `ephemeral-id` is stored in the `global` (aka the `window`) object, and the `session-id` in the `localStorage` – if available, otherwise again the `global` object is used.
> Locks with the same name share the same identity, but each lock number is treated separately.
A lock will *always* permit to be acquired, if the identity context is the same! However, this behaviour can be overridden by providing a flag to *clear* the internal identity (of a named lock), which will cause the lock to *not* be acquired – if another lock with the same name as already been acquired.
Upon a successful acquisition a positive number (larger than `0`) will be returned, which indicates the amount of time (in milliseconds) it took to acquire the lock; a failure to acquire it will result in a `null` object. Upon a successful release a `true` value will be returned (else the result will be `false`).
## Usage
### Installation
```sh
npm install @dizmo/functions-lock --save
```
### Require
```typescript
import { Lock } from '@dizmo/functions-lock';
```
### Example(s)
#### Acquire and release lock
```typescript
const lock = new Lock();
if (await lock.acquire()) {
if (await lock.release()) {
console.debug('lock acquired and released');
} else {
console.debug('lock acquired but *not* released');
}
} else {
console.debug('lock *not* acquired');
}
```
#### Acquire and release lock at index=0 (default) with no expiration (default)
```typescript
const lock = new Lock();
if (await lock.acquire(0)) {
if (await lock.release(0)) {
console.debug('lock acquired @index=0 and released');
} else {
console.debug('lock acquired @index=0 but *not* released');
}
} else {
console.debug('lock @index=0 *not* acquired');
}
```
#### Acquire and release lock at index=0 (default) with an expiration of one minute
```typescript
const lock = new Lock(), expiry_ms = 60 * 1000; // one minute
if (await lock.acquire(0, expiry_ms)) {
if (await lock.release(0)) {
console.debug('lock acquired and released');
} else {
console.debug('lock acquired but *not* released');
}
} else {
console.debug('lock *not* acquired');
}
```
#### Acquire and release named lock at index=1
```typescript
const lock = new Lock('my-lock');
if (await lock.acquire(1)) {
if (await lock.release(1)) {
console.debug('named lock @index=1 acquired and released');
} else {
console.debug('named lock @index=1 acquired but *not* released');
}
} else {
console.debug('named lock @index=1 *not* acquired');
}
```
#### Acquire (twice) and release named lock at index=2
```typescript
const lock = new Lock('my-lock');
if (await lock.acquire(2)) {
if (await lock.acquire(2)) {
if (await lock.release(2)) {
console.debug('named lock @index=2 acquired and released');
} else {
console.debug('named lock @index=2 acquired but *not* released');
}
} else {
console.debug('named lock @index=2 *not* acquired (2nd time)');
}
} else {
console.debug('named lock @index=2 *not* acquired (1st time)');
}
```
#### Acquire (twice) and release named lock at index=2 with ID clearing
```typescript
const lock = new Lock('my-lock', true); // clear ID i.e. "fake" another context!
if (await lock.acquire(2)) {
if (await lock.acquire(2)) {
if (await lock.release(2)) {
console.debug('named lock @index=2 acquired and released');
} else {
console.debug('named lock @index=2 acquired but *not* released');
}
} else {
console.debug('named lock @index=2 *not* acquired (2nd time)');
}
} else {
console.debug('named lock @index=2 *not* acquired (1st time)');
}
```
## Development
### Clean
```sh
npm run clean
```
### Build
```sh
npm run build
```
#### without linting and cleaning:
```sh
npm run -- build --no-lint --no-clean
```
#### with UMD bundling (incl. minimization):
```sh
npm run -- build --prepack
```
#### with UMD bundling (excl. minimization):
```sh
npm run -- build --prepack --no-minify
```
### Lint
```sh
npm run lint
```
#### with auto-fixing:
```sh
npm run -- lint --fix
```
### Test
```sh
npm run test
```
#### without linting, cleaning and (re-)building:
```sh
npm run -- test --no-lint --no-clean --no-build
```
### Cover
```sh
npm run cover
```
#### without linting, cleaning and (re-)building:
```sh
npm run -- cover --no-lint --no-clean --no-build
```
## Debugging
Connect `@dizmo/functions-lock` to another project:
```sh
[@dizmo/functions-lock] $ npm link # symlink global:@dizmo/functions-lock
```
```sh
[a-project] $ npm link @dizmo/functions-lock # symlink node-modules:@dizmo/functions-lock
```
```sh
[a-project] $ head webpack.config.js # ensure @dizmo/functions-lock in entry.main
```
```
entry: {
main: [..., '@dizmo/functions-lock', './source/index.js']
}
```
Disconnect `@dizmo/functions-lock` from the project:
```sh
[a-project] $ npm unlink @dizmo/functions-lock # delete local symlink
```
```sh
[@dizmo/functions-lock] $ npm uninstall -g # delete global symlink
```
## Documentation
```sh
npm run docs
```
## Publication
```sh
npm publish
```
#### initially (if public):
```sh
npm publish --access=public
```
## Copyright
© 2021 [dizmo AG](https://dizmo.com/), Switzerland