Repository files navigation

various classification, validation and utility functions for JavaScript and TypeScript

From time to time, it's necessary to classify and/or validate the values of user inputs, data read from input streams (like files or network connections) or arguments passed as part of a function call. While TypeScript type annotations already eliminate the need for many of these tests, there still exist lots of interfaces to the outer (non-TypeScript) world where value checking remains important.

These situations are, what thejavascript-interface-library has been made for.

NPM users: please consider theGithub README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Just a small note: if you like this module and plan to use it, consider "starring" this repository (you will find the "Star" button on the top right of this page), so that I know which of my repositories to take most care of.

javascript-interface-library may be used as an ECMAScript module (ESM), a CommonJS or AMD module or from a global variable.

You may either install the package into your build environment usingNPM with the command

npm install javascript-interface-library

or load the plain script file directly

<scriptsrc="https://unpkg.com/javascript-interface-library"></script>

How to access the package depends on the type of module you prefer

• ESM (or Svelte):import { ValueIsListSatisfying, ValueIsOrdinal } from 'javascript-interface-library'
• CommonJS:const JIL = require('javascript-interface-library')
• AMD:require(['javascript-interface-library'], (JIL) => {...})

Alternatively, you may access the global variableJIL directly.

Note for ECMAScript module users: all module functions and values are exported individually, thus allowing your bundler to perform some "tree-shaking" in order to include actually used functions or values (together with their dependencies) only.

For Svelte, it is recommended to import the package in a module context. From then on, its exports may be used as usual:

<scriptcontext="module">import{ValueIsListSatisfying,ValueIsOrdinal}from'javascript-interface-library'</script><script>console.log(ValueIsListSatisfying([1,2,3,4],ValueIsOrdinal,1,10))</script>

Let's assume that you already "required" or "imported" (or simply loaded) the module according to your local environment. In that case, you may use it as follows:

console.log(JIL.ValueIsListSatisfying([1,2,3,4],JIL.ValueIsOrdinal,1,10))

As shown above, the individual functions and values may either be accessed directly (when used as an ESM) or by prefixing them with their namespaceJIL (in all other cases). The following documentation lists all module contents without namespace prefix only, and the shown function signatures are those used by TypeScript.

The JavaScriptObject class provides a few useful functions (or "static methods") for inspecting or converting a given object. Unfortunately, these functions are often used without prior checking whether the given target object actually inherits from theObject protoype or was built usingObject.create(null) - and will fail whenever such a "vanilla" object is given.

JIL therefore contains the following functions which mimic their counterparts from theObject class, but succeed even if the given target object is "vanilla".

• Object_hasOwnProperty (Value:Object, PropertyName:string):boolean
  returnstrue if the givenValue contains a property with the namePropertyName as its own property - orfalse otherwise. This function mimics the JavaScript methodObject.hasOwnProperty
• Object_isPrototypeOf (Value:Object, Candidate:any):boolean
  returnstrue if the givenValue exists in the prototype chain of a givenCandidate - orfalse otherwise. This function mimics the JavaScript methodObject.isPrototypeOf
• Object_propertyIsEnumerable (Value:Object, PropertyName:string):boolean
  returnstrue if the givenValue contains a property with the namePropertyName as its own property and that one is enumerable - orfalse otherwise. This function mimics the JavaScript methodObject.propertyIsEnumerable
• Object_toString (Value:Object):string
  returns a string which represents the givenValue. This function mimics the JavaScript methodObject.toString
• Object_toLocaleString (Value:Object):string
  returns a locale-specific string which represents the givenValue. This function mimics the JavaScript methodObject.toLocaleString
• Object_valueOf (Value:Object):any
  returns the primitive value of the givenValue object. This function mimics the JavaScript methodObject.valueOf

The following functions check whether a given argument satisfies a certain constraint (e.g., belongs to a certain category) and return eithertrue (if the constrain is met) or false otherwise.

