api/utils/common

Module for some common utility functions and references

Source:

Classes

DataTable

Members

(static) base64 :object

Source:

Whole base64 alphabet for fetching splitted documents

Type:
  • object

(static) config :object

Source:

Default countlyConfig object for API server

Type:
  • object

(static) crypto :object

Source:

Reference to crypto module

Type:
  • object

(static) dbEventMap :object

Source:

Mapping some common event property names from longer understandable to shorter representation stored in database

Type:
  • object

(static) dbMap :object

Source:

Mapping some common property names from longer understandable to shorter representation stored in database

Type:
  • object

(static) dbUserMap :object

Source:

Mapping some common user property names from longer understandable to shorter representation stored in database

Type:
  • object

(static) log :module:api/utils/log~Logger

Source:

Logger object for creating module specific logging

Type:
Example
var log = common.log('myplugin:api');
log.i('myPlugin got a request: %j', params.qstring);

(static) moment :object

Source:

Reference to momentjs

Type:
  • object

(static) os_mapping :object

Source:

Operating syste/platform mappings from what can be passed in metrics to shorter representations stored in db as prefix to OS segmented values

Type:
  • object

Methods

(static) adjustTimestampByTimezone(ts, tz) → {number}

Source:

Adjust timestamp with app's timezone for timestamp queries that should equal bucket results

Parameters:
Name Type Description
ts number

miliseconds timestamp

tz string

timezone

Returns:

adjusted timestamp for timezone

Type
number

(static) argon2Hash(str) → {promise}

Source:

Create argon2 hash string

Parameters:
Name Type Description
str string

string to hash

Returns:

hash promise

Type
promise

(static) arrayAddUniq(arr, item)

Source:

Add item or array to existing array only if values are not already in original array

Parameters:
Name Type Description
arr array

original array where to add unique elements

item string | number | array

item to add or array to merge

(static) blockResponses(params)

Source:
Parameters:
Name Type Description
params params

params object

(static) checkDatabaseConfigMatch(apiConfig, frontendConfig) → {boolean}

Source:

Check db host match for both of API and Frontend config

Parameters:
Name Type Description
apiConfig object

mongodb object from API config

frontendConfig object

mongodb object from Frontend config

Returns:

isMatched - is config correct?

Type
boolean

(static) checkPromise(func, count, interval) → {Promise}

Source:

Create promise for function which result should be checked periodically

Parameters:
Name Type Description
func function

function to run when verifying result, should return true if success

count number

how many times to run the func before giving up, if result is always negative

interval number

how often to retest function on negative result in miliseconds

Returns:

promise for checking task

Type
Promise

(static) convertToType(value) → {varies}

Source:

This default Countly behavior of type conversion for storing proeprties accepted through API requests dealing with numbers as strings and too long numbers

Example
common.convertToType(1) //outputs 1
common.convertToType("2") //outputs 2
common.convertToType("test") //outputs "test"
common.convertToType("12345678901234567890") //outputs "12345678901234567890"
Parameters:
Name Type Description
value any

value to convert to usable type

Returns:

converted value

Type
varies

(static) decode_html(string) → {string}

Source:

Decode escaped html

Parameters:
Name Type Description
string string

The string to decode

Returns:

escaped string

Type
string

(static) dot(obj, is, value) → {varies}

Source:

Getter/setter for dot notatons:

Example
common.dot({a: {b: {c: 'string'}}}, 'a.b.c') === 'string'
common.dot({a: {b: {c: 'string'}}}, ['a', 'b', 'c']) === 'string'
common.dot({a: {b: {c: 'string'}}}, 'a.b.c', 5) === 5
common.dot({a: {b: {c: 'string'}}}, 'a.b.c') === 5
Parameters:
Name Type Description
obj object

object to use

is string

path of properties to get

value varies

value to set

Returns:

value at provided path

Type
varies

(static) equal(a, b, checkFromA) → {Boolean}

Source:

Not deep object and primitive type comparison function

Parameters:
Name Type Description
a Any

