lib

Type Definitions

ParamsOptions

Description:

• An object to be used with toParams for validation

Properties:

Type:

• object

Methods

(static) __()

Description:

• Simple i18n translation method compatible with other popular modules, supports the following usage:

Example

lib.__(name)
lib.__(fmt, arg,...)
lib.__({ phrase: "", locale: "" }, arg...

(static) base64ToJson()

Description:

• Parse base64 JSON into JavaScript object, in some cases this can be just a number then it is passed as it is, if secret is given verify that data is not chnaged and was signed with the same secret

(static) call(obj, methodopt, …argsopt)

Description:

• Call a function safely with context:

Parameters:

Example

lib.call(func,..)
lib.call(context, func, ...)
lib.call(context, method, ...)

(static) clock()

Description:

• Returns current time in microseconds since January 1, 1970, UTC

(static) configParse(data, optionsopt) → {Array.<string>}

Description:

• Parse data as config format name=value per line

  Include supports:

  • The format is: $include filename the contents of the given file will be included in place and parsed. File name may contain placeholders formatted as @name@ where name can refer to any property inside the options or inside the modules as @module.name@

  Supports sections:

  • The format is: [name=value,...] or [name!=value,...] where name is a property name with optional value(s).
  • if the value is empty then it just checks if the property is empty.
  • != denotes negative condition, i.e. not matching or NOT empty
  • section names may refer deep into objects like aws.region or instance.tag, all modules will be checked inside options.modules object only, all other names are checked in the top level options.

  Sections work like a filter, only if a property matches it is used otherwise skipped completely, it uses lib.isTrue for matching so checking an item in an array will work as well. The [global] section can appear anytime to return to global mode

Parameters:

Returns:

(static) daysInMonth()

Description:

• Return the number of days in the given month of the specified year.

(static) decodeURIComponent()

Description:

• No-exception version of the global function, on error return empty string

(static) deferCallback(parent, msg, callback, timeoutopt) → {object}

Description:

• Register the callback to be run later for the given message, the message may have the __deferId property which will be used for keeping track of the responses or it will be generated. A timeout is created for this message, if runCallback for this message will not be called in time the timeout handler will call the callback anyway with the original message.

Parameters:

Returns:

(static) deferInterval()

Description:

• Assign or clear an interval timer by name, keep the reference in the given parent object

(static) deferShutdown()

Description:

• Clear all pending timers

(static) encodeURIComponent()

Description:

• Encode with additional symbols, convert these into percent encoded:

       ! -> %21, * -> %2A, ' -> %27, ( -> %28, ) -> %29
  

(static) entityToText()

Description:

• Convert html entities into their original symbols

(static) escapeUnicode()

Description:

• Convert all Unicode binary symbols into Javascript text representation

(static) fromBase32(str, optionsopt)

Description:

• Convert a string in base32 into a Buffer

Parameters:

(static) fromBase62()

Description:

• Convert base62 number as a string into base10 number

(static) fromBase64url()

Description:

• Decode base64url into a string

(static) getArg(name, dfltopt) → {string}

Description:

• Return commandline argument value by name

Parameters:

Returns:

(static) getArgInt(name, dfltopt) → {int}

Description:

• Return commandline argument value as a number

Parameters:

Returns:

(static) getHashid(optionsopt) → {string}

Description:

• Return cached Hashids instance for the given configuration, see https://github.com/niieani/hashids.js for docs, NOTE: only .encode and .decode methods are implemented. Properties:

Parameters:

Returns:

(static) getWorkers(filteropt, filteropt)

Description:

• Return a worker by id or list of workers, useful only in primary process only, always returns an object.

Parameters:

(static) hash(data, algorithmopt, encodeopt) → {string}

Description:

• Hash wrapper without exceptions for node crypto createHash

Parameters:

Returns:

(static) isArg(name) → {boolean}

Description:

• Returns true of given arg(s) are present in the command line, name can be a string or an array of strings.

Parameters:

Returns:

(static) isDST()

Description:

• Returns true if the given date is in DST timezone

(static) isTimeRange()

Description:

• Returns 0 if the current time is not within specified valid time range or it is invalid. Only continious time rang eis support, it does not handle over the midninght ranges, i.e. time1 is always must be greater than time2.

  options.tz to specify timezone, no timezone means current timezone. options.date if given must be a list of dates in the format: YYY-MM-DD,...

(static) jsonFormat()

Description:

• Nicely format an object with indentations, optional indentlevel can be used to control until which level deep to use newlines for objects. Options:

  • preset - predefined set of options, compact prints yaml-like text version, if a list all presets are combined
  • indent - initial indent, empty default
  • ilevel - level to start to use spaces for indentation, 0 default
  • ignore - regexp with properties to ingore
  • skipnull - do not print null/undefined/""
  • skipempty - skip all empty object accorsding to lib.isEmpty
  • map - an object to map property names
  • replace - an object for string values replacement: { ORIG: REPL... }
  • preprocess - a function(name, val, options) to run before prints, return undefined to skip
  • sbracket1, sbracket2 - open/close brackets for arrays, [ ]
  • cbracket1, cbracket2 - open close brackets for obejcts, { }
  • nl1, nl2 - newline chars before and after a single property
  • quote1, quote2 - quotes for property names
  • squote1, squote2 - quotes for string values
  • comma - comma separator between items
  • sep - separator between array items, comma by default
  • space - symbol for indentation
  • nspace - how many spaces to use for indentation, 4
  • prefix - prefix for array items, each item on new line, requires nl1
  • wrap - wrap long strings at this length
  • over - number greater than 1 to allow extra characters over wrap length
  • delim - characters that trigger wrapping

(static) jsonFormatPreset()

Description:

• Register or update a jsonFormat preset

(static) jsonParse(data, optionsopt) → {object|array}

Description:

• Silent JSON parse, returns null on error, no exceptions raised.

Parameters:

Returns:

(static) jsonToBase64()

Description:

• Stringify JSON into base64 string, if secret is given, sign the data with it

(static) killWorkers(filter)

Description:

• Kill all workers

Parameters:

(static) loadLocale(file, callbackopt)

Description:

• Load a file with locale translations into memory

Parameters:

(static) localEpoch()

Description:

• Returns current time in seconds (s), microseconds (m), time struct (tm) or milliseconds since the local lib._epoch (2025-11-15 UTC)

(static) log(…argsopt)

Description:

• Print all arguments into the console, for debugging purposes, if the first arg is an error only print the error

Parameters:

(static) murmurHash3(key) → {number}

Description:

• 32-bit MurmurHash3 implemented by bryc (github.com/bryc)

Parameters:

Returns:

(static) newError(message, statusopt, codeopt)

Description:

• Return a new Error object, message can be a string or an object with message, code, status properties. The default error status is 400 if not specified.

Parameters:

(static) notifyWorkers(filter)

Description:

• Send a message to all workers

Parameters:

(static) now()

Description:

• Return number of seconds for current time

(static) objClone(obj, …argsopt) → {object}

Description:

• A shallow copy of an object, it is deeper than Object.assign for arrays, objects, sets and maps, these created new but all other types are just references as in Object.assign

Parameters:

Returns:

Example

const a = { 1: 2, a: [1, 2] }
   const b = lib.objClone(a, { "3": 3, "4": 4 })
   b.a.push(3)
   a.a.length != b.length

(static) objSize(optionsopt) → {int}

Description:

• Calculate the size of the whole object, this is not exact JSON size, for speed it summarizes approximate size of each property recursively

Parameters:

Returns:

(static) parseCookies(header) → {object}

Description:

• Parse a cookie header.

  Parse the given cookie header string into an object The object has the various cookies as keys(names) => values Borrowed from https://github.com/jshttp/cookie

Parameters:

Returns:

(static) parseTime()

Description:

• Parses a string with time and return an array [hour, min], accepts 12 and 24hrs formats, a single hour is accepted as well, returns undefined if cannot parse

(static) runCallback()

Description:

• Run delayed callback for the message previously registered with the deferCallback method. The message must have __deferId property which is used to find the corresponding callback, if the msg is a JSON string it will be converted into the object.

  Same parent object must be used for deferCallback and this method.

(static) shuffle(list) → {Array.<any>}

Description:

• Randomize a list items in place

Parameters:

Returns:

(static) sleep(delay) → {Promise}

Description:

• Async sleep version

Parameters:

Returns:

(static) slug(optionsopt) → {string}

Description:

• Generate a 22 chars slug from an UUID

Parameters:

Returns:

(static) sortByVersion()

Description:

• Sort a list be version in descending order, an item can be a string or an object with a property to sort by, in such case name must be specified which property to use for sorting. The name format is assumed to be: XXXXX-N.N.N

(static) strftimeMap()

Description:

• Format date object according to Unix stftime function

(static) stringify()

Description:

• JSON stringify without exceptions, on error just returns an empty string and logs the error

(static) suuid(prefixopt, optionsopt) → {string}

Description:

• Short unique id within a microsecond

Parameters:

Returns:

(static) textToEntity()

Description:

• Convert all special symbols into html entities

(static) textToXml()

Description:

• Convert all special symbols into xml entities

(static) toAge()

Description:

• Given time in msecs, return how long ago it happened

  • short - if true use first letters only
  • round - a number, 1 return only 1st part, 2 - 1st and 2nd parts

(static) toBase32(bug, optionsopt) → {string}

Description:

• Convert a Buffer into base32 string

Parameters:

Returns:

(static) toBase62()

Description:

• Return base62 representation for a number

(static) toBase64url()

Description:

• Encode a string into Base64 url safe version

(static) toBool(val, dfltopt) → {boolean}

Description:

• Return true if value represents true condition, i.e. non empty value

Parameters:

Returns:

(static) toCamel(name, charsopt) → {string}

Description:

• Convert into camelized form

Parameters:

Returns:

(static) toClamp(num, min, max) → {number}

Description:

• Return a number clamped between the range

Parameters:

Returns:

(static) toDate(val, dfltopt, invalidopt) → {Date}

Description:

• Return Date object for given text or numeric date representation, for invalid date returns 1969 unless invalid parameter is given, in this case invalid date returned as null. If dflt is NaN, null or 0 returns null as well.

Parameters:

Returns:

(static) toDigits(str) → {string}

Description:

• Strip all non-digit characters from a string

Parameters:

Returns:

(static) toDuration()

Description:

• Return duration in human format, mtime is msecs

  • short - if true use first letters only
  • round - a number, 1 return only 1st part, 2 - 1st and 2nd parts

(static) toEmail()

Description:

• Return an email address if valid, options.parse makes it extract the email from name <email> format

(static) toFlags()

Description:

• Flags command utility, the commands are:

  • add - adds the name flags to the list if does not exists, returns the same array
  • update - adds new flags and removes flags that starts with - , returns the same array
  • concat - same as add but always returns a new list
  • del - removes the flags name, returns the same array
  • present - returns only flags that present in the list name
  • absent - returns only flags that are not present in the list name

(static) toFormat()

Description:

• Convert a list of records into the specified format, supported formats are: xml, csv, json, jsontext.

  • For csv the default separator is comma but can be specified with options.separator. To produce columns header specify options.header.
  • For json format puts each record as a separate JSON object on each line, so to read it back it will require to read every line and parse it and add to the list.
  • For xml format the name of the row tag is <row> but can be specified with options.tag.

  All formats support the property options.allow which is a list of property names that are allowed only in the output for each record, non-existent properties will be replaced by empty strings.

  The mapping object property can redefine different tag/header names to be put into the file instead of the exact column names from the records.

(static) toMtime(val, dfltopt) → {number}

Description:

• Return milliseconds from the date or date string, only number as dflt is supported, for invalid dates returns 0

Parameters:

Returns:

(static) toNumber(val, optionsopt) → {number}

Description:

• Safe convertion to a number, no expections, uses 0 instead of NaN, handle booleans, if float specified, returns as float.

Parameters:

Returns:

Example

lib.toNumber("123")
lib.toNumber("1.23", { float: 1, dflt: 0, min: 0, max: 2 })

(static) toParams(query, schema, optionsopt) → {string|object}

Description:

• Process incoming query and convert parameters according to the type definition, the schema contains the definition of the paramaters against which to validate incoming data. It is an object with property names and definitoons that at least must specify the type, all other options are type specific.

  Returns a string message on error or an object

Parameters:

Returns:

Example

var query = lib.toParams(req.query, {
       id: { type: "int" },
       count: { type: "int", min: 1, max: 10, dflt: 5 },
       age: { type: "int", minnum: 10, maxnum: 99 },
       name: { type: "string", max: 32, trunc: 1 },
       pair: { type: "map", maptype: "int" },
       code: { type: "string", regexp: /^[a-z]-[0-9]+$/, errmsg: "Valid code is required" },
       start: { type: "token", required: 1 },
       email: { type: "list", datatype: "email", novalue: ["a@a"] },
       email1: { type: "email", required: { email: null } },
       data: { type: "json", datatype: "obj" },
       mtime: { type: "mtime", name: "timestamp" },
       date: { type: "date", mindate: new Date(2000,1,1) },
       flag: { type: "bool", novalue: false },
       descr: { novalue: { name: "name", value: "test" }, replace: { "<": "!" } },
       internal: { ignore: 1 },
       tm: { type: "timestamp", optional: 1 },
       ready: { value: "ready" },
       state: { values: [ "ok","bad","good" ] },
       status: { value: [ "ok","done" ] },
       obj: { type: "obj", params: { id: { type: "int" }, name: {} } },
       arr: { type: "array", params: { id: { type: "int" }, name: {} } },
       ssn: { type: "string", regexp: /^[0-9]{3}-[0-9]{3}-[0-9]{4}$/, errmsg: "Valid SSN is required" },
       phone: { type: "list", datatype: "number" },
       }, {
       defaults: {
           start: { secret: req.user.secret },
           name: { dflt: "test" },
           count: { max: 100 },
           email: { ignore: req.user.roles != "admin" },
           "*.string": { max: 255 },
           '*': { maxlist: 255 },
       });

 if (typeof query == "string) return api.sendReply(res, 400, query);

(static) toPrice()

Description:

• Return a test representation of a number according to the money formatting rules, default is en-US, options may include: currency(USD), display(symbol), sign(standard), min(2), max(3)

(static) toRFC3339()

Description:

• Return RFC3339 formatted timestamp for a date or current time

(static) toRegexp()

Description:

• Safely create a regexp object, if invalid returns undefined, the options can be a string with srandard RegExp flags or an object with the following properties:

  • ingoreCase - similar to i
  • globalMatch - similar to m
  • multiLine - similar to m
  • unicode - similar to u
  • sticky - similar to y
  • escape - escape all special symbols or symbol e

(static) toRegexpMap()

Description:

• Add a regexp to the list of regexp objects, this is used in the config type regexpmap.

(static) toRegexpObj()

Description:

• Add a regexp to the object that consist of list of patterns and compiled regexp, this is used in the config type regexpobj

(static) toSize()

Description:

• Return size human readable format

(static) toString(val) → {string}

Description:

• Convert a value to a string, use default Javascript toString convertion of any object

Parameters:

Returns:

(static) toTemplate()

Description:

• Given a template with @..@ placeholders, replace each placeholder with the value from the obj. The obj can be an object or an array of objects in which case all objects will be checked for the value until non empty.

  To use @ in the template specify it as @@

  Placeholders can have default or/and encoding

  • default only: @name|dflt@
  • encoding with default: @name|dflt|encoding@
  • encoding no default: @name||encoding@

  Encoding options:

  • url, base64, entity, strftime, mtime
  • d-url, d-base64, d-entity - decode value instead of encode it

  The options if given may provide the following:

  • allow - placeholders with a name present in this list will be replaced, all other will be replaced with empty string
  • skip - placeholders with a name present in this list will be ignored, the placeholer will be kept
  • only - placeholders with a name present in this list will be replaced only, all other will be ignored and kept as placeholders
  • encoding - can be url or base64, the replaced values will be encoded accordingly
  • separator1 - left side of the placehoder, default is @
  • separator2 - right side of the placeholder, default is @

  Default placeholders:

  • @exit@ - stop processing and return the template ignoring the rest
  • @RAND@ - produce a random number using Math.random
  • @n@ - produce a line break, newline
  • @p@ - produce 2 newlines

Example

lib.toTemplate("http://www.site.com/@code@/@id@", { id: 123, code: "YYY" }, { encoding: "url" })
lib.toTemplate("Hello @name|friend@!", {})

(static) toTitle(name, minlenopt) → {string}

Description:

• Convert text into capitalized words, if it is less or equal than minlen leave it as is

Parameters:

Returns:

(static) toUncamel(str, sepopt) → {string}

Description:

• Convert Camel names into names separated by the given separator or dash(-) if not.

Parameters:

Returns:

(static) toUrl()

Description:

• Return a well formatted and validated url or empty string

(static) toValue()

Description:

• Convert a value to the proper type, default is to return a string or convert the value to a string if no type is specified, special case if the type is "" or null return the value as is without any conversion

(static) toVersion(str) → {number}

Description:

• Returns a floating number from the version string, it assumes common semver format as major.minor.patch, all non-digits will be removed, underscores will be treated as dots. Returns a floating number which can be used in comparing versions.

Parameters:

Returns:

Example

> lib.toVersion("1.0.3")
     1.000003
     > lib.toVersion("1.0.3.4")
     1.000003004
     > lib.toVersion("1.0.3.4") > lib.toVersion("1.0.3")
     true
     > lib.toVersion("1.0.3.4") > lib.toVersion("1.0.0")
     true
     > lib.toVersion("1.0.3.4") > lib.toVersion("1.1.0")
     false

(static) traceError(err)

Description:

• Returns the error stack or the error itself, to be used in error messages

Parameters:

(static) tryCall(callback, …argsopt) → {any}

Description:

• Run a callback if a valid function, all arguments after the callback will be passed as is, report a warning if callback is not a function but not empty

Parameters:

Returns:

(static) tryCatch(callback, …argsopt)

Description:

• Run a callback inside try..catch block, all arguments after the callback will be passed as is, in case of error all arguments will be printed in the log. If no callback passed do nothing.

Parameters:

(static) tryLater(callback, timeout, …argsopt)

Description:

• Run a callback after timeout, returns a function so it can be used instead of actual callback, report a warning if callback is not a function but not empty

Parameters:

(static) tzName()

Description:

• Return a timezone human name if matched (EST, PDT...), tz must be in GMT-NNNN format

(static) unescape()

Description:

• Convert escaped characters into native symbols

(static) unicode2Ascii()

Description:

• Replace Unicode symbols with ASCII equivalents, types is a string with list of types of characters to replace, default is: opqs, for quotes,other,punctuations,spaces

(static) uuid(prefixopt) → {string}

Description:

• Unique Id (UUID v4) without any special characters and in lower case

Parameters:

Returns:

(static) weekDate()

Description:

• Return first day of the week by ISO week number

(static) weekOfYear()

Description:

• Return an ISO week number for given date, from https://www.epochconverter.com/weeknumbers

(static) xmlParse()

Description:

• Same arguments as for module:lib.jsonParse

(inner) onDeferCallback()

Description:

• To be called on timeout or when explicitely called by the runCallback, it is called in the context of the message.