• ValueExists (Value:any):boolean
  returnstrue if the givenValue exists, i.e., if it differs from bothnull andundefined - orfalse otherwise
• ValueIsMissing (Value:any):boolean
  returnstrue if the givenValue is eithernull orundefined - orfalse otherwise
   
  
• ValueIsBoolean (Value:any):boolean
  returnstrue if the givenValue is either a primitive boolean value or an instance ofBoolean - orfalse otherwise
   
  
• ValueIsNumber (Value:any):boolean
  returnstrue if the givenValue is either a primitive numeric value or an instance ofNumber - orfalse otherwise
• ValueIsFiniteNumber (Value:any):boolean
  returnstrue if the givenValue is a finite number, i.e. a number which is notNaN and whose value is greater than negative and smaller than positive infinity - orfalse otherwise
• ValueIsNaN (Value:any):boolean
  returnstrue if the givenValue isNaN - orfalse otherwise
• ValueIsNumberInRange (Value:any, minValue?:number, maxValue?:number, withMin:boolean = true, withMax:boolean = true):boolean
  returnstrue if the givenValue is a number whose value is within the range given byminValue andmaxValue - orfalse otherwise.minValue is optional and defaults to negative infinity,maxValue is also optional but defaults to positive infinity. Whentrue,withMin indicates thatValue may also beequal to the lower end of the given range, otherwise it must just begreater than the lower limit. Whentrue,withMax indicates thatValue may also beequal to the upper end of the given range, otherwise it must just belower than the upper limit
• ValueIsInteger (Value:any):boolean
  returnstrue if the givenValue is a whole number - orfalse otherwise
• ValueIsIntegerInRange (Value:any, minValue?:number, maxValue?:number):boolean
  returnstrue if the givenValue is a whole number whose value is within the range given byminValue andmaxValue - orfalse otherwise.minValue is optional and defaults to negative infinity,maxValue is also optional but defaults to positive infinity
• ValueIsOrdinal (Value:any):boolean
  returnstrue if the givenValue is a whole number greater than or equal to zero - orfalse otherwise
• ValueIsCardinal (Value:any):boolean
  returnstrue if the givenValue is a whole number greater than or equal to one - orfalse otherwise
   
  
• ValueIsString (Value:any):boolean
  returnstrue if the givenValue is either a primitive literal value or an instance ofString - orfalse otherwise
• ValueIsEmptyString (Value:any):boolean
  returnstrue if the givenValue is a string without any characters or with some content that consists of white-space characters only - orfalse otherwise
• ValueIsNonEmptyString (Value:any):boolean
  returnstrue if the givenValue is a string with some content that does not just consist of white-space characters - orfalse otherwise
• ValueIsStringMatching (Value:any, Pattern:RegExp):boolean
  returnstrue if the givenValue is a string whose content matches the given regular expressionPattern - orfalse otherwise
• ValueIsText (Value:any):boolean
  returnstrue if the givenValue is a string containing "ordinary" text only (i.e., a string which lacks any kind of control characters except \n or \r) - orfalse otherwise
• ValueIsTextline (Value:any):boolean
  returnstrue if the givenValue is a string containing a single line of "ordinary" text only (i.e., a string which lacks any kind of control characters) - orfalse otherwise
   
  
• ValueIsFunction (Value:any):boolean
  returnstrue if the givenValue is a JavaScript function - orfalse otherwise
• ValueIsAnonymousFunction (Value:any):boolean
  returnstrue if the givenValue is an anonymous JavaScript function (i.e., a function without aname property) - orfalse otherwise
• ValueIsNamedFunction (Value:any):boolean
  returnstrue if the givenValue is a "named" JavaScript function (i.e., a function with a non-emptyname property) - orfalse otherwise
• ValueIsNativeFunction (Value:any):boolean
  returnstrue if the givenValue is a native JavaScript function - orfalse otherwise
• ValueIsScriptedFunction (Value:any):boolean
  returnstrue if the givenValue is a scripted JavaScript function - orfalse otherwise
   
  
