Razorux-js-utils NPM

razorUX JS Utils

My collection of custom Node.js utilities. Small useful, and constantly improved!

Working with environment variables
Read/write files: plaintext, CSV, and JSON
Normalize tokens
Dollar /cents conversion
Functional pipe methods
Object cloning
Iteration syntax sugar
Sleep
Enable / disable console
Base64 encode/decode
Insecure random numbers
Retry network errors
Type Assertions
Slack messaging
JSON caching with Memcachier

Installation

npm install razorux-js-utils

Included functions

loadEnvVars(filePath);
validateEnvVars([ ENV_VAR ]);

readCsvFile(path);
writeCsvFile(data, path);

readTextFile(path);

ensureDirExists(path);

readJsonFile(path);
writeJsonFile(data, path);

normalizeToken(string);

dollarsToCents(number);
centsToDollars(number);

invokeMethod(Function);


pipe([ function() {}, function() {} ]);
map([], function() {});
reduce([], function() {});
objectToEntries({});
entriesToObject([key, value]);

clone(Object)

asyncMap(Array, Function);
asyncForEach(Array, Function);

sendSlackNotification,
getCloudWatchLogDeeplink()
sendErrorNotification,

simpleHash(Any)

sleep(number) // (milliseconds)

parseBoolean(String);

retryable({fn, retryCount = 3, timeout = 300, addRandomDelay = true});

validateJson(json, requiredPaths);

createErrorType(name, suppressErrorNotification);

enableConsoleLogging();
disableConsoleLogging();

base64ToString,
stringToBase64

Modules

Insecure Random

const n = randomNumberBetween(0, 42);
# => a random number within range, **inclusive**

Base64

A pair of functions to encode/decode base64 strings. Works exactly as you'd expect.

const b64 = stringToBase64("Just you wait, Henry Higgins, just you wait...")
// => "SnVzdCB5b3Ugd2FpdCwgSGVucnkgSGlnZ2lucywganVzdCB5b3Ugd2FpdC4uLg=="

base64ToString(b64)
// # => "Just you wait, Henry Higgins, just you wait..."

Retry

This package includes a powerful retry function for retrying pretty much any function, including async promises.

Max retry count
Linear retry delay
Global Timeout
Truncated exponential backoff
Min and max backoff values
Jitter
Jitter min and max
Return true to break out of retry
[] Error matchers

const {	
  retry
} = require('main');

function myAsyncFunction() { ... }

// Simple use case
await retry(myAsyncFunction);

const ONE_SECOND = 1000;
const ONE_MINUTE = 1000 * 60;

// Retry all errors with backoff + jitter
await retry(myAsyncFunction, {
	backoff: true,
	jitter: true,
	minRetryDelay: ONE_SECOND,
	maxRetryDelay: 3 * ONE_MINUTE, // No retry delay of longer than 3m
	timeout: 10 * ONE_MINUTE, // Give up after 10 minutes
});


// Full options
await retry(
myAsyncFunction,

{ 

// A function to retry
// Every time an exception is thrown, it will be
// retried, subject to the following parameters

onError = ()=>{
	// Optional. 
	// Will be passed every exception captured from `fn`
	
	// You can return `true` to break out of the retry block early
	// If you do so, `retry` will throw the error instead of retrying
},


maxRetryCount: Number.MAX_SAFE_INTEGER
// Amount of times to retry before giving up
// If, the amount of retries are exhausted, will throw a RetryLimitReachedError,
// with the original error wrapped inside it

timeout: 1000,
// Amount of milliseconds to wait between giving up.
// If the timeout expires will throw a RetryTimeoutError, with the original error wrapped inside it.
// Example: "Retry this network request until 5 minutes have passed"

// Note:
// If maxRetryCount and timeout are both set, the operation will abort
// with whichever one occurs sooner

retryDelayMs: 50,
// Amount of milliseconds to wait between retries.
// If `backoff` is true, this will be ignored

backoff: false,
// Wait exponentially more between retries
// i.e. 1000ms, 2000ms, 4000ms, 8000ms, etc.
// Perfect for rate-limited APIs

factor: 2,
// Exponent to use for backoff

minRetryDelay: 0,
// The initial delay value in milliseconds

maxRetryDelay: 1000 * 60 * 2, // Two minutes
// The maximum delay value in milliseconds.
// You should always set this to prevent the retry delay from becoming really huge


jitter: false,
// Add a randomized amount to the delay
// This is important to avoid deadlock if many instances of your program will be trying to access the same resource at once

minJitterMs:  0,
maxJitterMs:  50,
// Min and max jitter values
// Max doesn't need to be very large, just enough to break deadlock

debugLogging: false 
// Print comprehensive internal logs to the console
// Great for debugging
})

Caching with Memcachier

Dead-easy temporary JSON storage in Memcache.

You'll need to sign up for a free Memcachier account here.

First, make sure you've set the following environment variables:

MEMCACHIER_SERVER,
MEMCACHIER_USERNAME
MEMCACHIER_PASSWORD

# Optional. Expire cached objects after this timeout.
# Default is 12 hours
CACHE_EXPIRATION_TIMEOUT_SECONDS = 60 * 60; // 1 hour

# Optional. Shows debug logging.
# Defaults to false
MEMCACHE_LOGGING_ENABLED=true

Usage:

// JSON to store in the cache
const data = { text: "Hello World!", passenger: "Mr. Frumble" }
const key = "top_secret_key"

const cache = createCacheClient();

const storageResponse = await cache.persist(key, data);
// => true

const retrieveResponse = await cache.retrieve(key);	
// => { text: 'Hello World!', passenger: 'Mr. Frumble' }

JSON is automatically serialized and deserialized

Type Assertions

A collection of type assertions, if you need them.

assert* functions throw an error if the value doesn't match. A match returns nothing. (The default error is TypeError. A custom error class can be used instead. )
is* functions return true or false.

You can optionally customize the name of the error in the error message, and the error message class.

const arg = 42;

// Basic usage
assertTypeString(arg);
// => throws TypeError "Expected Argument to be a String. (Got: 42. typeof: number)"


// Customized errors
assertTypeString(arg, 'Input String', MyInputStringError);
// => throws MyInputStringError "Expected Input String to be a String. (Got: 42. typeof: number)"

Included assertions:

assertDefined(arg, argName, customErrorClass);
assertTruthy(arg, argName, customErrorClass);

assertTypeString(arg, argName, customErrorClass);
assertTypeNumber(arg, argName, customErrorClass);
assertTypeObject(arg, argName, customErrorClass);
assertTypeArray(arg, argName, customErrorClass);

isTypeof(value, typeString) //  i.e. isTypeof(42, 'number') -> true
isObject(arg);
isArray(arg);
isNull(arg);
isUndefined(arg)