1. Home
  2. Classes
  3. Utils

new Utils()

Utility helper methods

Description

For use in any JavaScript project, including Google Apps scripts etc. All methods are available as both static and instance methods for flexibility.

Hybrid Class Pattern:

  • All utility methods are implemented as static methods (e.g., Utils.isBlank())
  • The same methods are also available as instance methods (e.g., M.isBlank())
  • Instance methods are simple delegates to the static methods
  • Full documentation is provided for static methods only to avoid duplication in child class documentation

Base class - Extended by FulcrumHelpers

Methods

<static> padZero( val, len ) → {string}

Add leading zeroes to a number(or string number).

Description

Pads a number OR string with leading zeroes to reach a specified total length. Returns a string with leading zeroes.

Parameters
Name Type Description
val number | string
len number
Returns
Examples
Utils.padZero(1.35,5) //returns: "001.35"

<static> arrSort( arr [, asc ] ) → {void}

Array Sort - Sorts an array, defaults to ascending order.

Description

Sorts an array of strings, numbers, or dates in ascending or descending order. Defaults to ascending order. Automatically determines data type of array contents. MUTATES original array.

Parameters
Name Type Attributes Default Description
arr Array

Array of strings, numbers, or date strings/objects.
asc boolean <optional>
 true

Sort ascending (true) or descending (false).
Returns
  • Sorted array (mutates original array).

<static> arrReverse( arr ) → {void}

Array Reverse - Sorts an array in descending order.

Description

Sorts an array of strings, numbers, or dates in descending order. Automatically determines data type of array contents. MUTATES original array.

Parameters
Name Type Description
arr Array

Array of strings, numbers, or date strings/objects.
Returns
  • Sorted array (mutates original array).

<static> arr2Sorted( arr [, asc ] ) → {Array}

Array to Sorted - Sorts an array, defaults to ascending order.

Description

Sorts an array of strings, numbers, or dates in ascending or descending order. Defaults to ascending order. Automatically determines data type of array contents. Returns a new array.

Parameters
Name Type Attributes Default Description
arr Array

Array of strings, numbers, or date strings/objects.
asc boolean <optional>
 true

Sort ascending (true) or descending (false).
Returns
  • Sorted array (new array, does not mutate original).

<static> arr2Reversed( arr ) → {Array}

Array to Reversed - Sorts an array in descending order.

Description

Sorts an array of strings, numbers, or dates in descending order. Automatically determines data type of array contents. Returns a new array.

Parameters
Name Type Description
arr Array

Array of strings, numbers, or date strings/objects.
Returns
  • Sorted array (new array, does not mutate original).

<static> arrRem( haystack, needle ) → {void}

Array Remove - Remove element from array.

Description

Remove element OR elements from array, needle can be a single element or an array of elements. ie: Remove data_name string from array of data_names. Return new list of field names. MUTATES original array.

Parameters
Name Type Description
haystack Array

array to add element to
needle any

element to remove from array
Returns
  • mutates original array

<static> arr2Rem( haystack, needle ) → {Array}

Array to Remove - Return new array with elements removed.

Description

Remove element OR elements from array, needle can be a single element or an array of elements. ie: Remove data_name string from array of data_names. Return new list of field names. Returns a new array.

Parameters
Name Type Description
haystack Array

array to add element to
needle any

element to remove from array
Returns
  • returns new array with elements removed.

<static> arrSplice( haystack, needle, pos ) → {void}

Array Splice - Add element to array, default to end of array.

Description

Add element to array at position "pos". MUTATES the existing array. ie: Add field name string to list of field names at position "pos". Return new list of field names.

MUTATES existing array.

Parameters
Name Type Default Description
haystack Array

array to add element to
needle any

element to add to array
pos number

position in array to add element
Returns
Details

change to arrInsert

<static> dtAddDays( dt, days ) → {Date}

Date Add Days - Adds days to a date.

Description

Adds a number of days to a date and returns the new date. Input can be a Date object or a date string.

Parameters
Name Type Description
dt Date | string

The starting date (Date object or date string).
days number

Number of days to add.
Returns
  • The new Date object.

<static> dtMonthBounds( dt ) → {Object}

Date Month Bounds - Get first and last day of month for a given date.

Description

Returns the first and last day of the month for a given date.

Parameters
Name Type Description
dt Date | string

