A "standard library" of stuff I find to routinely be useful in Node.js
This is a module intended for my own personal use which contains stuff which I believe the Node.js standard library
should have, but doesn't.
It will follow semver, but don't expect me to pay any attention to feature requests (bug reports are welcome though).
As I wrote above, this is really only intended for my own personal use (as with everything in the @doctormckay npm
namespace).
``js`
const {Arrays} = require('@doctormckay/stdlib');
import {unique} from '@doctormckay/stdlib/arrays';
- The array to get unique elements from
- strict - Optional. Pass true to use strict comparisons, or false to use weak comparisons. Performance will increase dramatically when using weak comparisons on large arrays. Default false.Returns an array containing only the unique elements from the input array, in the order they first appeared.
Concurrency
Semaphore
`js
const {Concurrency} = require('@doctormckay/stdlib');
import {Semaphore} from '@doctormckay/stdlib/concurrency';
let sem = new Concurrency.Semaphore();
`A semaphore for ensuring only one (or some number) concurrent asynchronous task runs at once.
$3
- - The maximum number of locks the semaphore will allow at one time. Optional, default 1Creates a new Semaphore with some concurrency limit.
$3
- callback - A function to be called when waiting is over
- release - A function you need to call once you're done to release the semaphoreWaits for the semaphore to be free. Once free, the function provided will be called. If the semaphore is already free,
the callback will be invoked immediately.
Once you're done processing and are ready to release the semaphore, call
release().$3
Returns a promise that is resolved when the semaphore is free. The promise resolves with a function
release, which you
must call once you're done processing and are ready to release the semaphore.`js
import {Semaphore} from '@doctormckay/stdlib/concurrency';
let sem = new Semaphore();
let release = await sem.waitAsync();
// do something
release();
`$3
Returns
if the semaphore is currently free, or false if not. A semaphore is free if a call to wait() would
result in the callback being immediately invoked.Data Structures
AsyncQueue
`js
const {DataStructures} = require('@doctormckay/stdlib');
import {AsyncQueue} from '@doctormckay/stdlib/data_structures';
let queue = new DataStructures.AsyncQueue(processItemSomehow, 2);
`A Queue that automatically pops the first element from the array and runs the async
on it, up to your set
concurrency limit. Very very similar to the async module's Queue.$3
- worker - A function that will be invoked every time an item is popped from the queue. This function should take these arguments:
- item - The item that you pushed into the queue
- callback - A function you should call once processing is finished for the item. The first argument to this callback should be an Error if the processing failed, or null if it succeeded. Any remaining arguments are passed as-is to the callback passed in the push method.$3
Pauses execution. While paused, no new items will be dequeued and passed to a worker, but any workers currently processing
will be allowed to finish.
$3
Resumes execution after you paused it. This will begin handing tasks off to workers again.
$3
Removes the
drain and empty callbacks and empties the queue. Any workers that are already working will be allowed to
finish. After you kill an AsyncQueue, you cannot use it anymore. Any further attempts to push items into the AsyncQueue
will throw an Error.$3
- item - The item to push to the back of the queue
- callback - An optional callback to be invoked once processing of this item is complete. The arguments to the callback will be the same as what the worker called back with.Adds a new item to the queue and if you haven't already reached your concurrency limit, immediately hands it off to a
worker.
$3
A property indicating your concurrency limit. You can assign to this to change the concurrency limit, but it will only
take effect the next time you push an item into the queue, or the next time a worker finishes.
$3
A property containing the worker function that's being used to process items in the queue. You may change it directly if
needed.
$3
A read-only property indicating how many workers are currently running.
$3
A read-only boolean property indicating if the queue is currently paused.
$3
A read-only property indicating how many items are remaining in the queue, waiting to be assigned to a worker.
$3
A property you can assign a function to, which will be called whenever the queue is empty and the last worker finishes.
$3
A property you can assign a function to, which will be called whenever the last item in the queue is handed off to a worker.
$3
A property you can assign a function to, which will be called whenever a worker finishes with an error.
The first argument to the function is the error, and the second is the item that caused it.
LeastUsedCache
`js
const {DataStructures} = require('@doctormckay/stdlib');
let cache = new DataStructures.LeastUsedCache(100, 30000);
`$3
- - The maximum number of items the LeastUsedCache will store before it starts pruning old stuff
- gcInterval - The minimum number of milliseconds between garbage collection attempts$3
- key - A string key
- val - A value, of any typeAdd a new entry to the cache.
$3
- key - A string keyRetrieve a value from the cache. Returns
null if the key doesn't exist.$3
- key - A string keyDelete a value from the cache.
$3
Returns an array containing all the keys in the cache.
$3
Checks if garbage collection is necessary at this point in time, and if it is, does it.
$3
Manually collects garbage immediately, without waiting for the proper timeout.
TTLCache
`js
const {DataStructures} = require('@doctormckay/stdlib');
let cache = new DataStructures.TTLCache(10000);
`$3
- - The number of milliseconds after which an item will be removed from the cache.$3
- key - A string key
- val - A value, of any type
- ttlMilliseconds - Optional. Override the default TTL for this item. If omitted, the default TTL will be used.Add a new entry to the cache.
$3
- key - A string keyRetrieve a value from the cache. Returns
null if the key doesn't exist.$3
- key - A string keyDelete a value from the cache.
$3
Returns an array containing all the keys in the cache.
$3
Clears the entire cache.
Queue
`js
const {DataStructures} = require('@doctormckay/stdlib');
let queue = new DataStructures.Queue();
`Just a basic queue, implemented as a doubly-linked list.
$3
$3
- - The item to push into the back of the queuePushes an item into the back of the queue. Returns the queue's new length. Alias:
enqueue(item)$3
Removes the first item from the queue and returns it. Returns
if the queue is empty. Alias: dequeue()$3
Removes and discards every item in the queue.
$3
A property indicating how many items are in the queue.
Stack
js
const {DataStructures} = require('@doctormckay/stdlib');
let stack = new DataStructures.Stack();
`Just a basic stack, implemented as a linked list.
$3
$3
- - The item to push onto the top of the stackPushes an item onto the top of the stack. Returns the stack's new length.
$3
Removes the top item from the stack and returns it. Returns
null if the stack is empty.$3
Removes and discards every item in the stack.
$3
A property indicating how many items are on the stack.
Hashing
`js
const {Hashing} = require('@doctormckay/stdlib');
`$3
- - Either a Buffer or a string (if a string, will be interpreted as UTF-8)
- outputForm - A string indicating what form should be returned; one of the Buffer encodings, or alternatively buffer to just return a Buffer. Default hex.Return the MD5 hash of the input.
$3
- input - Either a Buffer or a string (if a string, will be interpreted as UTF-8)
- outputForm - A string indicating what form should be returned; one of the Buffer encodings, or alternatively buffer to just return a Buffer. Default hex.Return the SHA-1 hash of the input.
$3
- input - Either a Buffer or a string (if a string, will be interpreted as UTF-8)
- outputForm - A string indicating what form should be returned; one of the Buffer encodings, or alternatively buffer to just return a Buffer. Default hex.Return the SHA-256 hash of the input.
$3
- input - Either a Buffer or a string (if a string, will be interpreted as UTF-8)
- outputForm - A string indicating what form should be returned; one of the Buffer encodings, or alternatively buffer to just return a Buffer or number to return an unsigned 32-bit integer. Default number.Return the CRC32 hash of the input.
HTTP
`js
const {HTTP} = require('@doctormckay/stdlib');
import {getProxyAgent, HttpClient} from '@doctormckay/stdlib/http';
`$3
- - true if this agent will be used for secure (HTTPS) requests, or false if not
- proxyUrl - The URL to your proxy, or something falsy to just get false returned (indicating no agent)
- proxyTimeout - The timeout for connecting to the proxy in milliseconds; default 5000 (5 seconds)
Gets an (HTTP || HTTPS).Agent that can be used to make requests through an HTTP/HTTPS proxy.`js
const StdLib = require('@doctormckay/stdlib');
const HTTPS = require('https');HTTPS.get({
host: 'icanhazip.com',
port: 443,
agent: StdLib.HTTP.getProxyAgent(true, "http://user:pass@1.2.3.4:12345", 10000)
}, (res) => {
if (res.statusCode != 200) {
console.log("HTTP error: " + res.statusCode);
}
res.on('data', (chunk) => {
console.log(chunk.toString('utf8'));
});
}).on('error', (err) => {
console.log(err);
});
`$3
js
import {HttpClient, HttpClientOptions, HttpRequestOptions, HttpResponse} from '@doctormckay/stdlib/http';let client = new HttpClient({
defaultHeaders: {'user-agent': 'my super cool app'},
cookieJar: true
});
let response = await client.request({
method: 'GET',
url: 'https://tools.learningcontainer.com/sample-json.json'
});
console.log(response.statusCode);
console.log(response.jsonBody);
`
IPv4
js
const {Ipv4} = require('@doctormckay/stdlib');
`$3
- - An integer-format Ipv4 addressReturns a dotted-decimal string representation of the input IP address.
$3
- ipString - A dotted-decimal string format Ipv4 addressReturns a 32-bit unsigned integer representation of the input IP address.
Objects
`js
const {Objects} = require('@doctormckay/stdlib');
`$3
- - Some value to clone (may be of any type)Clones a value, and all its sub-objects.
$3
- obj1 - The first thing to compare
- obj2 - The second thing to compare
- strict - Optional. Pass true to use strict equality checks (===). Default false.Checks whether two values and all their sub-objects are equal, and returns
true or false.Two objects are considered to be equal if they have all the same properties and each identical property has the same value.
The order of properties is not considered, except in arrays.
OS
`js
const {OS} = require('@doctormckay/stdlib');
`$3
- - An object
- appName - A string containing your app's name
- appAuthor - A string containing the name of the author/vendor of your app (only used on Windows)
- useRoaming - Optional. true to use roaming appdata on Windows (default false)Returns a string containing the path to a directory you can use to store app-specific data.
Parsing
`js
const {Parsing} = require('@doctormckay/stdlib');
`$3
- - An input stringParses a set of ordered, unnamed command-line arguments similar to how the Source engine does it. For example, instead
of doing it like
--arg=foo -pbar it parses like one two "three three" four.To be a little more specific, arguments are split on spaces but spaces inside quotes are interpreted as part of the value.
Quotes, spaces, and backslashes can be escaped with backslashes. Double spaces between arguments are collapsed, but
you can preserve empty values with quotes. Some examples:
`
one two three => ["one", "two", "three"]
one two "three three" four => ["one", "two", "three three", "four"]
one two three four => ["one", "two", "three", "four"]
one two "" four five => ["one", "two", "", "four", "five"]
one two\ two three four => ["one", "two two", "three", "four"]
Promises
js
const {Promises} = require('@doctormckay/stdlib');
`$3
- - Timeout in milliseconds. If this value is <= 0, then the timeout functionality is disabled.
- executor - The executor function for the promise with signature (resolve, reject)Creates and returns a promise that automatically rejects after the specified timeout if the promise has not yet been settled.
If a promise times out, then it will be rejected with an
object with message Request timed out.$3
- callbackArgs - An array of strings indicating the names and order of arguments in the callback. null to just pass the entire promise result object
- callback - A callback function, or falsy if none
- isOptional - Indicates whether the callback is optional. If it isn't, then rejected promises will crash the app (eventually). Default false.
- executor - The executor function for the promise with signature (resolve, reject)Creates and returns a promise that can also be used to fire a callback, for supporting both promises and callbacks.
$3
- - Timeout in milliseconds. If this value is <= 0, then the timeout functionality is disabled.
- callbackArgs - An array of strings indicating the names and order of arguments in the callback. null to just pass the entire promise result object
- callback - A callback function, or falsy if none
- isOptional - Indicates whether the callback is optional. If it isn't, then rejected promises will crash the app (eventually). Default false.
- executor - The executor function for the promise with signature (resolve, reject)Creates and returns a promise that has properties of both
and callbackPromise.$3
- sleepMilliseconds - The time, in milliseconds, after which the Promise should be resolvedReturns a Promise that is resolved after the specified delay.
Rendering
`js
const {Rendering} = require('@doctormckay/stdlib');
`$3
- - The current value of the progress bar, as a number
- maxValue - The maximum value of the progress bar, as a number
- barWidth - The width of the bar in characters, including the containing square brackets
- showPercentage - Pass true to display the bar's current percentage in the center of it (default false)Returns a string containing an ASCII progress bar. For best results when using
showPercentage, barWidth should be
an odd number.Time
`js
const {Time} = require('@doctormckay/stdlib');
`$3
Returns a string containing the current 24-hour time in your local timezone in the format
.Units
`js
const {Units} = require('@doctormckay/stdlib');
`$3
- - Number of bytes
- binary - Pass true if you want to use the base-1024 system (i.e. MiB instead of MB). Default false`Returns a human-readable string representation of the input byte count, e.g. 12.5 MB.