• ValueIsObject (Value:any):boolean
  returnstrue if the givenValue is a JavaScript object (and notnull) - orfalse otherwise
• ValueIsPlainObject (Value:any):boolean
  returnstrue if the givenValue is a JavaScript object (different fromnull) which directly inherits fromObject (such as a Javascript object literal) - orfalse otherwise
• ValueIsVanillaObject (Value:any):boolean
  returnstrue if the givenValue is a JavaScript object which has been built usingObject.create(null) - orfalse otherwise
   
  
• ValueIsArray (Value:any):boolean
  returnstrue if the givenValue is anArray instance - orfalse otherwise. If given,minLength specifies the minimal required list length andmaxLength specifies the maximal allowed list length
• ValueIsList (Value:any, minLength?:number, maxLength?:number):boolean
  returnstrue if the givenValue is a "dense" JavaScript array (i.e., an array whose indices 0...n-1 all exist, where n is thelength of the given array) - orfalse otherwise
• ValueIsListSatisfying (Value:any, Validator:Function, minLength?:number, maxLength?:number):boolean
  returnstrue if the givenValue is a "dense" JavaScript array, whose elements all pass the givenValidator - orfalse otherwise.Validator is a function which receives a list element as its sole argument and returnstrue if the given element is "valid" orfalse otherwise. If given,minLength specifies the minimal required list length andmaxLength specifies the maximal allowed list length
   
  
• ValueIsInstanceOf (Value:any, Constructor:Function):boolean
  returnstrue if the givenValue was constructed using the givenConstructor function - orfalse otherwise
• ValueInheritsFrom (Value:any, Prototype:Object):boolean
  returnstrue ifPrototype exists in the prototype chain of the givenValue - orfalse otherwise
   
  
• ValueIsDate (Value:any):boolean
  returnstrue if the givenValue is aDate instance - orfalse otherwise
• ValueIsError (Value:any):boolean
  returnstrue if the givenValue is anError instance - orfalse otherwise
• ValueIsPromise (Value:any):boolean
  returnstrue if the givenValue is a "Promise", i.e., an object with a property namedthen which contains a function - orfalse otherwise
• ValueIsRegExp (Value:any):boolean
  returnstrue if the givenValue is aRegExp instance - orfalse otherwise
   
  
• ValueIsOneOf (Value:any, ValueList:any[]):boolean
  returnstrue if the givenValue equals (at least) one of the items found in the givenValueList - orfalse otherwise. Equality is checked using the JavaScript=== operator
   
  
• ValueIsColor (Value:any):boolean
  returnstrue if the givenValue is a string containing a syntactically valid CSS color specification - orfalse otherwise
• ValueIsEMailAddress (Value:any):boolean
  returnstrue if the givenValue is a string containing a syntactically valid EMail address - orfalse otherwise
• ValueIsURL (Value:any):boolean
  returnstrue if the givenValue is a string containing a syntactically valid URL - orfalse otherwise

The following functions check whether a given argument satisfies a certain constraint (e.g., belongs to a certain category) and either return the given argument (sometimes after some normalization), if the constrain is met, or throw an error otherwise.

Unless stated otherwise, these functions exist in four different "flavours", as indicated by their name prefixes:

• allowXXX
  validates the given argument and returns it, if it is either missing (i.e., equalsnull orundefined) or meets the condition defined forXXX - or throws an exception otherwise
• allwedXXX
  synonym forallowXXX, looks better when used as an expression
• expectXXX
  validates the given argument and returns it, if it exists (i.e., differs both fromnull andundefined) and meets the condition defined forXXX - or throws an exception otherwise
• expectedXXX
  synonym forexpectXXX, looks better when used as an expression

For the sake of clarity, however, only the first "flavour" (namelyallowXXX) is shown in the list below (provided that this flavour actually exists).

