elv-js-helpers

A collection of Javascript helper functions used by several Eluvio libraries.

THIS LIBRARY IS CURRENTLY IN PRE-RELEASE: FUNCTION NAMES AND SIGNATURES ARE STILL IN FLUX.

API Documentation

Installation

#### Install from NPM:

``
npm install --save @eluvio/elv-js-helpers
`

Usage

It is possible to import individual items or the entire library, depending on whether code size is a concern.

$3

`javascript
// namespace entire suite to a const
const H = require('@eluvio/elv-js-helpers')

console.log(H.Datetime.now())

// create references to particular items in order to avoid needing to use H.Category prefix
const { etaDurStr, etaTimeStr } = H.Datetime
const {_boundLowerErrMsg} = H.ModelAssertion

// Get reference to 1 category (note that this will still wind up incuding the entire package)
const { Datetime } = require('@eluvio/elv-js-helpers')
console.log(Datetime.now())
`

$3

`javascript
// namespace entire suite to H
import H from '@eluvio/elv-js-helpers'

// create references to particular items in order to avoid needing to use H. prefix
const { etaDurStr, etaTimeStr } = H.Datetime
const {_boundLowerErrMsg} = H.ModelAssertion

// Note that the following syntax still causes entire library to be bundled into your project
import { Datetime } from '@eluvio/elv-js-helpers'
`

$3

Importing individual items will minimize code size.

`javascript
// require in each item directly
const etaDurStr = require('@eluvio/elv-js-helpers/Datetime/etaDurStr')
const etaTimeStr = require('@eluvio/elv-js-helpers/Datetime/etaTimeStr')
const _boundLowerErrMsg = require('@eluvio/elv-js-helpers/ModelAssertion/_boundLowerErrMsg')
`

$3

`javascript
// import in each item directly
import etaDurStr from '@eluvio/elv-js-helpers/Datetime/etaDurStr'
import etaTimeStr from '@eluvio/elv-js-helpers/Datetime/etaTimeStr'
import _boundLowerErrMsg from '@eluvio/elv-js-helpers/ModelAssertion/_boundLowerErrMsg'
`

$3

Although not recommended, it is also possible to import the entire library directly into a browser via a

`

Conventions

$3

* Each function (or exported constant) has its own source file.
* Each source file exports exactly 1 item.
* Files have the same case-sensitive name as the function or constant it defines (with .js extension added)
* Files are stored in subdirectories of src/ according to category (1 category per subdirectory)

$3

#### Abbreviations

* Names tend to err on the side of not abbreviating, prioritizing clarity over brevity:
* conditionalCheck _not_ condlChk _(function)_
* sysTimezone _not_ sysTZ _(function)_
* When an item name would be cumbersome or excessively long otherwise, abbreviations and/or acronyms are used for words where the meaning remains reasonably clear and obvious:
* assertPropMaxGTEMin _not_ assertPropertyMaximumGreaterThanOrEqualToMinimum _(function)_
* defNonEmptyArrModel _not_ defineNonEmptyArrayModel _(function)_
* RE_UTC_TIMESTAMP _not_ REGEXP_UNIVERSAL_TIME_COORDINATED_TIMESTAMP _(constant)_
* A few abbreviations stretch the "reasonably clear and obvious" condition:
* ADT _not_ AlgebraicDataType _(category)_
* resultToPOJO _not_ resultToPlainOldJavascriptObject _(function)_

#### Capitalization (general)

* Compound words that are widely treated as single words do not capitalize the second word:
* Datetime _not_ DateTime _(category)_
* sysTimezone _not_ sysTimeZone _(function)_
* RE_UTC_TIMESTAMP _not_ RE_UTC_TIME_STAMP _(constant)_
* Acronyms are kept all the same case, either upper or lower depending on kind of item and position within name:
* ADT _not_ Adt _(category)_
* parseUTCStr _not_ parseUtcStr _(function)_
* utcStrToDate _not_ uTCStrToDate _(function)_
* etaDurStr _not_ eTADurStr _(function)_
* For greater legibility, the prefix "non" is treated as a word:
* NonBlankStrModel _not_ NonblankStrModel _(model)_
* wrapNonArray _not_ wrapNonarray _(function)_

#### Capitalization (by item type)

* ADTs: PascalCase (List, Ok)
* Categories: PascalCase (ModelAssertion, ModelFactory)
* Constants: UPPER_SNAKE_CASE (RE_UTC_TIMESTAMP)
* Regular expression names start with "RE_"
* Models: PascalCase (NonBlankStrModel)
* Model names always end with "Model"
* Functions: camelCase (mapWithIndex, resultUnwrap)
* Note that ADTs and Models are actually functions but are named using PascalCase because they are used more like classes.
* ModelFactory names always start with "def" and end with "Model" (defArrModel, defObjModel)

#### Private Items

* Have names beginning with underscore (_boundLowerErrMsg)
* Are not truly private, they are available for use but are filtered from the documentation page unless Show private` is checked.
* Contain internal code shared by more than one function but considered too specialized to be useful outside the package