A Date object or date string.
Returns

<static> dtDaysDiff( dt1, dt2 ) → {number}

Date Days Difference - Calculate the difference in days between two dates.

Description

Calculate the difference in days between two dates.

Parameters
Name Type Description
dt1 Date
dt2 Date
Returns

<static> iso2dt( str ) → {Date}

ISO to Date - Convert ISO to Date.

Description

Convert ISO date in string format to javascript date/unix timestamp. Strips time and timezone if present before conversion.

Parameters
Name Type Description
str string

ISO date in string format
Returns

<static> dtStrip( str ) → {string}

Date Strip - Strip timezone and time from ISO String date.

Description

Strip timezone and time from ISO date and time in string format

ie: '2024-09-09T16:23:47Z' returns '2024-09-09'

Parameters
Name Type Description
str string

ISO date in string format
Returns

<static> dt2iso( dt ) → {string}

Date to ISO - Convert Date to ISO string.

Description

Convert javascript date/unix timestamp to ISO string with time and timezone stripped. Strips time and timezone from ISO string.

Parameters
Name Type Description
dt Date

ISO date in string format
Returns

<static> dtStr2iso( dateStr ) → {string}

Date String to ISO Date - Convert any date string to ISO date format.

Description

Parses any valid date string format and returns it as ISO date (YYYY-MM-DD) without time or timezone.

Parameters
Name Type Description
dateStr string

Date string in any parseable format
Returns

ISO date string (YYYY-MM-DD) or original value if not a valid date string

<static> arrAnyInArr( arr1, arr2 ) → {boolean}

Array Any in Array - Check if any string in one array is in another array.

Description

Returns true if any string in arr1 matches any string in arr2.

Parameters
Name Type Description
arr1 Array.<string>
arr2 Array.<string>
Returns

<static> arrCountItems( arr ) → {Array.<{item: (string|number), count: number}>}

Array Count Items - Count occurrences of items in an array.

Description

Counts the number of occurrences of each unique item in an array and returns an array of objects, each with properties 'item' and 'count', sorted by count descending. Example: ['a','b','a'] => [ { item: 'a', count: 2 }, { item: 'b', count: 1 } ]

Parameters
Name Type Description
arr Array.<(string|number)>

Array of primitive values to count.
Returns

Array of {item, count} objects sorted by descending count. Returns empty array if input array is empty.

<static> arrListDups( arr ) → {Array}

Array List Duplicates - List duplicate values in an array.

Description

Creates an array containing all values that are present in array more then once. Also see arrUnique to filter an array down to only unique values.

Parameters
Name Type Description
arr Array
Returns

<static> arrUnique( arr ) → {Array}

Array Unique - Filter array to unique values.

Description

Filter an array down to an array of unique values

Parameters
Name Type Description
arr Array
Returns

<static> strAfter( val, search ) → {string}

String After - Return slice AFTER FIRST occurence.

Description

Return slice of string AFTER FIRST occurence of search string. Useful for getting middle section of text after underscore in data_name.

Parameters
Name Type Default Description
val string

string to search IN
search string _

string to search FOR in val
Returns

<static> strSuff( val, search ) → {string}

String Suffix - Return slice AFTER LAST occurence.

Description

Return slice of string AFTER LAST occurence of search string. Useful for getting suffix of text after last underscore in data_name.

Parameters
Name Type Default Description
val string

string to search IN
search string _

string to search FOR in val
Returns

<static> strBefore( val, search ) → {string}

String Before - Return slice BEFORE FIRST occurence.

Description

Return slice of string BEFORE FIRST occurence of search string. Useful for getting prefix of text before first underscore in data_name.

Parameters
Name Type Default Description
val string

string to search IN
search string _

string to search FOR in val
Returns

<static> isNumber( val ) → {boolean}

Determines if a value is a number.

Description

Determines if a value is a number (not NaN, not a string).

Parameters
Name Type Description
val any
Returns

<static> isDate( val ) → {boolean}

Determines if a value is a valid Date object or a valid date string.

Description

returns true if val is a Date object or a valid date string.

Parameters
Name Type Description
val any
Returns

<static> isDateStr( str ) → {boolean}

Determines if a string is a valid date string.

Description

Validates if a string can be parsed as a valid date, including ISO 8601 format and other common date formats. Rejects strings that don't match common date patterns to avoid false positives from JavaScript's permissive Date parser.