• expectValue (Description:string, Argument:any):any
  checks if the givenArgument exists (i.e., if it differs from bothnull andundefined). If this is the case, the function returns the givenArgument, otherwise an error with the message"no ${Description} given" is thrown, which uses the givenDescription argument. Please note: this function does not exist in the flavoursallowXXX orallowedXXX
   
  
• allowBoolean (Description:string, Argument:any):boolean|null|undefined
  checks if the givenArgument (if it exists) is either a primitive boolean value or an instance ofBoolean. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error with the message"the given ${Description} is no valid boolean value" is thrown, which uses the givenDescription
   
  
• allowNumber (Description:string, Argument:any):number|null|undefined
  checks if the givenArgument (if it exists) is either a primitive numeric value or an instance ofNumber. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error with the message"the given ${Description} is no valid numeric value" is thrown, which uses the givenDescription
• allowFiniteNumber (Description:string, Argument:any):number|null|undefined
  checks if the givenArgument (if it exists) is a finite number, i.e. a number which is notNaN and whose value is greater than negative and smaller than positive infinity. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowNaN (Description:string, Argument:any):number|null|undefined
  checks if the givenArgument (if it exists) isNaN. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowNumberInRange (Description:string, Argument:any, minValue?:number, maxValue?:number, withMin?:boolean, withMax?:boolean):number|null|undefined
  checks if the givenArgument (if it exists) is a number whose value is within the range given byminValue andmaxValue. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription.minValue is optional and defaults to negative infinity,maxValue is also optional but defaults to positive infinity. When true,withMin indicates thatValue may also beequal to the lower end of the given range, otherwise it must just begreater than the lower limit. When true,withMax indicates thatValue may also beequal to the upper end of the given range, otherwise it must just belower than the upper limit
• allowInteger (Description:string, Argument:any):number|null|undefined
  checks if the givenArgument (if it exists) is a whole number. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowIntegerInRange (Description:string, Argument:any, minValue?:number, maxValue?:number):number|null|undefined
  checks if the givenArgument (if it exists) is a whole number whose value is within the range given byminValue andmaxValue. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription.minValue is optional and defaults to negative infinity,maxValue is also optional but defaults to positive infinity
• allowOrdinal (Description:string, Argument:any):number|null|undefined
  checks if the givenArgument (if it exists) is a whole number greater than or equal to zero. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowCardinal (Description:string, Argument:any):number|null|undefined
  checks if the givenArgument (if it exists) is a whole number greater than or equal to one. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
   
  
• allowString (Description:string, Argument:any):string|null|undefined
  checks if the givenArgument (if it exists) is either a primitive literal value or an instance ofString. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error with the message"the given ${Description} is no valid literal string" is thrown, which uses the givenDescription
• allowNonEmptyString (Description:string, Argument:any):string|null|undefined
  checks if the givenArgument (if it exists) is a string with some content that does not just consist of white-space characters. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowStringMatching (Description:string, Argument:any, Pattern:RegExp):string|null|undefined
  checks if the givenArgument (if it exists) is a string whose content matches the given regular expressionPattern. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowText (Description:string, Argument:any):string|null|undefined
  checks if the givenArgument (if it exists) is a string containing "ordinary" text only (i.e., a string which lacks any kind of control characters except \n or \r). If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowTextline (Description:string, Argument:any):string|null|undefined
  checks if the givenArgument (if it exists) is a string containing a single line of "ordinary" text only (i.e., a string which lacks any kind of control characters). If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
   
  
• allowFunction (Description:string, Argument:any):Function|null|undefined
  checks if the givenArgument (if it exists) is a JavaScript function. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowAnonymousFunction (Description:string, Argument:any):Function|null|undefined
  checks if the givenArgument (if it exists) is an anonymous JavaScript function (i.e., a function without a name property). If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowNamedFunction (Description:string, Argument:any):Function|null|undefined
  checks if the givenArgument (if it exists) is a "named" JavaScript function (i.e., a function with a non-emptyname property). If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowNativeFunction (Description:string, Argument:any):Function|null|undefined
  checks if the givenArgument (if it exists) is a native JavaScript function. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowScriptedFunction (Description:string, Argument:any):Function|null|undefined
  checks if the givenArgument (if it exists) is a scripted JavaScript function. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
   
  