object to compare

b Any

object to compare

checkFromA Boolean

true if check should be performed agains keys of a, resulting in true even if b has more keys

Returns:

true if objects are equal, false if different types or not equal

Type
Boolean

(static) escape_html(string, more) → {string}

Source:

Escape special characters in the given string of html.

Parameters:
Name Type Description
string string

The string to escape for inserting into HTML

more bool

if false, escapes only tags, if true escapes also quotes and ampersands

Returns:

escaped string

Type
string

(static) fillTimeObject(params, object, property, incrementopt) → {void}

Source:

Modifies provided object in the format object["2012.7.20.property"] = increment. Usualy used when filling up Countly metric model data

Example
var obj = {};
common.fillTimeObject(params, obj, "u", 1);
console.log(obj);
//outputs
{ '2017.u': 1,
  '2017.2.u': 1,
  '2017.2.23.u': 1,
  '2017.2.23.8.u': 1,
  '2017.w8.u': 1 }
Parameters:
Name Type Attributes Description
params params

params object

object object

object to fill

property string

meric value or segment or property to fill/increment

increment number <optional>

by how much to increments, default is 1

Returns:

void

Type
void

(static) fillTimeObjectMonth(params, object, property, incrementopt, forceHouropt) → {void}

Source:

Modifies provided object filling properties used in monthly documents in the format object["2012.7.20.property"] = increment. Usualy used when filling up Countly metric model monthly document

Example
var obj = {};
common.fillTimeObjectMonth(params, obj, "u", 1);
console.log(obj);
//outputs
{ 'd.23.u': 1, 'd.23.12.u': 1 }
Parameters:
Name Type Attributes Description
params params

params object

object object

object to fill

property string

meric value or segment or property to fill/increment

increment number <optional>

by how much to increments, default is 1

forceHour boolean <optional>

force recording hour information too, dfault is false

Returns:

void

Type
void

(static) fillTimeObjectZero(params, object, property, incrementopt) → {void}

Source:

Modifies provided object filling properties used in zero documents in the format object["2012.7.20.property"] = increment. Usualy used when filling up Countly metric model zero document

Example
var obj = {};
common.fillTimeObjectZero(params, obj, "u", 1);
console.log(obj);
//outputs
{ 'd.u': 1, 'd.2.u': 1, 'd.w8.u': 1 }
Parameters:
Name Type Attributes Description
params params

params object

object object

object to fill

property string

meric value or segment or property to fill/increment

increment number <optional>

by how much to increments, default is 1

Returns:

void

Type
void

(static) fixEventKey(eventKey) → {string|false}

Source:

Fix event keys before storing in database by removing dots and $ from the string, removing other prefixes and limiting length

Parameters:
Name Type Description
eventKey string

key value to fix

Returns:

escaped key or false if not possible to use key at all

Type
string | false

(static) generatePassword(length, no_special) → {string}

Source:

Generate random password

Example
//outputs 4UBHvRBG1v
common.generatePassword(10, true);
Parameters:
Name Type Description
length number

length of the password

no_special boolean

do not include special characters

Returns:

password

Type
string

(static) getDate(timestamp, timezone) → {moment}

Source:

Creates a Date object from provided seconds timestamp in provided timezone

Parameters:
Name Type Description
timestamp number

unix timestamp in seconds

timezone string

name of the timezone

Returns:

moment object for provided time

Type
moment

(static) getDateIds(params) → {object}

Source:

Get object of date ids that should be used in fetching standard metric model documents

Parameters:
Name Type Description
params params

params object

Returns:

with date ids, as {zero:"2017:0", month:"2017:2"}

Type
object

(static) getDaysInYear(year) → {number}

Source:

Returns amount of days in provided year

Parameters:
Name Type Description
year number

year to check for days

Returns:

number of days in provided year

Type
number

(static) getDescendantProp(obj, desc) → {object}

Source:

Fetches nested property values from an obj.

