mini-semaphore 1.3.4 → 1.3.10

package/README.md

@@ -1,4 +1,14 @@
-[![Build Status](https://travis-ci.com/jeffy-g/mini-semaphore.svg?branch=master)](https://travis-ci.com/jeffy-g/mini-semaphore) ![GitHub](https://img.shields.io/github/license/jeffy-g/mini-semaphore?style=plastic)
+[![CircleCI](https://circleci.com/gh/jeffy-g/mini-semaphore/tree/master.svg?style=svg)](https://circleci.com/gh/jeffy-g/mini-semaphore/tree/master)
+![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)
+[![Total alerts](https://img.shields.io/lgtm/alerts/g/jeffy-g/mini-semaphore.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/jeffy-g/mini-semaphore/alerts/)
+[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/jeffy-g/mini-semaphore.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/jeffy-g/mini-semaphore/context:javascript)
+
+![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,15 +1,65 @@
 "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);
     }
@@ -22,6 +72,10 @@ class MiniSemaphore {
     get pending() {
         return this.q.length;
     }
+    /**
+     * automatic acquire/release
+     * @param process
+     */
     async flow(process, lazy) {
         await a(this, lazy);
         try {
@@ -32,4 +86,4 @@ class MiniSemaphore {
         }
     }
 }
-exports.MiniSemaphore = MiniSemaphore;
+exports.MiniSemaphore = MiniSemaphore;

package/cjs/core.js

@@ -2,6 +2,27 @@
 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();
@@ -10,6 +31,12 @@ const box = (z, r) => {
         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) {
@@ -21,14 +48,18 @@ const acquire = (dis, lazy = true) => {
     });
 };
 exports.acquire = acquire;
+/**
+ * @param {TFlowableLock} dis
+ * @returns {void}
+ */
 const release = (dis) => {
     dis.capacity++;
     if (dis.q.length) {
-        dis.capacity -= 1, (dis.q.shift() || extras_1.THROW)();
+        dis.capacity -= 1, (dis.q.shift() || /* istanbul ignore next */ extras_1.THROW)();
     }
     if (dis.capacity > dis.limit) {
         console.warn("inconsistent release!");
         dis.capacity = dis.limit;
     }
 };
-exports.release = release;
+exports.release = release;

package/cjs/deque.js

@@ -1,12 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Deque = void 0;
-const am = (src, si, dst, di, len) => {
+/**
+ * arrayMove
+ *
+ * @param src
+ * @param si
+ * @param dst
+ * @param di
+ * @param len
+ */
+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;
@@ -17,16 +30,34 @@ const p2l = (n) => {
     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) {
@@ -38,6 +69,7 @@ class Deque {
     }
     shift() {
         const l = this._l;
+        /* istanbul ignore if */
         if (l === 0) {
             return void 0;
         }
@@ -53,13 +85,19 @@ class Deque {
     }
 }
 exports.Deque = Deque;
+/**
+ * resize to
+ *
+ * @param n expected capacity
+ */
 const rt = (dis, n) => {
     const oc = dis._c;
     dis._c = n;
     const f = dis._f;
     const l = dis._l;
+    /* istanbul ignore next */
     if (f + l > oc) {
         const mc = (f + l) & (oc - 1);
         am(dis._a, 0, dis._a, oc, mc);
     }
-};
+};

package/cjs/extras.js

@@ -4,4 +4,4 @@ exports.THROW = void 0;
 const THROW = () => {
     throw new Error("mini-semaphore: inconsistent occurred");
 };
-exports.THROW = THROW;
+exports.THROW = THROW;

package/cjs/flow-restrictor.js

@@ -1,12 +1,42 @@
 "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];
@@ -20,12 +50,28 @@ var restrictor;
         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;
@@ -33,7 +79,7 @@ var restrictor;
         const keys = Object.keys(currentLocks);
         let eliminatedCount = 0;
         let eliminatedKeys;
-        !timeSpan && (timeSpan = 1);
+        !timeSpan && /* istanbul ignore next */ (timeSpan = 1);
         timeSpan *= 1000;
         if (debug) {
             eliminatedKeys = [];
@@ -59,6 +105,14 @@ var restrictor;
         }
         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);
@@ -66,8 +120,18 @@ var restrictor;
         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 || (exports.restrictor = {}));
+})(restrictor = exports.restrictor || (exports.restrictor = {}));

package/cjs/index.d.ts

@@ -94,8 +94,6 @@ export declare type TFlowableLock<T = TVoidFunction> = IFlowableLock & {
     readonly q: Deque<T>;
 };
 export declare type TVoidFunction = () => void;
-// export declare const acquire: (dis: TFlowableLock<TVoidFunction>, lazy?: boolean) => Promise<void>;
-// export declare const release: (dis: TFlowableLock<TVoidFunction>) => void;
 
 
 /**

package/cjs/index.js

@@ -1,6 +1,13 @@
 "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 = exports.Deque = exports.create = exports.MiniSemaphore = void 0;
+exports.version = exports.restrictor = exports.Deque = exports.create = exports.MiniSemaphore = void 0;
 var class_1 = require("./class");
 Object.defineProperty(exports, "MiniSemaphore", { enumerable: true, get: function () { return class_1.MiniSemaphore; } });
 var object_1 = require("./object");
@@ -9,3 +16,4 @@ var deque_1 = require("./deque");
 Object.defineProperty(exports, "Deque", { enumerable: true, get: function () { return deque_1.Deque; } });
 var flow_restrictor_1 = require("./flow-restrictor");
 Object.defineProperty(exports, "restrictor", { enumerable: true, get: function () { return flow_restrictor_1.restrictor; } });
+exports.version = "v1.3.10";

package/cjs/object.js

@@ -1,27 +1,62 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.create = 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 (object 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;
+/**
+ * object implementation of `IFlowableLock`
+ *
+ *   + constructs a semaphore object limited at `capacity`
+ *
+ * @param {number} capacity limitation of concurrent async by `capacity`
+ * @date 2020/2/7
+ * @version 1.0
+ */
 const create = (capacity) => {
     return {
         capacity,
         limit: capacity,
         q: new deque_1.Deque(capacity),
+        /**
+         *
+         * @param {boolean} [lazy]
+         * @returns {Promise<void>}
+         */
         acquire(lazy) {
             return a(this, lazy);
         },
         release() {
             r(this);
         },
+        /**
+         * @param {number} restriction
+         */
         setRestriction(restriction) {
             this.limit = this.capacity = restriction;
         },
         get pending() {
             return this.q.length;
         },
+        /**
+         * @template {any} T
+         * @param {() => Promise<T>} process
+         * @param {boolean} [lazy]
+         * @returns {Promise<T>}
+         */
         async flow(process, lazy) {
             await a(this, lazy);
             try {
@@ -33,4 +68,4 @@ const create = (capacity) => {
         }
     };
 };
-exports.create = create;
+exports.create = create;

package/esm/class.mjs

@@ -0,0 +1,85 @@
+/*!
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  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
+ */
+import * as core from "./core.mjs";
+import { Deque } from "./deque.mjs";
+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
+ */
+export 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(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
+     * @param process
+     */
+    async flow(process, lazy) {
+        await a(this, lazy);
+        try {
+            return await process();
+        }
+        finally {
+            r(this);
+        }
+    }
+}

package/esm/core.mjs

@@ -0,0 +1,60 @@
+import { THROW } from "./extras.mjs";
+/**
+ * @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>}
+ */
+export const acquire = (dis, lazy = true) => {
+    return new Promise(r => {
+        if (!lazy) {
+            box(dis, r);
+        }
+        else {
+            setTimeout(() => box(dis, r), 4);
+        }
+    });
+};
+/**
+ * @param {TFlowableLock} dis
+ * @returns {void}
+ */
+export const release = (dis) => {
+    dis.capacity++;
+    if (dis.q.length) {
+        dis.capacity -= 1, (dis.q.shift() || /* istanbul ignore next */ THROW)();
+    }
+    if (dis.capacity > dis.limit) {
+        console.warn("inconsistent release!");
+        dis.capacity = dis.limit;
+    }
+};