Documentation

Module: sjl

`sjl` module.

Namespaces

stdlib

Methods

<static> addRevealingModuleCall(obj, functionKey, shortFunctionKey)

Revealing module pattern seeder. Adds the revealing module pattern call to passed in object. Gives said object the revealing module pattern capability (for in browser use).
Parameters:
Name Type Description
obj Object | * Object to set the revealing module pattern method on.
functionKey String Key to set the revealing module setter and store to. Default 'module'.
shortFunctionKey String Shorthand name to use for revealing module setter and store. Default 'ns'.
Returns:
- Returns passed in `obj`.
Type
Object | *
Example
```
 var myApp = sjl.addRevealingModuleCall ({}, 'module');

 // Creates all namespace objects, if they don't already exist, and protects them from being overwritten (uses Object.defineProper(ty|ties) internally)
 // Then sets your module at the end of the chain also making it `unconfigurable` and `unwritable` as a property
 // on the namespace chain though does not protect MyModule itself from being tampered with (for security on
 // that level look into `Object.freeze`).
 myApp.module('some.deep.namespace.MyModule', MyModule); // returns MyModule

 // Fetching module that was set now becomes cleaner and module will always be there and cannot be deleted from location
 myApp.some.namespace.MyModule === MyModule; // true

```

<static> argsToArray(args)

Calls Array.prototype.slice on arguments object passed in.
Parameters:
Name Type Description
args Arguments
Returns:
Type
Array

<static> autoNamespace(ns_string, objToSearch, valueToSet)

Takes a namespace string and fetches that location out from an object/Map. If the namespace doesn't exists it is created then returned. Also allows you to set a value at that namespace (last parameter).
Parameters:
Name Type Description
ns_string String The namespace you wish to fetch
objToSearch Object The object to search for namespace on
valueToSet Object Optional. A value to set on the key (last key if key string (a.b.c.d = value)).
Returns:
Type
Object
Examples
// will create/fetch within `obj`: hello: { world: { how: { are: { you: { doing: {} } } } } }
autoNamespace ('hello.world.how.are.you.doing', obj)
// Will set 'hello.what.is.your.name' to 'juan'
autoNamespace ('hello.what.is.your.name', obj, 'juan')

<static> camelCase(str, upperFirst, replaceStrRegex)

Make a string code friendly. Camel cases a dirty string into a valid javascript variable/constructor name; Uses `replaceStrRegex` to replace unwanted characters with a '-' and then splits and merges the parts with the proper casing, pass in `true` for lcaseFirst to lower case the first character.
Parameters:
Name Type Description
str String
upperFirst Boolean default `false`
replaceStrRegex RegExp default /[^a-z0-9] * /i (without spaces before and after '*')
Returns:
Type
String

<static> classicalToStringMethod(constructor)

Creates classical styled `toString` method; E.g. `toString` method that returns `'[object ' + constructor.name + ']'` a` la` '[object Array]', '[object Function]' format.
Parameters:
Name Type Description
constructor function
Returns:
- Passed in constructor.
Type
function

<static> classOf(value)

Returns the class name of an object from it's class string.
Parameters:
Name Type Description
value *
Returns:
- A string representation of the type of the value; E.g., 'Number' for `0`
Type
string

<static> classOfIs(obj, type)

Checks to see if an object is of type 'constructor name'. Note: If passing in constructors as your `type` to check, ensure they are *'named' constructors as the `name` property is checked directly on them to use in the class/constructor-name comparison. *'named' constructors - Not anonymous functions/constructors but ones having a name: E.g., ``` (function Hello () {}) // Named function. (function () {}) // Anonymous function. ```
Parameters:
Name Type Description
obj * Object to be checked.
type String | function Either a constructor name or an constructor itself.
Returns:
- Whether object matches class string or not.
Type
Boolean

<static> classOfIsMulti(value, type)

Check if `value` is of one of the passed in types.
Parameters:
Name Type Description
value *
type function | String Constructor or string.
Returns:
Type
boolean

<static> clone(obj)

Returns copy of object.
Parameters:
Name Type Description
obj Object
Returns:
- Cloned object.
Type
*

<static> compose()

Composes one or more functions into a new one.
Returns:
Type
function

<static> constrainPointer(pointer, min, max)

Constrains a number within a set of bounds (range of two numbers) or returns the pointer if it is within bounds. E.g., If pointer is less than `min` then returns `min`. If pointer is greater than `max` returns `max`. If pointer is within bounds returns `pointer`.
Parameters:
Name Type Description
pointer Number
min Number
max Number
Returns:
Type
Number

<static> createTopLevelPackage(obj, funcKey, altFuncKey)

