publish

Author: caiangums

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Codevor - js-library-boilerplate
+Copyright (c) 2019 Codevor - js-semaphore
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,34 +1,110 @@
-# js-library-boilerplate
+# 🚦js-semaphore - Syncronization Using Promises
 
 [![License][license-badge]][license-url] [![Travis CI][travis-badge]][travis-url] [![Coverage Status][coverage-badge]][coverage-url] [![Commitizen][commitizen-badge]][commitizen-url]
 
-> js-library-boilerplate-description.
+🚦`js-semaphore` is a simple **Semaphore** implementation using **Promises** for JavaScript aplications.
+
+If you ever find a need for a syncronization mechanism usage into your application, you can use a Semaphore. If you want to use a Semaphore and you develop in JavaScript, you can use `js-semaphore`!
+
+If your need is simple and a small mechanism with just **1 shared resource**, you can use `js-semaphore` as a **Mutex** too!
+
+The source code comprehends the full **Semaphore** implementation with some basics tests and some applications. Actually, we have:
+
+- 🤔🍜 Philosophers Dinner
+
+#### Common questions
+
+- _Why the tests take so long to complete?_
+
+As this is a Semaphore implementation, the tests are based in time and waiting for a specific resource to continue the execution. We emulate this as a test in order to validate the correct behavior of the lib.
+
+- _Why implement a Semaphore? Using Promises?_
+
+As a common solver for deadlocks avoidance, we found an util lib to create and test! The Promises usage is just a matter of asynchronous need.
 
 ## Installation
 
-js-library-boilerplate is available on npm/yarn:
+`js-semaphore` is available with npm/yarn:
 
 ```bash
-$ npm install js-library-boilerplate --save
-$ yarn add js-library-boilerplate
+$ npm install js-semaphore --save
+$ yarn add js-semaphore
 ```
 
 ## Usage
 
 ### With ES6/import
 
 ```js
-import { sum } from 'js-library-boilerplate';
+import { Semaphore } from 'js-semaphore';
+
+// Semaphore with 1 resource = Mutex
+const semaphore = Semaphore();
+
+// Semaphore with 1 resource, starting at 0 value
+const semaphore = Semaphore({ resource: 1, start: 0 });
 
-sum(2, 2); // => 4
+// Semaphore with 3 resources
+const semaphore = Semaphore({ resource: 3 });
+
+// acquire the semaphore
+semaphore.acquire().then(() => {
+  // Your code goes here
+  const x = 2 + 3;
+
+  // remember to release the semaphore at the end of your usage
+  semaphore.release();
+});
 ```
 
 ### With require
 
 ```js
-const sum = require('js-library-boilerplate').sum;
+const Semaphore = require('js-semaphore').Semaphore;
+
+// Semaphore with 1 resource = Mutex
+const semaphore = Semaphore();
+
+// Semaphore with 1 resource, starting at 0 value
+const semaphore = Semaphore({ resource: 1, start: 0 });
+
+// Semaphore with 3 resources
+const semaphore = Semaphore({ resource: 3 });
+
+// acquire the semaphore
+semaphore.acquire().then(() => {
+  // Your code goes here
+  const x = 2 + 3;
+
+  // remember to release the semaphore at the end of your usage
+  semaphore.release();
+});
+```
+
+### Control timeout
+
+If you want, you can control the timeout. We **hardly** suggest not let this below `0.2s`, but you can try if you want.
+
+```js
+import { Semaphore, setTimespan, timespan } from 'js-semaphore';
+
+// creates the Semaphore
+const semaphore = Semaphore();
+
+// get the actual Timespan
+const actualTimespan = timespan();
+
+// set the actual Timespan, in seconds
+setTimespan(actualTimespan / 2);
+
+// acquire the semaphore
+semaphore.acquire().then(() => {
+  // Your code goes here
+  const x = 2 + 3;
 
-sum(2, 2); // => 4
+  // remember to release the semaphore at the end of your usage
+  semaphore.release();
+});
 ```
 
 ## Contributing
@@ -37,21 +113,21 @@ Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduc
 
 ## Changelog
 
