New function names for clarity (#14)

* New function names for clarity

The function names `v()` and `p()` in this library were
accidentally reversed from the tradition. Since the function names
might be a bit confusing even if named correctly, we should rename
them as `acquire()` and `release()` but also provide the old names
for backwards compatibility.

Fixes #13

* Missed this

* Add deprecation warnings

* Fix ts definitions

Author: OlliV

examples/basic.js

@@ -16,10 +16,10 @@ async function f () {
 
   const s = new Sema(13, { capacity: arr.length })
   await Promise.all(arr.map(async (elem) => {
-    await s.v()
+    await s.acquire()
     console.log(elem, s.nrWaiting())
     await new Promise((resolve) => setTimeout(resolve, getRnd(500, 3000)))
-    s.p()
+    s.release()
   }))
   console.log('hello')
 }

examples/pausing.js

@@ -23,11 +23,11 @@ function resume() {
 
 const s = new Sema(5, { pauseFn: pause, resumeFn: resume })
 async function parse(line) {
-  await s.v()
+  await s.acquire()
 
   console.log(line)
 
-  s.p()
+  s.release()
 }
 
 rl.on('line', (line) => {

examples/pooling.js

@@ -6,9 +6,9 @@ const redis = require('promise-redis')
 async function f () {
   const red = new Sema(3, { initFn: () => redis().createClient(process.env.REDIS_URL) })
 
-  const db = await red.v()
+  const db = await red.acquire()
   console.log(await db.get('id'))
-  red.p(db)
+  red.release(db)
 
   const dbs = await red.drain()
   dbs.map((db) => db.quit())

index.d.ts

@@ -8,10 +8,14 @@ declare module 'async-sema' {
     drain(): Promise<string[]>;
 
     nrWaiting(): number;
+
+    v(): Promise<string>;
+
+    acquire(): Promise<string>;
 
     p(token?: string): void;
-    
-    v(): Promise<string>;
+
+    release(token?: string): void;
 
   }
 

index.js

@@ -1,5 +1,6 @@
 // Native
 const EventEmitter = require('events')
+const util = require('util')
 
 // Packages
 const Deque = require('double-ended-queue')
@@ -43,7 +44,7 @@ class Sema {
     }
   }
 
-  async v () {
+  async acquire () {
     let token = this.free.pop()
 
     if (token) {
@@ -59,15 +60,21 @@ class Sema {
       this.waiting.push({ resolve, reject })
     })
   }
+  async v () {
+    return this.acquire();
+  }
 
-  p (token) {
+  release (token) {
     this.releaseEmitter.emit('release', this.noTokens ? '1' : token)
   }
+  p (token) {
+    return this.release(token)
+  }
 
   drain () {
     const a = new Array(this.nrTokens)
     for (let i = 0; i < this.nrTokens; i++) {
-      a[i] = this.v()
+      a[i] = this.acquire()
     }
     return Promise.all(a)
   }
@@ -77,4 +84,6 @@ class Sema {
   }
 }
 
+Sema.prototype.v = util.deprecate(Sema.prototype.v, '`v()` is deperecated; use `acquire()` instead')
+Sema.prototype.p = util.deprecate(Sema.prototype.p, '`p()` is deprecated; use `release()` instead')
 module.exports = Sema

rate-limit.js

@@ -4,7 +4,7 @@ module.exports = function rateLimit(rps) {
   const sema = new Sema(rps);
 
   return async function rl() {
-    await sema.v();
-    setTimeout(() => sema.p(), 1000);
+    await sema.acquire();
+    setTimeout(() => sema.release(), 1000);
   }
 }