Parameters
Name Type Description
str string
Returns

<static> isISOdt( str ) → {boolean}

Check if string is in ISO 8601 date format.

Description

Checks if string is in the format of an ISO 8601 date format ie: '2011-10-05T14:48:00.000Z'

Parameters
Name Type Description
str string
Returns

<static> isBlank( val ) → {boolean}

Check if variable is blank.

Description

Check if variable is undefined, null or '' (empty string) OR if it is an Array if it has a length of 0 OR if it is an Object if it has an Object.keys() length of 0

Parameters
Name Type Description
val any
Returns

<static> isChoiceFieldValue( val ) → {boolean}

Check if value is a Fulcrum choice field object

Description

Validates if object has choice_values array property

Parameters
Name Type Description
val any
Returns

<static> isAddressFieldValue( val ) → {boolean}

Check if value is a Fulcrum address field object

Description

Validates if object has standard address properties

Parameters
Name Type Description
val any
Returns

<static> fVal( val [, naVal ] ) → {string}

Format Value - Format unknown value to printable String.

Description

Format unknown value to Merjent standard formatted String. Useful for values returned from Query API or REPEATABLEVALUES. This function is intended for unknown values that are not returned from a fulcrum field. For values from a fulcrum field use the fldVal method.

Parameters
Name Type Attributes Default Description
val any
naVal string <optional>
 '---'

Value for null, undefined and empty strings
Returns
Examples
fVal('2011-10-05T14:48:00.000Z') // returns '2011-10-05'
fVal(['apples','oranges','bananas']) // returns 'apples, oranges, bananas'

<static> formatAddress( val ) → {string}

Format Address

Description

Formats a fulcrum address object into a us address formated string.

Parameters
Name Type Description
val Object
Returns
Details

addr2Str

<static> flipKVpair( obj ) → {*}

Flip Key:Value Pair - Flips keys and values in an object.

Description

Flips keys and values in an object. Object must have unique values. Input is an Object NOT an array of objects.

Parameters
Name Type Description
obj *
Returns
Details

obj2Flipped

<static> str2html( strings, ...vals ) → {*}

Clean HTML - Removes newlines and trims whitespace from template literal.

Description

Useful for embedding HTML snippets in JavaScript without extra whitespace or newlines. removes all newline characters (\r and \n). removes any leading or trailing whitespace.

Parameters
Name Type Attributes Description
strings string
vals Object <repeatable>
Returns
Details

better name? cleanTemplateLiteral?

<static> strProper( word ) → {string}

String Proper - Capitalizes the first character of a word

Description

Capitalizes the first character of a word and converts the rest to lowercase.

Parameters
Name Type Description
word string

The word to capitalize.
Returns
  • The capitalized word.

<static> dn2Title( str ) → {string}

data_name to Title - Converts a string with underscores to title case.

Description

Converts a string to title case by replacing '_' with a ' ' and applying capitalization to each word. Use to convert Fulcrum data_name strings to title case.

Parameters
Name Type Description
str string

The input string.
Returns
  • The string converted to title case.
Details

change to str2Title

<static> str2Snake( str ) → {string}

Description

Convert string to snake_case

Parameters
Name Type Description
str string

Input string
Returns

Snake case string

Examples
str2Snake("camelCase")        // "camel_case"
str2Snake("PascalCase")       // "pascal_case"
str2Snake("kebab-case")       // "kebab_case"
str2Snake("Title Case")       // "title_case"
str2Snake("SCREAMING_SNAKE")  // "screaming_snake"
str2Snake("mixedUP_string")   // "mixed_up_string"

<static> rowsFind( rows, key, val ) → {Array.<Object>}

Rows Find - Find objects in array by property value.

Description

Finds objects with property matching lookup value in an array of objects and returns that object.

Parameters
Name Type Description
rows Array.<Object>

The array of objects to search.
key string

The property to look up in the objects.
val string

The value to match against the property.
Returns

<static> rowsRem( rows, key, val ) → {void}

Rows Remove - Remove objects from array by property value(s).

Description

Removes all objects where the specified property matches the value or any value in array. MUTATES original array.

Parameters
Name Type Description
rows Array.<Object>

Array of objects to filter
key string

Property name to check
val any | Array.<any>

Value(s) to match for removal
Returns
  • Mutates original array