• allowObject (Description:string, Argument:any):any|null|undefined
  checks if the givenArgument (if it exists) is a JavaScript object (and notnull). If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowPlainObject (Description:string, Argument:any):any|null|undefined
  checks if the givenArgument (if it exists) is a JavaScript object (different fromnull) which directly inherits fromObject (such as a Javascript object literal). If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowVanillaObject (Description:string, Argument:any):any|null|undefined
  checks if the givenArgument (if it exists) is a JavaScript object which has been built usingObject.create(null). If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
   
  
• allowArray (Description:string, Argument:any):any[]|null|undefined
  checks if the givenArgument (if it exists) is anArray instance. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowList (Description:string, Argument:any, Expectation?:string,minLength?:number, maxLength?:number):any[]|null|undefined
  checks if the givenArgument (if it exists) is a "dense" JavaScript array (i.e., an array whose indices 0...n-1 all exist, where n is the length of the given array). If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription. If given,minLength specifies the minimal required list length andmaxLength specifies the maximal allowed list length
• allowListSatisfying (Description:string, Argument:any, Validator:(Value:any) => boolean,Expectation?:string, minLength?:number, maxLength?:number):any[]|null|undefined
  checks if the givenArgument (if it exists) is a "dense" JavaScript array, whose elements all pass the givenValidator. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription.Validator is a function which receives a list element as its sole argument and returnstrue if the given element is "valid" orfalse otherwise. If given,minLength specifies the minimal required list length andmaxLength specifies the maximal allowed list length
   
  
• allowInstanceOf (Description:string, Argument:any, constructor:Function, Expectation:string):any|null|undefined
  checks if the givenArgument (if it exists) was constructed using the givenConstructor function. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowValueInheritingFrom (Description:string, Argument:any, prototype:any, Expectation:string):any|null|undefined
  checks ifPrototype exists in the prototype chain of the givenArgument (if that exists). If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
   
  
• allowDate (Description:string, Argument:any):Date|null|undefined
  checks if the givenArgument (if it exists) is aDate instance. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowError (Description:string, Argument:any):Error|null|undefined
  checks if the givenArgument (if it exists) is anError instance. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowPromise (Description:string, Argument:any):any|null|undefined
  checks if the givenArgument (if it exists) is a "Promise", i.e., an object with a property namedthen which contains a function. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowRegExp (Description:string, Argument:any):RegExp|null|undefined
  checks if the givenArgument (if it exists) is aRegExp instance. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription
   
  
• allowOneOf (Description:string, Argument:any, ValueList:any[]):any|null|undefined
  checks if the givenArgument (if it exists) equals (at least) one of the items found in the givenValueList. If this is the case (orArgument is missing), the function returns the givenArgument, otherwise an error is thrown whose message contains the givenDescription. Equality is checked using the JavaScript=== operator
   
  
• allowColor (Description:string, Argument:any):string|null|undefined
  checks if the givenArgument (if it exists) is a string containing a syntactically valid CSS color specification. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowEMailAddress (Description:string, Argument:any):string|null|undefined
  checks if the givenArgument (if it exists) is a string containing a syntactically valid EMail address. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription
• allowURL (Description:string, Argument:any):string|null|undefined
  checks if the givenArgument (if it exists) is a string containing a syntactically valid URL. If this is the case (orArgument is missing), the function returns the primitive value of the givenArgument, otherwise an error is thrown whose message contains the givenDescription

• throwableError (Message:string):Error
  this function has been provided in order to simplify the construction of "named"Error instances: if the givenMessage starts with a JavaScript identifier followed by a colon, identifier and colon are stripped apart and the identifier is used as thename property of a newly constructedError instance for the remaining part ofMessage. Otherwise, this function is equivalent tonew Error(Message)
