mini-semaphore 1.3.9 → 1.3.12

package/README.md

@@ -1,5 +1,12 @@
 [![CircleCI](https://circleci.com/gh/jeffy-g/mini-semaphore/tree/master.svg?style=svg)](https://circleci.com/gh/jeffy-g/mini-semaphore/tree/master)
+[![codecov](https://codecov.io/gh/jeffy-g/mini-semaphore/graph/badge.svg?token=SEEIAGR8HW)](https://codecov.io/gh/jeffy-g/mini-semaphore)
 ![GitHub](https://img.shields.io/github/license/jeffy-g/mini-semaphore?style=plastic)
+[![npm version](https://badge.fury.io/js/mini-semaphore.svg)](https://badge.fury.io/js/mini-semaphore)
+![node](https://img.shields.io/node/v/mini-semaphore.svg?style=plastic)
+![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/jeffy-g/mini-semaphore.svg?style=plastic)
+![npm bundle size](https://img.shields.io/bundlephobia/min/mini-semaphore?style=plastic)
+![npm](https://img.shields.io/npm/dm/mini-semaphore.svg?style=plastic)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/m/jeffy-g/mini-semaphore.svg?style=plastic)
 
 # Mini Semaphore (mini-semaphore
 

package/cjs/class.js

@@ -1,42 +1,92 @@
-"use strict";
-/*!
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-  Copyright (C) 2020 jeffy-g <hirotom1107@gmail.com>
-  Released under the MIT license
-  https://opensource.org/licenses/mit-license.php
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-*/
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MiniSemaphore = void 0;
-const core = require("./core");
-const deque_1 = require("./deque");
-const a = core.acquire;
-const r = core.release;
-class MiniSemaphore {
-    constructor(capacity) {
-        this.limit = this.capacity = capacity;
-        this.q = new deque_1.Deque(capacity);
-    }
-    acquire(lazy) {
-        return a(this, lazy);
-    }
-    release() {
-        r(this);
-    }
-    setRestriction(restriction) {
-        this.limit = this.capacity = restriction;
-    }
-    get pending() {
-        return this.q.length;
-    }
-    async flow(process, lazy) {
-        await a(this, lazy);
-        try {
-            return await process();
-        }
-        finally {
-            r(this);
-        }
-    }
-}
-exports.MiniSemaphore = MiniSemaphore;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiniSemaphore = void 0;
+/*!
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  Copyright (C) 2020 jeffy-g <hirotom1107@gmail.com>
+  Released under the MIT license
+  https://opensource.org/licenses/mit-license.php
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file minimal implementation of semaphore (class implementation
+ * @author jeffy-g <hirotom1107@gmail.com>
+ * @version 1.0
+ */
+const core = require("./core");
+const deque_1 = require("./deque");
+const a = core.acquire;
+const r = core.release;
+/**
+ * #### Mini Semaphore
+ *
+ *   + minimal implementation of semaphore
+ *
+ * @example
+ * import { MiniSemaphore } from "mini-semaphore";
+ *
+ * const s = new MiniSemaphore(10);
+ * async function fetchTypeData(type_id) {
+ *   await s.acquire();
+ *   try {
+ *       return fetch(`https://esi.evetech.net/latest/universe/types/${type_id}/`);
+ *   } finally {
+ *       s.release();
+ *   }
+ * }
+ *
+ * //
+ * // or automatic acquire/release
+ * //
+ * async function fetchTypeData(type_id) {
+ *   return s.flow(async () => fetch(`https://esi.evetech.net/latest/universe/types/${type_id}/`));
+ * }
+ *
+ * @date 2020/2/7
+ * @version 1.0
+ */
+class MiniSemaphore {
+    /**
+     * constructs a semaphore instance limited at `capacity`
+     *
+     * @param capacity limitation of concurrent async by `capacity`
+     */
+    constructor(capacity) {
+        this.limit = this.capacity = capacity;
+        this.q = new deque_1.Deque(capacity);
+    }
+    /**
+     * If there is enough capacity, execute the `resolve` immediately
+     *
+     * If not, put it in a queue and wait for the currently pending process to execute `release`
+     */
+    acquire(lazy) {
+        return a(this, lazy);
+    }
+    release() {
+        r(this);
+    }
+    setRestriction(restriction) {
+        this.limit = this.capacity = restriction;
+    }
+    get pending() {
+        return this.q.length;
+    }
+    /**
+     * automatic acquire/release
+     *
+     * @template {any} T description
+     * @param {() => Promise<T>} process
+     * @param {boolean=} lazy
+     */
+    async flow(process, lazy) {
+        await a(this, lazy);
+        try {
+            return await process();
+        }
+        finally {
+            r(this);
+        }
+    }
+}
+exports.MiniSemaphore = MiniSemaphore;

package/cjs/core.js

@@ -1,41 +1,67 @@
-"use strict";
-/*!
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-  Copyright (C) 2020 jeffy-g <hirotom1107@gmail.com>
-  Released under the MIT license
-  https://opensource.org/licenses/mit-license.php
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-*/
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.release = exports.acquire = void 0;
-const extras_1 = require("./extras");
-const box = (z, r) => {
-    if (z.capacity > 0) {
-        z.capacity--, r();
-    }
-    else {
-        z.q.push(r);
-    }
-};
-const acquire = (dis, lazy = true) => {
-    return new Promise(r => {
-        if (!lazy) {
-            box(dis, r);
-        }
-        else {
-            setTimeout(() => box(dis, r), 4);
-        }
-    });
-};
-exports.acquire = acquire;
-const release = (dis) => {
-    dis.capacity++;
-    if (dis.q.length) {
-        dis.capacity -= 1, (dis.q.shift() || extras_1.THROW)();
-    }
-    if (dis.capacity > dis.limit) {
-        console.warn("inconsistent release!");
-        dis.capacity = dis.limit;
-    }
-};
-exports.release = release;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.release = exports.acquire = void 0;
+const extras_1 = require("./extras");
+/**
+ * @typedef ISimplifiedLock
+ * @prop {(lazy?: boolean) => Promise<void>} acquire acquire the process rights&#64;param lazy Whether the privilege acquisition process is deffer. default `true`
+ * @prop {() => void} release release the pending of one
+ * @prop {(restriction: number) => void} setRestriction Change sharing restrictions to the value of `restriction`&#64;param {number} restriction
+ * @prop {number} pending Get the number of currently pending processes&#64;type {number}
+ * @prop {number} limit limitation
+ * @prop {number} capacity capacity
+ */
+/**
+ * @typedef {<T>(f: () => Promise<T>, lazy?: boolean) => Promise<T>} TFlow
+ * @typedef {ISimplifiedLock & { flow: TFlow }} IFlowableLock
+ * @typedef {() => void} TVoidFunction
+ * @typedef {import("./deque").Deque} Deque
+ * @typedef {IFlowableLock & { readonly q: Deque }} TFlowableLock
+ */
+/**
+ *
+ * @param {TFlowableLock} z
+ * @param {TVoidFunction} r
+ */
+const box = (z, r) => {
+    if (z.capacity > 0) {
+        z.capacity--, r();
+    }
+    else {
+        z.q.push(r);
+    }
+};
+/**
+ *
+ * @param {TFlowableLock} dis
+ * @param {boolean} [lazy] default: true
+ * @returns {Promise<void>}
+ */
+const acquire = (dis, lazy = true) => {
+    return new Promise(r => {
+        if (!lazy) {
+            box(dis, r);
+        }
+        else {
+            setTimeout(() => box(dis, r), 4);
+        }
+    });
+};
+exports.acquire = acquire;
+/**
+ * @param {TFlowableLock} dis
+ * @returns {void}
+ */
+const release = (dis) => {
+    if (dis.q.length) {
+        (dis.q.shift() || /* istanbul ignore next */ extras_1.THROW)();
+    }
+    else {
+        dis.capacity++;
+    }
+    if (dis.capacity > dis.limit) {
+        console.warn("inconsistent release!");
+        dis.capacity = dis.limit;
+    }
+};
+exports.release = release;

package/cjs/deque.js

@@ -1,65 +1,102 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Deque = void 0;
-const am = (src, si, dst, di, len) => {
-    for (let j = 0; j < len; ++j) {
-        dst[j + di] = src[j + si];
-        src[j + si] = void 0;
-    }
-};
-const p2l = (n) => {
-    n = n >>> 0;
-    n = n - 1;
-    n = n | (n >> 1);
-    n = n | (n >> 2);
-    n = n | (n >> 4);
-    n = n | (n >> 8);
-    n = n | (n >> 16);
-    return n + 1;
-};
-const gc = (n) => {
-    return p2l(Math.min(Math.max(16, n | 0), 1073741824));
-};
-class Deque {
-    constructor(ic) {
-        this._c = gc(ic);
-        this._l = 0;
-        this._f = 0;
-        this._a = [];
-    }
-    push(s) {
-        const l = this._l;
-        if (this._c < l + 1) {
-            rt(this, gc(this._c * 1.5 + 16));
-        }
-        const i = (this._f + l) & (this._c - 1);
-        this._a[i] = s;
-        this._l = l + 1;
-    }
-    shift() {
-        const l = this._l;
-        if (l === 0) {
-            return void 0;
-        }
-        const f = this._f;
-        const r = this._a[f];
-        this._a[f] = void 0;
-        this._f = (f + 1) & (this._c - 1);
-        this._l = l - 1;
-        return r;
-    }
-    get length() {
-        return this._l;
-    }
-}
-exports.Deque = Deque;
-const rt = (dis, n) => {
-    const oc = dis._c;
-    dis._c = n;
-    const f = dis._f;
-    const l = dis._l;
-    if (f + l > oc) {
-        const mc = (f + l) & (oc - 1);
-        am(dis._a, 0, dis._a, oc, mc);
-    }
-};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deque = void 0;
+/**
+ * arrayMove
+ *
+ * @param src
+ * @param si source index
+ * @param dst
+ * @param di dest index
+ * @param len move count
+ */
+const am = /* istanbul ignore next */ (src, si, dst, di, len) => {
+    for (let j = 0; j < len; ++j) {
+        dst[j + di] = src[j + si];
+        src[j + si] = void 0;
+    }
+};
+/**
+ * pow2AtLeast
+ * @param n
+ */
+const p2l = (n) => {
+    n = n >>> 0;
+    n = n - 1;
+    n = n | (n >> 1);
+    n = n | (n >> 2);
+    n = n | (n >> 4);
+    n = n | (n >> 8);
+    n = n | (n >> 16);
+    return n + 1;
+};
+/**
+ * getCapacity
+ * @param n
+ */
+const gc = (n) => {
+    // @ts-ignore typescript cannot allow (undefined | 0) expression
+    return p2l(Math.min(Math.max(16, n | 0), 1073741824));
+};
+/**
+ * ### Implementation restricted to FIFO
+ *
+ * this class is based on https://github.com/petkaantonov/deque/blob/master/js/deque.js
+ * Released under the MIT License: https://github.com/petkaantonov/deque/blob/master/LICENSE
+ */
+class Deque {
+    /**
+     * default capacity `16`
+     * @param ic initial capacity
+     */
+    constructor(ic) {
+        this._c = gc(ic);
+        this._l = 0;
+        this._f = 0;
+        this._a = [];
+    }
+    /**
+     * @param s subject
+     */
+    push(s) {
+        const l = this._l;
+        if (this._c < l + 1) {
+            rt(this, gc(this._c * 1.5 + 16));
+        }
+        const i = (this._f + l) & (this._c - 1);
+        this._a[i] = s;
+        this._l = l + 1;
+    }
+    shift() {
+        const l = this._l;
+        /* istanbul ignore if */
+        if (l === 0) {
+            return void 0;
+        }
+        const f = this._f;
+        const r = this._a[f];
+        this._a[f] = void 0;
+        this._f = (f + 1) & (this._c - 1);
+        this._l = l - 1;
+        return r;
+    }
+    get length() {
+        return this._l;
+    }
+}
+exports.Deque = Deque;
+/**
+ * resize to
+ *
+ * @param n expected capacity
+ */
+const rt = (dis, n) => {
+    const oc = dis._c;
+    dis._c = n;
+    const lastIndex = dis._f + dis._l;
+    /* istanbul ignore next */
+    if (lastIndex > oc) {
+        const mc = (lastIndex) & (oc - 1);
+        am(dis._a, 0, dis._a, oc, mc);
+    }
+};

package/cjs/extras.js

@@ -1,7 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.THROW = void 0;
-const THROW = () => {
-    throw new Error("mini-semaphore: inconsistent occurred");
-};
-exports.THROW = THROW;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.THROW = void 0;
+const THROW = () => {
+    throw new Error("mini-semaphore: inconsistent occurred");
+};
+exports.THROW = THROW;

package/cjs/flow-restrictor.js

@@ -1,80 +1,137 @@
-"use strict";
-/*!
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-  Copyright (C) 2020 jeffy-g <hirotom1107@gmail.com>
-  Released under the MIT license
-  https://opensource.org/licenses/mit-license.php
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-*/
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.restrictor = void 0;
-const c = require("./class");
-var restrictor;
-(function (restrictor) {
-    const { MiniSemaphore: MS } = c;
-    const internalLock = new MS(1);
-    let locks = Object.create(null);
-    const get = async (key, restriction) => {
-        await internalLock.acquire(false);
-        let lock = locks[key];
-        if (!lock) {
-            locks[key] = lock = new MS(restriction);
-        }
-        if (lock.limit !== restriction) {
-            internalLock.release();
-            throw new ReferenceError(`Cannot get object with different restriction: key: '${key}', lock.limit: ${lock.limit} <-> restriction: ${restriction},`);
-        }
-        internalLock.release();
-        return lock;
-    };
-    restrictor.getLockByKey = async (key) => {
-        await internalLock.acquire(false);
-        const l = locks[key];
-        internalLock.release();
-        return l;
-    };
-    restrictor.cleanup = async (timeSpan, debug) => {
-        await internalLock.acquire(false);
-        const currentLocks = locks;
-        const newLocks = Object.create(null);
-        const keys = Object.keys(currentLocks);
-        let eliminatedCount = 0;
-        let eliminatedKeys;
-        !timeSpan && (timeSpan = 1);
-        timeSpan *= 1000;
-        if (debug) {
-            eliminatedKeys = [];
-        }
-        for (let i = 0, end = keys.length; i < end;) {
-            const key = keys[i++];
-            const s = currentLocks[key];
-            if (s.last && Date.now() - s.last >= timeSpan) {
-                eliminatedCount++;
-                if (debug) {
-                    eliminatedKeys.push(key);
-                }
-                continue;
-            }
-            newLocks[key] = s;
-        }
-        locks = newLocks;
-        internalLock.release();
-        if (debug) {
-            console.log(`eliminated: [\n${eliminatedKeys.join(",\n")}\n]` +
-                "\n" +
-                `lived: [\n${Object.keys(newLocks).join(",\n")}\n]`);
-        }
-        return eliminatedCount;
-    };
-    async function multi(key, restriction, pb) {
-        const s = await get(key, restriction);
-        const result = s.flow(pb);
-        s.last = Date.now();
-        return result;
-    }
-    restrictor.multi = multi;
-    async function one(key, pb) {
-        return multi(key, 1, pb);
-    }
-    restrictor.one = one;
-})(restrictor = exports.restrictor || (exports.restrictor = {}));
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restrictor = void 0;
+/*!
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  Copyright (C) 2020 jeffy-g <hirotom1107@gmail.com>
+  Released under the MIT license
+  https://opensource.org/licenses/mit-license.php
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file Utility module using `MiniSemaphore`
+ * @author jeffy-g <hirotom1107@gmail.com>
+ * @version 1.0
+ */
+const c = require("./class");
+/**
+ * @typedef {string | number} TLockRecordKey
+ */
+/**
+ * Flow Restriction
+ */
+var restrictor;
+(function (restrictor) {
+    const { MiniSemaphore: MS } = c;
+    /**
+     * @internal
+     */
+    const internalLock = new MS(1);
+    /**
+     *
+     */
+    let locks = Object.create(null);
+    /**
+     *
+     * @param {TLockRecordKey} key
+     * @param {number} restriction
+     * @throws when different restriction
+     */
+    const get = async (key, restriction) => {
+        await internalLock.acquire(false);
+        let lock = locks[key];
+        if (!lock) {
+            locks[key] = lock = new MS(restriction);
+        }
+        if (lock.limit !== restriction) {
+            internalLock.release();
+            throw new ReferenceError(`Cannot get object with different restriction: key: '${key}', lock.limit: ${lock.limit} <-> restriction: ${restriction},`);
+        }
+        internalLock.release();
+        return lock;
+    };
+    /**
+     * get the semaphore associated with the value of `key`
+     *
+     *   + ⚠️ The object to be retrieved with `key` must already be created with `multi` ore `one`
+     *
+     * @param {TLockRecordKey} key
+     * @returns `IFlowableLock` instance or `undefined`
+     */
+    restrictor.getLockByKey = async (key) => {
+        await internalLock.acquire(false);
+        const l = locks[key];
+        internalLock.release();
+        return l;
+    };
+    /**
+     * Eliminate unused instances for the `timeSpan` seconds
+     *
+     * @param {number} timeSpan specify unit as seconds
+     * @param {true} [debug] enable debug
+     * @returns {Promise<number>} eliminated count
+     * @date 2020/6/19
+     */
+    restrictor.cleanup = async (timeSpan, debug) => {
+        await internalLock.acquire(false);
+        const currentLocks = locks;
+        const newLocks = Object.create(null);
+        const keys = Object.keys(currentLocks);
+        let eliminatedCount = 0;
+        let eliminatedKeys;
+        !timeSpan && /* istanbul ignore next */ (timeSpan = 1);
+        timeSpan *= 1000;
+        if (debug) {
+            eliminatedKeys = [];
+        }
+        for (let i = 0, end = keys.length; i < end;) {
+            const key = keys[i++];
+            const s = currentLocks[key];
+            if (s.last && Date.now() - s.last >= timeSpan) {
+                eliminatedCount++;
+                if (debug) {
+                    eliminatedKeys.push(key);
+                }
+                continue;
+            }
+            newLocks[key] = s;
+        }
+        locks = newLocks;
+        internalLock.release();
+        if (debug) {
+            console.log(`eliminated: [\n${eliminatedKeys.join(",\n")}\n]` +
+                "\n" +
+                `lived: [\n${Object.keys(newLocks).join(",\n")}\n]`);
+        }
+        return eliminatedCount;
+    };
+    /**
+     * Allocate a semaphore for each `key`, and limit the number of shares with the value of `restriction`
+     *
+     * @template {any} T
+     * @param {TLockRecordKey} key number or string as tag
+     * @param {number} restriction number of process restriction
+     * @param {() => Promise<T>} pb the process body
+     */
+    async function multi(key, restriction, pb) {
+        const s = await get(key, restriction);
+        const result = s.flow(pb);
+        s.last = Date.now();
+        return result;
+    }
+    restrictor.multi = multi;
+    /**
+     * synonym of `multi(key, 1, pb)`
+     *
+     *  + use case
+     *    * Avoid concurrent requests to the same url
+     *
+     * @template {any} T
+     * @param {TLockRecordKey} key number or string as tag
+     * @param {() => Promise<T>} pb the process body
+     */
+    async function one(key, pb) {
+        return multi(key, 1, pb);
+    }
+    restrictor.one = one;
+})(restrictor || (exports.restrictor = restrictor = {}));