-This project adheres to [Semantic Versioning](https://semver.org/). Every release, along with the migration instructions, is documented on the Github [Releases](https://github.com/codevor/js-library-boilerplate/releases) page.
+This project adheres to [Semantic Versioning](https://semver.org/). Every release, along with the migration instructions, is documented on the Github [Releases](https://github.com/codevor/js-semaphore/releases) page.
 
 ## Bugs and Sugestions
 
-Report bugs or do suggestions using the [issues](https://github.com/codevor/js-library-boilerplate/issues).
+Report bugs or do suggestions using the [issues](https://github.com/codevor/js-semaphore/issues).
 
 ## License
 
 [MIT License](LICENSE) © [Codevor](https://github.com/codevor)
 
-[license-badge]: https://img.shields.io/github/license/codevor/js-library-boilerplate.svg
+[license-badge]: https://img.shields.io/github/license/codevor/js-semaphore.svg
 [license-url]: https://opensource.org/licenses/MIT
-[coverage-badge]: https://coveralls.io/repos/github/codevor/js-library-boilerplate/badge.svg?branch=master
-[coverage-url]: https://coveralls.io/github/codevor/js-library-boilerplate?branch=master
-[travis-badge]: https://travis-ci.org/codevor/js-library-boilerplate.svg?branch=master
-[travis-url]: https://travis-ci.org/codevor/js-library-boilerplate
+[coverage-badge]: https://coveralls.io/repos/github/codevor/js-semaphore/badge.svg?branch=master
+[coverage-url]: https://coveralls.io/github/codevor/js-semaphore?branch=master
+[travis-badge]: https://travis-ci.org/codevor/js-semaphore.svg?branch=master
+[travis-url]: https://travis-ci.org/codevor/js-semaphore
 [commitizen-badge]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg
 [commitizen-url]: http://commitizen.github.io/cz-cli/

package.json

@@ -1,9 +1,9 @@
 {
-  "name": "js-library-boilerplate",
+  "name": "js-semaphore",
   "version": "0.1.0",
-  "description": "js-library-boilerplate-description",
-  "main": "dist/js-library-boilerplate.js",
-  "unpkg": "dist/js-library-boilerplate.min.js",
+  "description": "🚦Semaphore Implementation for JS",
+  "main": "dist/js-semaphore.js",
+  "unpkg": "dist/js-semaphore.min.js",
   "scripts": {
     "clean": "rimraf dist",
     "dev": "NODE_ENV=dev webpack --progress --colors --watch",
@@ -15,17 +15,17 @@
     "prepublish": "yarn lint && yarn test && yarn clean && yarn build:umd",
     "commit": "git-cz"
   },
-  "keywords": [],
-  "author": "Helder Burato Berto <helder.burato@gmail.com> (https://helder.dev/)",
+  "keywords": ["Semaphore", "Syncronization", "Mutex"],
+  "author": "Ilê Caian <ile.caian@gmail.com> (https://ile.pink/)",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/codevor/js-library-boilerplate.git"
+    "url": "git+https://github.com/codevor/js-semaphore.git"
   },
   "bugs": {
-    "url": "https://github.com/codevor/js-library-boilerplate/issues"
+    "url": "https://github.com/codevor/js-semaphore/issues"
   },
-  "homepage": "https://github.com/codevor/js-library-boilerplate#readme",
+  "homepage": "https://github.com/codevor/js-semaphore#readme",
   "devDependencies": {
     "@babel/cli": "^7.6.4",
     "@babel/core": "^7.6.4",
@@ -50,5 +50,10 @@
     "commitizen": {
       "path": "./node_modules/cz-conventional-changelog"
     }
+  },
+  "jest": {
+    "coveragePathIgnorePatterns": [
+      "<rootDir>/tests/utils/"
+    ]
   }
 }

src/constants/semaphore-timespan-seconds.js

@@ -0,0 +1 @@
+export const SEMAPHORE_TIMESPAN_SECONDS = 0.5;

src/index.js

@@ -1,3 +1,3 @@
-export function sum(x, y) {
-  return x + y;
-}
+export { default as Semaphore } from './semaphore';
+export * from './utils/timespan';
+export * from './constants/semaphore-timespan-seconds';

src/semaphore.js

@@ -0,0 +1,33 @@
+import { timespan } from './utils/timespan';
+
+const Semaphore = ({ resources = 1, start = resources } = {}) => {
+  let counter = start >= resources ? resources : start;
+
+  const acquire = () => {
+    if (counter > 0) {
+      counter -= 1;
+      return Promise.resolve();
+    }
+
+    return new Promise(resolve => {
+      setTimeout(() => {
+        acquire().then(() => {
+          resolve();
+        });
+      }, timespan() * 1000);
+    });
+  };
+
+  const release = () => {
+    if (counter < resources) {
+      counter += 1;
+    }
+  };
+
+  return {
+    acquire,
+    release
+  };
+};
+
+export default Semaphore;

src/utils/is-valid-number.js

@@ -0,0 +1,3 @@
+const isValidNumber = value => typeof value === 'number';
+
+export default isValidNumber;

src/utils/timespan.js

@@ -0,0 +1,13 @@
+import isValidNumber from './is-valid-number';
+import { SEMAPHORE_TIMESPAN_SECONDS } from '../constants/semaphore-timespan-seconds';
+
+let userTimespan;
+
+export const timespan = () =>
+  isValidNumber(userTimespan) ? userTimespan : SEMAPHORE_TIMESPAN_SECONDS;
+
+export const setTimespan = value => {
+  if (isValidNumber(value)) {
+    userTimespan = value;
+  }
+};

tests/apps/philosophers-dinner.test.js

@@ -0,0 +1,49 @@
+import { Semaphore } from '../../src';
+import philosopher from './philosophers-dinner/philosopher';
+
+const ENTITIES_COUNT = 5;
+const PHILOSOPHERS_ACTIONS_COUT = 3;
+
+const TEST_TIMEOUT_SECONDS = 20;
+
+jest.setTimeout(TEST_TIMEOUT_SECONDS * 1000);
+
+describe('app/philosophers-dinner', () => {
+  test('run philosophers dinner', () => {
+    const entities = Array.from(new Array(ENTITIES_COUNT).keys());
+    const actionTimes = Array.from(new Array(PHILOSOPHERS_ACTIONS_COUT).keys());
+
+    const chopsticks = entities.map(() => {
+      return Semaphore({ resources: 1, start: 0 });
+    }, []);
+
+    const philosophers = entities.map(entityIndex => {
+      return philosopher({
+        index: entityIndex,
+        entitiesCount: ENTITIES_COUNT,
+        chopsticks
+      });
+    }, []);
+
+    const philosophersPromises = actionTimes.reduce(acc => {
+      return [
+        ...acc,
+        ...philosophers.map(philosopherItem => {
+          return philosopherItem();
+        })
+      ];
+    }, []);
+
+    chopsticks.forEach(chopstick => {
+      chopstick.release();
+    });
+
+    return Promise.all(philosophersPromises).then(data => {
+      expect(data.length).toEqual(ENTITIES_COUNT * PHILOSOPHERS_ACTIONS_COUT);
+
+      data.forEach(value => {
+        expect(value).toBeGreaterThanOrEqual(1);
+      });
+    });
+  });
+});

tests/apps/philosophers-dinner/actions.js

@@ -0,0 +1,18 @@
+export const eat = ({ actionTimeout, chopsticks }) =>
+  new Promise(resolve => {
+    setTimeout(() => {
+      // release chopsticks
+      chopsticks.forEach(chopstick => {
+        chopstick.release();
+      });
+
+      resolve();
+    }, actionTimeout);
+  });
+
+export const think = ({ actionTimeout }) =>
+  new Promise(resolve => {
+    setTimeout(() => {
+      resolve();
+    }, actionTimeout);
+  });

tests/apps/philosophers-dinner/chopstick.js

@@ -0,0 +1,10 @@
+export const getChopsticksIndex = ({ index, entitiesCount }) => {
+  if (index !== entitiesCount - 1) {
+    return [index, index + 1];
+  }
+  return [0, index];
+};
+
+export const getChopstick = chopstick => {
+  return chopstick.acquire();
+};

tests/apps/philosophers-dinner/philosopher.js

@@ -0,0 +1,29 @@
+import { getChopsticksIndex, getChopstick } from './chopstick';
+import { eat, think } from './actions';
+
+const philosopher = ({ index, entitiesCount, chopsticks }) => () =>
+  new Promise(resolve => {
+    const [firstChopstickIndex, secondChopstickIndex] = getChopsticksIndex({
+      index,
+      entitiesCount
+    });
+
+    return getChopstick(chopsticks[firstChopstickIndex]).then(() => {
+      return getChopstick(chopsticks[secondChopstickIndex]).then(() => {
+        const ACTION_TIMEOUT = 200 + index * 100;
+        eat({
+          actionTimeout: ACTION_TIMEOUT,
+          chopsticks: [
+            chopsticks[firstChopstickIndex],
+            chopsticks[secondChopstickIndex]
+          ]
+        }).then(() => {
+          think({ actionTimeout: ACTION_TIMEOUT }).then(() => {
+            resolve(index + 1);
+          });
+        });
+      });
+    });
+  });
+
+export default philosopher;