• throwError (Message:string):never
  this function has been provided in order to simplify throwing "named"Error instances: if the givenMessage starts with a JavaScript identifier followed by a colon, identifier and colon are stripped apart and the identifier is used as thename property of a newly constructedError instance for the remaining part ofMessage. Otherwise, this function is equivalent tothrow new Error(Message)
   
  
• ObjectMergedWith (TargetObject:object, ...otherObjectList:object[]):object
Object.assign can not be used to copy properties with getters and setters from one object into another - this is whatObjectMergedWith is good for: it copies the descriptors of allown properties from any object found inotherObjectList into the givenTargetObject and also returns that object as its function result. Any descriptor already existing for a given property inTargetObject will be overwritten
   
  
• constrained (Value:number, Minimum:number = -Infinity, Maximum:number = Infinity):number
  limits the givenValue to the range specified byMinimum andMaximum - i.e., the function returnsMinimum ifValue is less than (or equal to)Minimum,Maximum ifValue is greater than (or equal to)Maximum, orValue itself otherwise.Minimum andMaximum are optional and default to-Infinity or+Infinity, resp.
   
  
• escaped (Text:string):string
  returns a copy of the givenText in which all control characters have been replaced by their corresponding escape sequences
• unescaped (Text:string):string
  returns a copy of the givenText in which all character escape sequences have been replaced by their corresponding (control) characters
   
  
• quotable (Text:string, Quote:'"' | "'" = '"'):string
  returns a copy of the givenText in which all control characters andQuotes have been replaced by their corresponding escape sequences. The outcome of this function may, f.e., used to construct literal values in JSON files.Quote is optional and defaults to the double-quotes character
• quoted (Text:string, Quote:'"' | "'" = '"'):string
  returns a copy of the givenText (embedded within a pair ofQuotes) in which all control characters andQuotes have been replaced by their corresponding escape sequences. The outcome of this function may, f.e., used to construct literal values in JSON files.Quote is optional and defaults to the double-quotes character
   
  
• HTMLsafe (Argument:string, EOLReplacement?:string):string
  returns a copy of the givenArgument in which all control characters (except\n) and characters with a special meaning for HTML have been replaced by their corresponding HTML entities. Any linefeed characters (\n) will be replaced by the givenEOLReplacement string - specification ofEOLReplacement is optional and defaults to<br/>
• MarkDownSafe (Argument:string, EOLReplacement?:string):string
  returns a copy of the givenArgument in which all control characters (except\n) and characters with a special meaning for (HTML and) Markdown have been replaced by their corresponding HTML entities. Any linefeed characters (\n) will be replaced by the givenEOLReplacement string - specification ofEOLReplacement is optional and defaults to<br/>
   
  
• ValuesDiffer (thisValue:any, otherValue:any, Mode?:'by-value'|'by-reference'|undefined):boolean
  returnstrue ifthisValue differs fromotherValue - orfalse otherwise. Equality is checked by inspection, i.e.,null,undefined, booleans, strings and functions are checked using the JavaScript=== operator, comparison of numbers also takes care ofNaN and a potential deviation byNumber.EPSILON and objects or arrays are (by default) compared element by element. If the optionalMode is set toby-reference, Objects are always compared by reference, if set toby-value, instances ofBoolean,Number andString are always compared by their primitive value
• ValuesAreEqual (thisValue:any, otherValue:any, Mode?:'by-value'|'by-reference'|undefined):boolean
  returnstrue ifthisValue equals tootherValue - orfalse otherwise. Equality is checked by inspection, i.e.,null,undefined, booleans, strings and functions are checked using the JavaScript=== operator, comparison of numbers also takes care ofNaN and a potential deviation byNumber.EPSILON and objects or arrays are (by default) compared element by element. If the optionalMode is set toby-reference, Objects are always compared by reference, if set toby-value, instances ofBoolean,Number andString are always compared by their primitive value
   
  
