@doctormckay/stdlib
Advanced tools
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).
const {Arrays} = require('@doctormckay/stdlib');
import {unique} from '@doctormckay/stdlib/arrays';
array - The array to get unique elements fromstrict - 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.
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.
concurrency - The maximum number of locks the semaphore will allow at one time. Optional, default 1Creates a new Semaphore with some concurrency limit.
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().
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.
import {Semaphore} from '@doctormckay/stdlib/concurrency';
let sem = new Semaphore();
let release = await sem.waitAsync();
// do something
release();
Returns true 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.
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 worker on it, up to your set
concurrency limit. Very very similar to the async module's Queue.
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 queuecallback - 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.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.
Resumes execution after you paused it. This will begin handing tasks off to workers again.
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.
item - The item to push to the back of the queuecallback - 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.
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.
A property containing the worker function that's being used to process items in the queue. You may change it directly if needed.
A read-only property indicating how many workers are currently running.
A read-only boolean property indicating if the queue is currently paused.
A read-only property indicating how many items are remaining in the queue, waiting to be assigned to a worker.
A property you can assign a function to, which will be called whenever the queue is empty and the last worker finishes.
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.
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.
const {DataStructures} = require('@doctormckay/stdlib');
let cache = new DataStructures.LeastUsedCache(100, 30000);
maxItems - The maximum number of items the LeastUsedCache will store before it starts pruning old stuffgcInterval - The minimum number of milliseconds between garbage collection attemptskey - A string keyval - A value, of any typeAdd a new entry to the cache.
key - A string keyRetrieve a value from the cache. Returns null if the key doesn't exist.
key - A string keyDelete a value from the cache.
Returns an array containing all the keys in the cache.
Checks if garbage collection is necessary at this point in time, and if it is, does it.
Manually collects garbage immediately, without waiting for the proper timeout.
const {DataStructures} = require('@doctormckay/stdlib');
let cache = new DataStructures.TTLCache(10000);
ttlMilliseconds - The number of milliseconds after which an item will be removed from the cache.key - A string keyval - A value, of any typettlMilliseconds - Optional. Override the default TTL for this item. If omitted, the default TTL will be used.Add a new entry to the cache.
key - A string keyRetrieve a value from the cache. Returns null if the key doesn't exist.
key - A string keyDelete a value from the cache.
Returns an array containing all the keys in the cache.
Clears the entire cache.
const {DataStructures} = require('@doctormckay/stdlib');
let queue = new DataStructures.Queue();
Just a basic queue, implemented as a doubly-linked list.
item - 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)
Removes the first item from the queue and returns it. Returns null if the queue is empty. Alias: dequeue()
Removes and discards every item in the queue.
A property indicating how many items are in the queue.
const {DataStructures} = require('@doctormckay/stdlib');
let stack = new DataStructures.Stack();
Just a basic stack, implemented as a linked list.
item - The item to push onto the top of the stackPushes an item onto the top of the stack. Returns the stack's new length.
Removes the top item from the stack and returns it. Returns null if the stack is empty.
Removes and discards every item in the stack.
A property indicating how many items are on the stack.
const {Hashing} = require('@doctormckay/stdlib');
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 MD5 hash of the input.
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.
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.
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.
const {HTTP} = require('@doctormckay/stdlib');
import {getProxyAgent, HttpClient} from '@doctormckay/stdlib/http';
secure - true if this agent will be used for secure (HTTPS) requests, or false if notproxyUrl - 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.
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);
});
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);
const {Ipv4} = require('@doctormckay/stdlib');
ipInt - An integer-format Ipv4 addressReturns a dotted-decimal string representation of the input IP address.
ipString - A dotted-decimal string format Ipv4 addressReturns a 32-bit unsigned integer representation of the input IP address.
const {Objects} = require('@doctormckay/stdlib');
obj - Some value to clone (may be of any type)Clones a value, and all its sub-objects.
obj1 - The first thing to compareobj2 - The second thing to comparestrict - 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.
const {OS} = require('@doctormckay/stdlib');
params - An object
appName - A string containing your app's nameappAuthor - 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.
const {Parsing} = require('@doctormckay/stdlib');
input - 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"]
const {Promises} = require('@doctormckay/stdlib');
timeout - 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 Error object with message Request timed out.
callbackArgs - An array of strings indicating the names and order of arguments in the callback. null to just pass the entire promise result objectcallback - A callback function, or falsy if noneisOptional - 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.
timeout - 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 objectcallback - A callback function, or falsy if noneisOptional - 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 timeoutPromise and callbackPromise.
sleepMilliseconds - The time, in milliseconds, after which the Promise should be resolvedReturns a Promise that is resolved after the specified delay.
const {Rendering} = require('@doctormckay/stdlib');
value - The current value of the progress bar, as a numbermaxValue - The maximum value of the progress bar, as a numberbarWidth - The width of the bar in characters, including the containing square bracketsshowPercentage - 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.
const {Time} = require('@doctormckay/stdlib');
Returns a string containing the current 24-hour time in your local timezone in the format YYYY-MM-DD HH:MM:SS.
const {Units} = require('@doctormckay/stdlib');
bytes - Number of bytesbinary - Pass true if you want to use the base-1024 system (i.e. MiB instead of MB). Default falseReturns a human-readable string representation of the input byte count, e.g. 12.5 MB.
FAQs
A "standard library" of stuff I find to routinely be useful in Node.js
We found that @doctormckay/stdlib demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.