Example
//outputs {"u":20,"t":20,"n":5}
common.getDescendantProp({"2017":{"1":{"2":{"u":20,"t":20,"n":5}}}}, "2017.1.2");
Parameters:
Name Type Description
obj object

standard countly metric object

desc string

dot separate path to fetch from object

Returns:

fetched object from provided path

Type
object

(static) getDiff(moment1, moment2, measure) → {number}

Source:

Get diference between 2 momentjs instances in specific measurement

Parameters:
Name Type Description
moment1 moment

momentjs with start date

moment2 moment

momentjs with end date

measure string

units of difference, can be minutes, hours, days, weeks

Returns:

difference in provided units

Type
number

(static) getDOY(timestamp, timezone) → {number}

Source:

Returns day of the year from provided seconds timestamp in provided timezone

Parameters:
Name Type Description
timestamp number

unix timestamp in seconds

timezone string

name of the timezone

Returns:

current day of the year

Type
number

(static) getIpAddress(req) → {string}

Source:

Get IP address from request object

Parameters:
Name Type Description
req req

nodejs request object

Returns:

ip address

Type
string

(static) getISOWeeksInYear(year) → {number}

Source:

Returns amount of iso weeks in provided year

Parameters:
Name Type Description
year number

year to check for days

Returns:

number of iso weeks in provided year

Type
number

(static) indexOf(array, property, value) → {number}

Source:

Return index of array with objects where property = value

Parameters:
Name Type Description
array array

array where to search value

property string

property where to look for value

value varies

value you are searching for

Returns:

index of the array

Type
number

(static) initTimeObj(appTimezone, reqTimestamp) → {timeObject}

Source:

Creates a time object from request's milisecond or second timestamp in provided app's timezone

Parameters:
Name Type Description
appTimezone string

app's timezone

reqTimestamp number

timestamp in the request

Returns:

Time object for current request

Type
timeObject

(static) isNumber(n) → {boolean}

Source:

Checks if provided value could be converted to a number, even if current type is other, as string, as example value "42"

Example
common.isNumber(1) //outputs true
common.isNumber("2") //outputs true
common.isNumber("test") //outputs false
Parameters:
Name Type Description
n any

value to check if it can be converted to number

Returns:

true if can be a number, false if can't be a number

Type
boolean

(static) md5Hash(str) → {string}

Source:

Create MD5 hash from provided value

Parameters:
Name Type Description
str string

value to hash

Returns:

MD5 hash

Type
string

(static) mergeQuery(ob1, ob2) → {object}

Source:

Merge 2 mongodb update queries

Parameters:
Name Type Description
ob1 object

existing database update query

ob2 object

addition to database update query

Returns:

merged database update query

Type
object

(static) o(arguments) → {object}

Source:

Returns plain object with key set to value

Parameters:
Name Type Description
arguments varies

every odd value will be used as key and every event value as value for odd key

Returns:

new object with set key/value properties

Type
object

(static) optional(module, options, value) → {number}

Source:

Optionally load module if it exists

Parameters:
Name Type Description
module string

module name

options object

additional opeitons

Properties
Name Type Description
rethrow boolean

throw exception if there is some other error

value varies

value you are searching for

Returns:

index of the array

Type
number

(static) p(f) → {Promise}

Source:

Promise that tries to catch errors

Parameters:
Name Type Description
f function

function which is usually passed to Promise constructor

Returns:

Promise with constructor catching errors by rejecting the promise

Type
Promise

(static) parseSequence(num) → {string}

Source:

Parse Sequence

Parameters:
Name Type Description
num number

sequence number for id

Returns:

converted to base 62 number

Type
string

(static) processCarrier(metrics)

Source:

Update carrier from metrics to convert mnc/mcc code to carrier name

Parameters:
Name Type Description
metrics object

metrics object from SDK request

(static) recordCustomMetric(params, collection, id, metrics, valueopt, segments, uniques, lastTimestamp)

Source:

Record data in Countly standard metric model Can be used by plugins to record data, similar to sessions and users, with optional segments