• ObjectIsEmpty (Candidate:any):boolean
  returns true if the givenCandidate is an empty object (i.e., an object without anyown properties) - orfalse otherwise
• ObjectIsNotEmpty (Candidate:any):boolean
  returns true if the givenCandidate is a non-empty empty object (i.e., an object with at least oneown property) - orfalse otherwise
• StringIsEmpty (Candidate:string):boolean
  returns true if the givenCandidate is an empty string (i.e., a string which either contains no characters at all or only whitespace characters) - orfalse otherwise
• StringIsNotEmpty (Candidate:string):boolean
  returns true if the givenCandidate is a non-empty string (i.e., a string which contains one or more characters and not all of them are whitespace characters) - orfalse otherwise
   
  
• ValidatorForClassifier (Classifier:(Value:any) => boolean, NilIsAcceptable:boolean, Expectation:string):Function
  this function is used internally to construct many of the offered argument validation functions: it returns a new function which takes aDescription and anArgument, uses the givenClassifier to check ifArgument belongs to the expected category of values and - if it does - returns the primitive value of the givenArgument. Otherwise, an error message is constructed, which includes the givenDescription and complains about the given value not being a "valid ${Expectation}" - i.e.,Expectation should describe the expected kind of argument. If set totrue,NilIsAcceptable indicates thatArgument may be missing (i.e.,null orundefined), otherwise the givenArgument is mandatory.
   
  Important Note: if you plan to develop a library which may be "tree-shaked" by application bundlers (such as WebPack and Rollup) and export functions built withValidatorForClassifier, you should mark all invocations ofValidatorForClassifier as "free of side-effects" by prepending them with/*#__PURE__*/ - otherwise those invocations will remain in the bundled code even if you don't use the corresponding exports
• validatedArgument (Description:string, Argument:any, ValueIsValid:(Value:any) => boolean,NilIsAcceptable:boolean, Expectation:string):any|null|undefined
  this function is used internally to actually validate a givenArgument and throw anError with a message containing the givenDescription, if not.ValueIsValid is the function used checkArgument and should returntrue ifArgument is "valid" orfalse if not. If set totrue,NilIsAcceptable indicates thatArgument may be missing (i.e.,null orundefined), otherwise the givenArgument is mandatory. If validation fails, an error message is constructed, which includes the givenDescription and complains about the given value not being a "valid ${Expectation}" - i.e.,Expectation should describe the expected kind of argument
   
  
• FunctionWithName (originalFunction:Function, desiredName:string|String):Function
  this function is used internally to convert an anonymous functionoriginalFunction into a named one - either by setting thedesiredName for the existing function or by wrapping it into a new function with that name

• ColorSet
  is an object, whose keys are the names of all colors known by (and built into) a web browser and the corresponding values are the RGBA specifications of these colors
• HexColor (Color:string):string
  converts a givenColor string (which must be a valid CSS color specification) into the long hexadecimal format (#rrggbbaa)
• shortHexColor (Color:string):string
  converts a givenColor string (which must be a valid CSS color specification) into the short hexadecimal format (#rrggbb) - such a format must be used for HTML input elements of type "color"
• RGBAColor (Color:string):string
  converts a givenColor string (which must be a valid CSS color specification) into the RGBA format (rgba(r,g,b,a))

You may easily build this package yourself.

Just installNPM according to the instructions for your platform and follow these steps:

1. either clone this repository usinggit ordownload a ZIP archive with its contents to your disk and unpack it there
2. open a shell and navigate to the root directory of this repository
3. runnpm install in order to install the complete build environment
4. executenpm run build to create a new build

If you made some changes to the source code, you may also try

npm run agadoo

in order to check if the result is still tree-shakable.

You may also look into the author'sbuild-configuration-study for a general description of his build environment.

MIT License