Examples
const users = [{id: 1}, {id: 2}, {id: 3}];
M.rowsRem(users, 'id', [1, 3]); // users is now [{id: 2}]

<static> rows2Rem( rows, key, val ) → {Array.<Object>}

Rows to Remove - Return new array with objects removed by property value(s).

Description

Removes all objects where the specified property matches the value or any value in array. Returns a new array.

Parameters
Name Type Description
rows Array.<Object>

Array of objects to filter
key string

Property name to check
val any | Array.<any>

Value(s) to match for removal
Returns
  • New array with matching objects removed
Examples
const users = [{id: 1}, {id: 2}, {id: 3}];
const filtered = M.rows2Rem(users, 'id', [1, 3]); // returns [{id: 2}]

<static> rows2Sorted( arr, key [, asc [, type ] ] ) → {Array.<Object>}

Rows to Sorted - Sorts an array of Objects, defaults to ascending order.

Description

Sorts an array of objects by a given property, or by value if objects contain only one key:value pair and parameter 'key' is null. Automatically sorts as number if type is 'number' or values are numbers, and as date if type is 'date' or values are valid dates. Returns a new array.

Parameters
Name Type Attributes Default Description
arr Array.<Object>

Array of objects to sort.
key string | null

Property name to sort by, or null to sort by value if objects have only one key:value pair.
asc boolean <optional>
 true

Sort ascending (true) or descending (false).
type 'string' | 'number' | 'date' <optional>
 'string'

Type of property to sort by.
Returns
  • Sorted array (new array, does not mutate original).

<static> dd2dms( dd, isLat ) → {array}

Decimal Degrees to DMS

Description

Converts decimal degrees to Degrees, Minutes, Seconds (DMS) format.

Parameters
Name Type Description
dd number

The decimal degrees value (e.g., 40.6892). Positive for N/E, negative for S/W.
isLat boolean

true for latitude, false for longitude.
Returns

[degrees,minutes,seconds,direction,The DMS string (e.g., "40° 41' 21.12" N")]

<static> dms2dd( deg, min, sec [, dir ] ) → {number}

DMS to Decimal Degrees

Description

Converts Degrees, Minutes, Seconds (DMS) to Decimal Degrees. Input direction is optional and defaults to 'N' or 'E' (ie: positive number in DD).

Parameters
Name Type Attributes Default Description
deg number

The degrees part (e.g., 40).
min number

The minutes part (e.g., 41).
sec number

The seconds part (e.g., 21.12).
dir string <optional>
 'N'

The directional quadrant (N, S, E, or W).
Returns

The decimal degrees value (e.g., 40.6892).

<static> deg2Dir( degrees [, secondary ] ) → {string}

Description

Convert degrees to compass direction

Parameters
Name Type Attributes Default Description
degrees number

Direction in degrees (0-360)
secondary boolean <optional>
 false

If true, uses 16-point compass. If false, uses 8-point compass.
Returns

Compass direction

Examples
Utils.deg2Dir(0)           // "N"
Utils.deg2Dir(45)          // "NE" (default 8-point)
Utils.deg2Dir(45, true)    // "NE"
Utils.deg2Dir(22.5)        // "NE" (8-point, 22.5° is center of NE range)
Utils.deg2Dir(22.5, true)  // "NNE" (16-point, 22.5° is center of NNE)
Utils.deg2Dir(67.5, true)  // "ENE"
Utils.deg2Dir(11)          // "N" (just before NE range starts at 22.5°)

<static> dir2Deg( direction [, secondary ] ) → {number}

Description

Convert compass direction to degrees

Parameters
Name Type Attributes Default Description
direction string

Compass direction (e.g., "N", "NE", "NNE", etc.)
secondary boolean <optional>
 false

If true, accepts 16-point compass (includes NNE, ENE, etc.). If false, accepts only 8-point compass.
Returns

Direction in degrees (0-360), or null if invalid direction

Examples
Utils.dir2Deg("N")           // 0
Utils.dir2Deg("NE")          // 45
Utils.dir2Deg("E")           // 90
Utils.dir2Deg("NNE")         // null (secondary = false by default)
Utils.dir2Deg("NNE", true)   // 22.5
Utils.dir2Deg("ENE", true)   // 67.5
Utils.dir2Deg("n")           // 0 (case-insensitive)