Example
//recording attribution
common.recordCustomMetric(params, "campaigndata", campaignId, ["clk", "aclk"], 1, {pl:"Android", brw:"Chrome"}, ["clk"], user["last_click"]);
Parameters:
Name Type Attributes Description
params params

params object

collection string

name of the collections where to store data

id string

id to prefix document ids, like app_id or segment id, etc

metrics array

array of metrics to record, as ["u","t", "n"]

value number <optional>

value to increment all metrics for, default 1

segments object

object with segments to record data, key segment name and value segment value

uniques array

names of the metrics, which should be treated as unique, and stored in 0 docs and be estimated on output

lastTimestamp number

timestamp in seconds to be used to determine if unique metrics it unique for specific period

(static) recordMetric(params, props)

Source:

Record data in Countly standard metric model Can be used by plugins to record data, similar to sessions and users, with optional segments

Example
//recording attribution
common.recordCustomMetric(params, "campaigndata", campaignId, ["clk", "aclk"], 1, {pl:"Android", brw:"Chrome"}, ["clk"], user["last_click"]);
Parameters:
Name Type Description
params params

params object

props object

object defining what to record

Properties
Name Type Description
collection string

name of the collections where to store data

id string

id to prefix document ids, like app_id or segment id, etc

metrics object

object defining metrics to record, using key as metric name and value object for segmentation, unique, etc

Properties
Name Type Attributes Description
value number <optional>

value to increment current metric for, default 1

segments object

object with segments to record data, key segment name and value segment value or array of segment values

unique boolean

if metric should be treated as unique, and stored in 0 docs and be estimated on output

lastTimestamp number

timestamp in seconds to be used to determine if unique metrics it unique for specific period

hourlySegments array

array of segments that should have hourly data too (by default hourly data not recorded for segments)

(static) returnMessage(params, returnCode, message, heads)

Source:

Output message as request response with provided http code

Parameters:
Name Type Description
params params

params object

returnCode number

http code to use

message string

Message to output, will be encapsulated in JSON object under result property

heads object

headers to add to the output

(static) returnOutput(params, output, noescape, heads)

Source:

Output message as request response with provided http code

Parameters:
Name Type Description
params params

params object

output output

object to stringify and output

noescape string

prevent escaping HTML entities

heads object

headers to add to the output

(static) returnRaw(params, returnCode, body, heads)

Source:

Return raw headers and body

Parameters:
Name Type Description
params params

params object

returnCode number

http code to use

body string

raw data to output

heads object

headers to add to the output

(static) reviver(key, value) → {vary}

Source:

Revive json encoded data, as for example, regular expressions

Parameters:
Name Type Description
key string

key of json object

value vary

value of json object

Returns:

modified value, if it had revivable data

Type
vary

(static) safeDivision(dividend, divisor) → {number}

Source:

Safe division between numbers providing 0 as result in cases when dividing by 0

Example
//outputs 0
common.safeDivision(100, 0);
Parameters:
Name Type Description
dividend number

number which to divide

divisor number

number by which to divide

Returns:

result of division

Type
number

(static) sanitizeFilename(filename, replacement) → {string}

Source:

Sanitizes a filename to prevent directory traversals and such.

Parameters:
Name Type Description
filename string

filename to sanitize

replacement string

string to replace characters to be removed

Returns:

sanitizedFilename - sanitized filename

Type
string

(static) sha1Hash(str, addSaltopt) → {string}

Source:

Create HMAC sha1 hash from provided value and optional salt

Parameters:
Name Type Attributes Description
str string

value to hash

addSalt string <optional>

optional salt, uses ms timestamp by default

Returns:

HMAC sha1 hash

Type
string

(static) sha512Hash(str, addSaltopt) → {string}

Source:

Create HMAC sha512 hash from provided value and optional salt

Parameters:
Name Type Attributes Description
str string

value to hash

addSalt string <optional>

optional salt, uses ms timestamp by default

Returns:

HMAC sha1 hash

Type
string

(static) unblockResponses(params)

Source:
Parameters:
Name Type Description
params params

params object