Package factory method. Allows object to have a `package` method which acts like java like namespace except it allows you to set it's members (once) and then protects it's members.
Parameters:
Name Type Description
obj Object | * Object to set the `package` method on.
funcKey String Key to set package function to. E.g., 'package'
altFuncKey String Alternate (usually shorter) key to set package function to. E.g., 'ns' ignore passed in paths as namespaces. Optional. Default `null`.
Returns:
- Returns passed in `obj`.
Type
Object | *

<static> curry(fn)

Curries a function with or without placeholders (sjl._ is `Placeholder`)
Parameters:
Name Type Description
fn function
Returns:
Type
function
Example
```
var slice = Array.prototype.slice,
    add = function () {...}, // recursively adds
    multiply = function () {...}; // recursively multiplies

  sjl.curry(add, __, __, __)(1, 2, 3, 4, 5) === 15 // `true`
  sjl.curry(multiply, __, 2, __)(2, 2) === Math.pow(2, 3) // `true`
  sjl.curry(divide, __, 625, __)(3125, 5)

```

<static> curry1()

Curries a function up to arity/args-length 1.
Returns:
Type
function

<static> curry2()

Curries a function up to arity/args-length 2.
Returns:
Type
function

<static> curry3()

Curries a function up to arity/args-length 3.
Returns:
Type
function

<static> curry4()

Curries a function up to arity/args-length 4.
Returns:
Type
function

<static> curry5()

Curries a function up to arity/args-length 5.
Returns:
Type
function

<static> curryN(fn, executeArity)

Curries a function and only executes the function when the arity reaches the .
Parameters:
Name Type Description
fn Function to curry.
executeArity Arity at which to execute curried function.
Throws:
- If `fn` is not a function.
Type
TypeError

<static> defineEnumProp(obj, key, value)

Sets an enumerable property on `obj` as not `configurable` and not `writable`.
Parameters:
Name Type Description
obj Object
key String Prop name.
value *
Returns:
Type
void

<static> defineSubClass(superclass, constructor, methods, statics)