(static) updateAppUser(params, update, no_meta, callback)

Source:

Single method to update app_users document for specific user for SDK requests

Parameters:
Name Type Description
params params

params object

update object

update query for mongodb, should contain operators on highest level, as $set or $unset

no_meta boolean

if true, won't update some auto meta data, like first api call, last api call, etc.

callback function

function to run when update is done or failes, passing error and result as arguments

(static) validateArgs(args, argProperties, returnErrors) → {object}

Source:

Validates provided arguments

Parameters:
Name Type Description
args object

arguments to validate

argProperties object

rules for validating each argument

Properties
Name Type Description
required boolean

should property be present in args

type string

what type should property be, possible values: String, Array, Number, URL, Boolean, Object, Email

max-length string

property should not be longer than provided value

min-length string

property should not be shorter than provided value

exclude-from-ret-obj string

should property be present in returned validated args object

has-number string

should string property has any number in it

has-char string

should string property has any latin character in it

has-upchar string

should string property has any upper cased latin character in it

has-special string

should string property has any none latin character in it

returnErrors boolean

return error details as array or only boolean result

Returns:

validated args in obj property, or false as result property if args do not pass validation and errors array

Type
object

(static) versionCompare(v1, v2, options) → {number}

Source:

Compares two version strings with : as delimiter (which we used to escape dots in app versions)

Parameters:
Name Type Description
v1 string

first version

v2 string

second version

options object

providing additional options

Properties
Name Type Description
delimiter string

delimiter between version, subversion, etc, defaults :

zeroExtend string

changes the result if one version string has less parts than the other. In this case the shorter string will be padded with "zero" parts instead of being considered smaller.

lexicographical string

compares each part of the version strings lexicographically instead of naturally; this allows suffixes such as "b" or "dev" but will cause "1.10" to be considered smaller than "1.2".

Returns:

0 if they are both the same, 1 if first one is higher and -1 is second one is higher

Type
number

(static) zeroFill(number, width) → {string}

Source:

Pad number with specified character from left to specified length

Example
//outputs 0012
common.zeroFill(12, 4, "0");
Parameters:
Name Type Description
number number

number to pad

width number

pad to what length in symbols

Returns:

padded number

Type
string

(inner) escape_html_entities(key, value, more) → {vary}

Source:

Escape special characters in the given value, may be nested object

Parameters:
Name Type Description
key string

key of the value

value vary

value to escape

more bool

if false, escapes only tags, if true escapes also quotes and ampersands

Returns:

escaped value

Type
vary

(inner) getJSON(val) → {object}

Source:

Check if string is a valid json

Parameters:
Name Type Description
val string

string that might be json encoded

Returns:

with property data for parsed data and property valid to check if it was valid json encoded string or not

Type
object

(inner) recordMetric(params, metric, props, tmpSet, updateUsersZero, updateUsersMonth)

Source:

Record specific metric

Parameters:
Name Type Description
params params

params object

metric string

metric to record

props object

properties of a metric defining how to record it

tmpSet object

object with already set meta properties

updateUsersZero object

object with already set update for zero docs

updateUsersMonth object

object with already set update for months docs

(inner) recordSegmentMetric(params, metric, name, val, props, tmpSet, updateUsersZero, updateUsersMonth, zeroObjUpdate, monthObjUpdate)

Source:

Record specific metric segment

Parameters:
Name Type Description
params params

params object

metric string

metric to record

name string

name of the segment to record

val string

value of the segment to record

props object

properties of a metric defining how to record it

tmpSet object

object with already set meta properties

updateUsersZero object

object with already set update for zero docs

updateUsersMonth object

object with already set update for months docs

zeroObjUpdate array

segments to fill for for zero docs

monthObjUpdate array

segments to fill for months docs

(inner) stripPort(ip) → {string}

Source:

This function takes ipv4 or ipv6 with possible port, removes port information and returns plain ip address

Parameters:
Name Type Description
ip string

ip address to check for port and return plain ip

Returns:

plain ip address

Type
string