Defines a class using a `superclass`, `constructor`, methods and/or static methods.
Parameters:
Name Type Description
superclass function Superclass to inherit from.
constructor function | Object Required. Note: If this param is an object, then other params shift over by 1 (`methods` becomes `statics` and this param becomes `methods` (constructor key expected else empty stand in constructor is used).
methods Object | undefined Methods for prototype. Optional. Note: If `constructor` param is an object, this param takes the place of the `statics` param.
statics Object | undefined Constructor's static methods. Optional. Note: If `constructor` param is an object, this param is not used.
Returns:
Type
function
Example
```
 // sjl.defineSubClass (superclass, methods, statics);
 var NewConstructor = sjl.defineSubClass( SomeConstructor, { constructor: function SomeOtherConstructor () {}, ...}, {...});

 // sjl.defineSubClass (superclass, constructor, methods, statics);
 var NewConstructor = sjl.defineSubClass( SomeConstructor, function SomeOtherConstructor () {}, {...}, {...});

 // Both calls above yield extendable constructors;  E.g.,
 // This call yields another constructor which inherits from NewConstructor and is also extendable (has `extend` static method).
 NewConstructor.extend(AnotherConstructor)

```

<static> defineSubClassPure(superClass, constructor, methods, statics)

Same as `defineSubClass` with out side-effect of `extend` method and `toString` method.
Parameters:
Name Type Description
superClass function Superclass to inherit from.
constructor function | Object Required. Note: If this param is an object, then other params shift over by 1 (`methods` becomes `statics` and this param becomes `methods` (constructor key expected else empty stand in constructor is used).
methods Object | undefined Methods for prototype. Optional. Note: If `constructor` param is an object, this param takes the place of the `statics` param.
statics Object | undefined Constructor's static methods. Optional. Note: If `constructor` param is an object, this param is not used.
Returns:
- Constructor with extended prototype and added statics.
Type
function

<static> empty(value)

Checks to see if passed in argument is empty.
Parameters:
Name Type Description
value * Value to check.
Returns:
Type
Boolean

<static> emptyMulti()

Checks to see if any of the values passed in are empty (null, undefined, empty object, empty array, or empty string).
Returns:
- Returns true if any of the values passed in are empty (null, undefined, empty object, empty array, or empty string).
Type
Boolean

<static> extend(`0`, `1-*`, `last`)

Extends first object passed in with all other object passed in after. First param could be a boolean indicating whether or not to perform a deep extend. Last param could also be a boolean indicating whether to use legacy setters if they are available on the receiving object.
Parameters:
Name Type Description
`0` Object | Boolean If boolean, causes `extend` to perform a deep extend. Optional.
`1-*` Object Objects to merge on @arg 0.
`last` Boolean Optional.
Returns:
- Returns first object passed in or null if no values were passed in.
Type
Object | null
Example
(if last param to passed in to `sjl.extend` is `true`
 var o = {setGreeting: v => this.greeting = 'Hello ' + v},
     otherObject = {greeting: 'Junior'};
 // Calls o.setGreeting when merging otherObject because `true` was passed in
 // as the last parameter
 sjl.extend(o, otherObject, true);

<static> extractBoolFromArrayEnd(array)

Returns boolean from end of array if any. If item at found there is undefined or not a boolean returns `false`.
Parameters:
Name Type Description
array Array
Returns:
Type
Boolean

<static> extractBoolFromArrayStart(array)

Returns boolean from beginning of array if any. If item at beginning of array is undefined returns `false`.
Parameters:
Name Type Description
array Array
Returns:
Type
Boolean

<static> extractFromArrayAt(array, index, type, makeCopyOfArray)

Extracts a value at an `index` of passed in array (alternately only extract the value if it is of `type`). Returns an array with two elements: Element `1` contains the extracted value and element `2` the resulting array of the extraction (copy of original array with extracted element) of the value at `index`.
Parameters:
Name Type Description
array Array Array to extract from.
index Number Index of element to look for in `array`.
type String | function Type (name or constructor) to match on. Optional.
makeCopyOfArray Boolean | Undefined Whether to make a copy of the array or not. Default `true`.
Returns:
- If passed in array has an element at `index` (and alternately) element matches `type` then returns an array with found value at index and resulting array of extraction of said value. Else returns an array containing `null` and passed in array.
Type
Array.<*, Array>

<static> forEach(arrayLike, callback, context)

For each for array like objects.
Parameters:
Name Type Description
arrayLike Array | Set | SjlSet | SjlMap | Map
callback
context

<static> forEachInObj(obj, callback, context)

Parameters:
Name Type Description
obj Object
callback function
context undefined | Object

<static> hasMethod(obj, method)

Checks if object has method key passed.
Parameters:
Name Type Description
obj Object | * Object to search on.
method Method name to search for.
Returns:
Type
Boolean

<static> implode(list, separator)

Implodes a `Set`, `Array` or `SjlSet` passed in.
Parameters:
Name Type Description
list Array | Set | SjlSet Members to join.
separator String Separator to join members with.
Returns:
- Imploded string. *Returns empty string if no members, to join, are found.
Type
string

<static> isArray(value)

Checks if value is an array.
Parameters:
Name Type Description
value *
Returns:
Type
boolean

<static> isBoolean(value)

Checks if value is a boolean.
Parameters:
Name Type Description
value *
Returns:
Type
Boolean

<static> isEmptyObj(obj)

Checks object's own properties to see if it is empty (Object.keys check).
Parameters:
Name Type Description
obj object to be checked
Returns:
Type
Boolean

<static> isEmptyOrNotOfType(value, type)

Retruns a boolean based on whether a key on an object has an empty value or is empty (not set, undefined, null)
Parameters:
Name Type Description
value Object Object to search on.
type String Optional. Type Name to check for match for; E.g., 'Number', 'Array', 'HTMLMediaElement' etc..
Deprecated:
  • - Will be removed in version 6.0.0. Use `notEmptyAndOfType` instead.
Returns:
Type
Boolean

<static> isFunction(value)

Returns whether a value is a function or not.
Parameters:
Name Type Description
value *
Returns:
Type
Boolean

<static> isNull(value)

Checks if value is null.
Parameters:
Name Type Description
value *
Returns:
Type
Boolean

<static> isNumber(value)

Checks if value is a valid number (also checks if isNaN so that you don't have to).
Parameters:
Name Type Description
value *
Returns:
Type
Boolean

<static> isObject(value)

Checks whether value is an object or not.
Parameters:
Name Type Description
value
Returns:
Type
Boolean

<static> isset(value)

Checks to see if value passed in is set (not undefined and not null).
Parameters:
Name Type Description
value * Value to check.
Returns:
Type
Boolean

<static> issetAndOfType(value, type)

Checks whether a value isset and if it's type is the same as the type name passed in.
Parameters:
Name Type Description
value * Value to check on.
type String | function Constructor name string or Constructor. You can pass one or more types.
Returns:
Type
Boolean

<static> issetMulti()

Checks if one or more parameters are set (not null and not undefined).
Returns:
- True if all params passed in are not null or undefined.
Type
Boolean

<static> isString(value)

Checks whether value is a string or not.
Parameters:
Name Type Description
value *
Returns:
Type
Boolean

<static> isSymbol(value)

Checks if value is a `Symbol`.
Parameters:
Name Type Description
value *
Returns:
Type
Boolean

<static> isUndefined(value)

Checks if value is undefined.
Parameters:
Name Type Description
value *
Returns:
Type
Boolean

<static> iterable(arrayOrObj)

Defines an es6 compliant iterator callback on `Object` or `Array`.
Parameters:
Name Type Description
arrayOrObj Array | Object Array or object to set iterator function on.
Returns:
Type
Array | Object

<static> jsonClone(obj)

Returns copy of object using JSON stringify/parse.
Parameters:
Name Type Description
obj Object Object to clone.
Returns:
- Cloned object.
Type
*

<static> lcaseFirst(str)

Lower cases first character of a string.
Parameters:
Name Type Description
str String
Throws:
TypeError
Returns:
Type
String

<static> makeExtendableConstructor(constructor)

Adds `extend` and `extendWith` static methods to the passed in constructor for having easy extensibility via said methods; I.e., passed in constructor will now be extendable via added methods.
Parameters:
Name Type Description
constructor function
See:
  • sjl.defineSubClass(superClass, constructor, methods, statics)
Returns:
Type
*

<static> mergeOnProps(obj1, obj2, deep)

Merges property values from object 2 to object 1 where possible (where property is writable or has getters and setters).
Parameters:
Name Type Description
obj1 Object
obj2 Object
deep Boolean Optional. Default `false`.
Returns:
- Passed in object at param 1.
Type
Object

<static> mergeOnPropsMulti(obj1 [, obj2,])

A strict version of sjl.extend; I.e., only merges on properties existing on `obj1`.
Parameters:
Name Type Argument Description
obj1 Object | Boolean If this param is set to a boolean then deep merge takes place.
obj2, Object <optional>
 One or more objects to operate on.
Returns:
Type
*

<static> notEmptyAndOfType(value, type)

Returns true if an element is not empty and is of type.
Parameters:
Name Type Description
value * Value to check.
type String | function Type to check against (string name or actual constructor).
Returns:
Type
Boolean

<static> ns()

Create top level frontend package.

<static> restArgs(args, start [, end])

Slices passed in arguments object (not own arguments object) into array from `start` to `end`.
Parameters:
Name Type Argument Description
args Arguments | Array
start Number | undefined
end Number | undefined <optional>
 Optional. Default `args.length`.
Returns:
Type
Array

<static> searchObj(ns_string, objToSearch)

Searches an object for namespace string.
Parameters:
Name Type Description
ns_string String Namespace string; E.g., 'all.your.base'
objToSearch *
Returns:
- Found value. If no found value returns `undefined`.
Type
*

<static> throwErrorIfEmptyOrNotOfType(prefix, paramName, value, type, suffix)

Throws an error if passed in `value` is empty (0, null, undefined, false, empty {}, or empty []).
Parameters:
Name Type Description
prefix String String to prefix to message.
paramName String Param that expected a non empty value (hint for user).
value * Value to check.
type String | function | undefined | null Type to check against. Optional.
suffix * String to append to message.
Throws:
TypeError
Returns:
Type
void

<static> throwTypeErrorIfEmpty(prefix, paramName, value, type, suffix)

Same as sjl.throwErrorIfEmptyOrNotType but named shorter.
Parameters:
Name Type Description
prefix String
paramName String
value String
type String | function | undefined
suffix String
See:
  • sjl.throwErrorIfEmptyOrNotType for full function description and param descriptions.
Throws:
TypeError
Returns:
Type
void

<static> throwTypeErrorIfNotOfType(prefix, paramName, value, type [, suffix])

Throws a type error if value is not of type and prepends the prefix and paramName/variable-name to the message (removes type checking boilerplate where required).
Parameters:
Name Type Argument Description
prefix String Context name and function name to prefix to error message if it is thrown.
paramName String Param name of the value being passed in.
value * Value to inspect.
type String | function Expected type constructor or constructor name.
suffix String | * <optional>
 A hint to user or a way to fix the error; Message to suffix to error message. Optional.
Throws:
TypeError
Returns:
Type
void

<static> ucaseFirst(str)

Upper cases first character of a string.
Parameters:
Name Type Description
str String
Returns:
Type
String

<static> unset(obj, propName)

Frees references for value and removes the property from `obj` if no references are found and if obj[propName] is configurable.
Parameters:
Name Type Description
obj *
propName String
See:
Returns:
- Whether deletion occurred or not (will always return true if obj[propName] is configurable.
Type
Boolean

<static> valueOrDefault(value, defaultValue, type)

Returns value if it is set and of type else returns `defaultValue`
Parameters:
Name Type Description
value * Value to pass through.
defaultValue * Optional. Value to use as default value if value is not set. Default `null`.
type String | function Optional. Constructor or string representation of type; E.g., String or 'String'

<static> wrapPointer(pointer, min, max)

Wraps a pointer (number) around a bounds (range of two numbers) or returns the next valid pointer depending on direction: E.g., If pointer is less than `min` then returns `max`. If pointer is greater than `max` returns `min`. If pointer is within bounds then returns `pointer`.
Parameters:
Name Type Description
pointer Number
min Number
max Number
Returns:
Type
Number