Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

quixot

alex2stf19ISC1.0.2

the missing javascript library

utils, random, browser fingerprinting, operating system detection, unit testing, html5 notification, smart tv, Tizen, time utils, MVC, enviroment independent, url decoding, logging

readme

quixot-js

the missing javascript library

N|Solid

quixot.js mission is to provide a set of stable cross-platform and cross-engine features

what's new in version 1.0.2
  • safer Logger configuration via URL access key
  • Util.aton method
  • Cache instances lifetime support
  • Event namespace
  • Mingui namespace (full support for browsers, beta-testing java options)
  • Time namespace

quixot : object

Kind: global namespace

quixot.require

require safe support: cached node js requirements
TODO support for http://requirejs.org/

Kind: static property of quixot

quixot.Fingerprint : object

Kind: static namespace of quixot

Fingerprint.data() ⇒ Object

Kind: static method of Fingerprint Returns: Object - the full scanned properties

Fingerprint.identifier() ⇒ String

Kind: static method of Fingerprint Returns: String - The unique fingerprint identifier

Fingerprint.text() ⇒ String

Kind: static method of Fingerprint Returns: String - the text to compose the identifier

Fingerprint.numbers() ⇒ String

Kind: static method of Fingerprint Returns: String - the numbers from text()

quixot.Event : object

Kind: static namespace of quixot

Event.APPOINTMENT_DONE

the name of the event witch is triggered any time an "Event.appoint" is registered

Kind: static property of Event Properties

Type
String

Event.dispatch(name) ⇒ Number

Kind: static method of Event Returns: Number - -1 if error occurs, 0 if no event is registered, > 0 as length of registered events for specified name

Param Type Description
name String required

Event.hasListener(eventName, uidName) ⇒ Boolean

check if a provided listener exist using declared or autogenerated "uidName" from "addListener"

Kind: static method of Event Returns: Boolean - true if the listener exist

Param Type Description
eventName String required
uidName String optional, if provided when listener was added

Event.addListener(eventName, callback, uidName) ⇒ Object

register an event listener

Kind: static method of Event Returns: Object - The current registered event listeners

Param Type Description
eventName String required
callback function required
uidName String an optional unique identifier for the method, to be used when removing the event handler

Example

quixot.addEventListener('whenMyJobIsCompleted', function(){
     console.log('finished');
}, 'myUniqeId');

Event.removeListener(eventName, uidName) ⇒ boolean

remove a registered event listener

Kind: static method of Event Returns: boolean - true if the listener is removed, false if listener does not exist anymore

Param Type Description
eventName String name of the event to be removed
uidName String optional. If not provided default function to string will be used

Event.getAll() ⇒ Object

retrieve all registered events and dispacthers

Kind: static method of Event Returns: Object - containing 2 properties: events and dispatchers

Event.appoint(callback, delay) ⇒ Object

appoint a method. If the environment is browser the appointment will be done via "_raf".
For NodeJS, method "setImmediate" will be used, so the "id" property of the result will be an object.

Kind: static method of Event Returns: Object - containing 2 properties: "type" => a string describing the used method for appointment (mozRequestAnimationFrame|setImmediate|setTimeout|nothing_found) and an "id" => the data return by the method.
This can be used as parameter for "dropAppoint".

Param Type Description
callback function required
delay Number optional, used only if browser has no support for "animationFrame" and a setTimeout will be used.
If not provided, a default value of 30 will be used.

Event.dropAppoint(id) ⇒ Boolean

cancel an appoint. Usage of this method should be avoided, since further changes on "appoint" method might return undroppable callbacks.

Kind: static method of Event Returns: Boolean - false if "id" is not provided or is invalid

Param Type Description
id Object | Number required

Example

var result = quixot.Event.appoint(function(){console.log('hi')}, 0);
quixot.Event.dropAppoint(result.id); //and nothing will happen

quixot.URL : object

Kind: static namespace of quixot

URL.getParams(url) ⇒ Object

retrieve the parameters from a given url

Kind: static method of URL

Param Type
url String

Example

quixot.URL.getParams("test.html?one=1&two=2")
//returns Object {one: 1, two: 2}
// same as:
quixot.URL.decode("test.html?one=1&two=2").params

URL.getDomainFromUrl(url) ⇒ String

Extract the domain from an url.

Kind: static method of URL Returns: String - For any invalid input, default return value is "localhost"

Param Type
url String

Example

quixot.URL.getDomainFromUrl('https://www.mydomain.com/page?args=more');

URL.currentDomain() ⇒ String

returns the current domain

Kind: static method of URL Returns: String - for NodeJS environment default value will be "localhost" Example

quixot.URL.currentDomain(); //produces the same result as:
     quixot.URL.getDomainFromUrl(document.URL)

URL.querify(object) ⇒ String

converts an object to a url query model. Inherited objects are converted into json string.
Lists are converted into csv format

Kind: static method of URL

Param Type Description
object Object object in json format

Example

quixot.URL.querify({a:1, b:[1, 2, 3], g:"text", c:{d:2, f:"some string"}});
//output: 'a=1&b=[1,2,3]&g=text&c={"d":2,"f":"some string"}'

URL.decode(url) ⇒ Object

Kind: static method of URL

Param Type
url String

Example

quixot.URL.decode('http://mydomain/page1/page2/finalPage?arg0=1,2,3&arg1=[1,2,3]');
//protocol => 'http'
//lastPage => 'finalPage'
//parts[2] =>mydomain
//params.arg0[0] => '1'
//params.arg1[0] => '[1'

URL.currentPath() ⇒ String

cross browser support for window.location.pathname. For non browsers environment, empty string is returned

Kind: static method of URL Returns: String - current path name, as defined by window.location.pathname.

URL.currentSearch() ⇒ String

Kind: static method of URL Returns: String - current search name, as defined by window.location.search

URL.currentParams() ⇒ Object

Kind: static method of URL Returns: Object - current url params Example

quixot.URL.currentParams();  retrieve the same data as:
quixot.URL.decode(document.URL).params;

quixot.Logger : object

Kind: static namespace of quixot Example

var myLogger = quixot.Logger.getInstance('TestLogger');
  myLogger.log('info', 'some message');
  myLogger.error('error occured');     //produces the same as
  myLogger.log('error', 'error occured');
  myLogger.info('info data');          //produces the same as
  myLogger.log('info', 'info data');
  quixot.Logger.warn('warning');        //produces the same as
  quixot.Logger.getInstance('quixot').log('warn', '111111');
  quixot.Logger.trace('bla-bla-bla');   ///produces the same as
  quixot.Logger.getInstance('quixot').log('warn', '111111');

Logger.CONSOLE_APPENDER

default console appender function

Kind: static property of Logger Properties

Type
function

Logger.DOM_APPENDER

default html appender function

Kind: static property of Logger Properties

Type
function

Logger.info(message)

info logging using default instance

Kind: static method of Logger

Param Type Description
message Object required

Logger.setDefaultConfig(config)

define default configuration for all newly created logging instances

Kind: static method of Logger

Param Type Description
config Object optional keys

Example

//built in definition:
quixot.Logger.setDefaultConfig({
     appenders: // a list of callbacks
     [ function(name, level, payload){
         //=> where payload has the following structure:
         {
             timestamp: {Date},
             message: {Object|String|Number} -> as called by client,
             stack: {Array} -> stack data
             caller: {Function} -> only if exists

         }
     } ],
     logStack: true
})

Logger.getDefaultConfig() ⇒ Object

Kind: static method of Logger Returns: Object - logger default configuration

Logger.trace(message)

trace logging using default instance

Kind: static method of Logger

Param Type
message Object

Logger.error(message)

error logging using default instance

Kind: static method of Logger

Param Type
message Object

Logger.warn(message)

warn logging using default instance

Kind: static method of Logger

Param Type
message Object

Logger.getLogs() ⇒ Object

Kind: static method of Logger Returns: Object - default instance logs

Logger.getAll() ⇒ Object

Kind: static method of Logger Returns: Object - the logger_container with all logging instances

Logger.getInstance(instancename, config) ⇒ Object

returns a new logger instance

Kind: static method of Logger Returns: Object - the logger_container with all the logger instances

Param Type Description
instancename String required
config Object optional logger configuration

Example

var myLogger = quixot.Logger.getInstance('TestLogger');
myLogger.setConfig(
     {
         appenders: [
                   function(name, level, data){
                         console.log(arguments);
                 }
         ]
   }
)

Logger.setURLAccessKey(name)

set the value for accessing logger configuration from URL. This feature is avaiable only for browser environments.
If is set to false, no configuration can be changed by using URL parameters. The url query opbject can contain only 2 properties: "consoleAppender", to use quixot default console appender as defined by quixot.Logger.CONSOLE_APPENDER and "fileAppender", to use quixot default dom appender as defined by quixot.Logger.DOM_APPENDER.

Kind: static method of Logger

Param Type Description
name String required

Example

//this will allow you to put the following query param into url:
//http://localhost/mypage?customKey={"ALL":{"consoleAppender":true}}
quixot.Logger.setURLAccessKey('customKey');

quixot.Cookie : object

The following namespace has no effect in non-browser environments, although is unit testable

Kind: static namespace of quixot

Cookie.getc(name) ⇒ String

retrieve a cookie with provided name.

Kind: static method of Cookie Returns: String - if the cookie does not exist, result is null

Param Type
name String

Cookie.setc(name, value, expires, path, domain, secure) ⇒ String

create a new cookie

Kind: static method of Cookie Returns: String - the composed cookie string

Param Type Description
name String required name of the cookie
value String required value of the cookie
expires Date | Number expire date. This parameter can also be provided via "Time" namespace
path String optional
domain String optional
secure Boolean optional

Example

quixot.Cookie.setc(
     'test-cookie', 'test-cookie-value',
     quixot.Time.interval(1, 'month'),
     'path', 'domain', true);
 //based on client timestamp, might return
 //"test-cookie=test-cookie-value; expires=Tue, 03 Jan 2017 10:41:31 GMT; path=path; domain=domain; secure"

Cookie.drop(name, path, domain) ⇒ String

delete a cookie

Kind: static method of Cookie Returns: String - empty string

Param Type Description
name String required
path String optional
domain String optional

quixot.Util : object

Kind: static namespace of quixot

Util.incr ⇒ Number

increments an unique number (old value is cached)

Kind: static property of Util Returns: Number - positive integer

Param Type Description
asfloat Boolean optional

Example

quixot.Util.incr(true); // 30.07000000000001
quixot.Util.incr();    // 31

Util.randNr ⇒ Number

if no parameters are provided a currentTimestamp value will be returned. id method is called twice in less than a milisecond, a quixot.Util.incr() value will be returned to make sure return values are avoided

Kind: static property of Util Returns: Number - float

Param Description
min limit range if "max" is not provided
max limit range

Example

quixot.Util.randNr(3); // will generate numbers betwen 0 and 3, like 0.6573690931544247
quixot.Util.randNr(2, 4); // will generate numbers betwen 2 and 4, like 2.3124963172024833
quixot.Util.randNr(-5); // will generate numbers betwen -5 and 0, like -4.3664502906423195

Util.randInt ⇒ Number

same usage as "randNr", only it returns an integer

Kind: static property of Util Returns: Number - float

Param
min
max

Util.atos(data, mapping, zval) ⇒ String

encode any type of javascript data type (specially numbers) to string

Kind: static method of Util

Param Type Description
data Number | String | Date | Object | Array | function required
mapping String optional a string whose characters will be used for encoding
zval Number the value for 0, used for encoding duplicated numeric characters

Example

quixot.atos(123456789); // "mdefghij"
 quixot.atos(000000); // "a"
 quixot.atos('000000'); // "abcdef"
 quixot.atos('000000', '!@#$%^&*()+='); // "!@#$%^"

Util.aton(input, separator) ⇒ String

converts any type of data into a string containing only numeric characters

Kind: static method of Util Returns: String - a string containing only numeric characters

Param Type Description
input String | Number | Array | Object | Date
separator String a separator for numbers

Example

quixot.Util.aton('\""', '__'); // "54__54"
 quixot.Util.aton(1234+'bcd'); //"1234234"

Util.makeDomId(prefix) ⇒ String

generates an unique id that begins with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9])

Kind: static method of Util

Param Type Description
prefix String optional, a prefix to be appended at the begging of the string

Util.randStr(mapping) ⇒ String

generates a random string

Kind: static method of Util Returns: String - a random string

Param Type Description
mapping String a string whose characters will be used for encoding.
Same usage as for "atos" method

quixot.Cache : object

supports browser && nodejs

Kind: static namespace of quixot

Cache.getInstance(instanceName, lifetime) ⇒ Object

caching instances factory

Kind: static method of Cache Returns: Object - a new or an existing caching instance

Param Type
instanceName String
lifetime Number

Cache.put(key, value) ⇒ Boolean

put item inside default cache instance

Kind: static method of Cache Returns: Boolean - true if cache is populated

Param Type
key String
value String | Number | Array | Object

quixot.Env : object

contains data related to enviroment:

Kind: static namespace of quixot Example

quixot.Env.jsEngine.isBrowser; //true if script is running in browser
quixot.Env.jsEngine.isNodeJs;  //true if script is running in node js
quixot.Env.javaEnabled;        //true if java is enabled in browser,
                                            // or if a path to JAVA_HOME exist is operating system enviroment
quixot.Env.tempDir             //path to operating system temporary directory
quixot.Env.homeDir             //path to operating system user home directory
quixot.Env.javaPath            //path to java binary (java.exe || java)

quixot.System : object

system information (browser|nodejs)

Kind: static namespace of quixot

System.os : object

operating system info

Kind: static namespace of System Example

quixot.System.os.name; // returns the operating system generic name
                                  // nodejs support is provided via os.type if exists otherwise via
                                  // os.platform. Result may be "Windows|Mac|Linux"
           quixot.System.version  // returns operatinng system version
                                  // result may vary based on scanned features
                                  // browsers will return data based on user agent, nodejs
                                  // or other engines may provide content via 'os.release'

quixot.Browser : object

browser information< br/>

Kind: static namespace of quixot Example

quixot.Browser.name; (Chrome|Firefox|Explorer|Opera|iCab|rekonq|Midori|Arora|Stainless|Epiphany|K-Meleon|Camino|Maxthon|SeaMonkey|Edge|OmniWeb|Apple|KDE|Netscape|MSIE|Gecko|Mozilla|Tizen)
 quixot.Browser.version;

quixot.Sancho : object

the unit testing namespace.

Kind: static namespace of quixot

Sancho.equals() ⇒ Boolean

For NodeJS environment, built-in 'assert' library will be used.

Kind: static method of Sancho Returns: Boolean - true if test is passed Example

quixot.Sancho.equals(1, 1);

Sancho.noDuplicates(list) ⇒ Boolean

verify if a list contains no duplicates

Kind: static method of Sancho

Param Type
list Array

Example

quixot.Sancho.noDuplicates([1, 8, 3, 4, 9, 7, 2 ])

quixot.Mingui : object

minimal graphic user interface components designed to run inside any type of enviroment and provide if possible native behaviour on visual components

Kind: static namespace of quixot

Mingui.notify(title, text, picture, lifetime, success, failure, onclick, onclose) ⇒ Boolean | Object

for browsers the notify action will first try create a native html5 notification if domain protocol is "http" or "https".
Second second approach will be to create a pop-up window. Please remember that second tryout will also apply if user native notifications are blocked from settings.
Finally, if the pop-up window is blocked, a simple html notification will be added to current document, styled by default with operating system colors.

For nodejs enviroments if java path is detected a spawned process wil start. (required java 1.8, this feature is still under developpement)

Kind: static method of Mingui Returns: Boolean | Object - false if notification fails to be displayed due to known reasons, an object with "remove()" method.

Param Type Description
title String
text String
picture String
lifetime Number
success function
failure function although the method returns false due to known reasons, this callback is safe to use. For example, native html5 notification require user approval. In this case method will return false, but if user press "Allow" the "failure" callback will never be called
onclick function Attention!!! This callback may run without context in some implementations.
onclose function Attention!!! This callback may run without context in some implementations.

quixot.Time : object

Time utils

Kind: static namespace of quixot

Time.interval(count, type) ⇒ Number

Kind: static method of Time Returns: Number - the value in milliseconds of required parameters

Param Type Description
count Number required
type String required, one of (nano

Example

quixot.Time.interval(4, 'year'); // returns 126144000000

quixot.Dulcineea : object

Kind: static namespace of quixot

Dulcineea.compiler : object

Kind: static namespace of Dulcineea

compiler.execute(caller, jsonData) ⇒ Object

executes a call for a JSON formatted object

Kind: static method of compiler

Param Type
caller String
jsonData Object | JSON

Example

quixot.Dulcineea.compiler.execute('a.b', {a:{b: 1}});
//returns "1"

compiler.extract(input) ⇒ Array

converts a string into a list of valid JSON callers

Kind: static method of compiler

Param Type
input String

Example

quixot.Dulcineea.compiler.extract('a.b.c'); //returns ['a', 'b', 'c']
quixot.Dulcineea.compiler.extract('a.b[0]c["data"]'); //returns ["a", "b", "0", "c", "'data'"]
realtime browser customer support (use case sample)

  • Create a urlAccessKey:

    quixot.Logger.setURLAccessKey('mySecretKey');

  • Create a logger instance with no appenders and use it in your webpage:

    var log4CustomerSupport = quixot.Logger.getInstance('log4CustomerSupport', {consoleAppender: false, fileAppender: false});
log4CustomerSupport.trace('this log happens client side');
log4CustomerSupport.trace('and client could see stored data');
log4CustomerSupport.trace('by calling in console');
log4CustomerSupport.trace('quixot.Logger.getInstance(\'log4CustomerSupport\').getLogs().trace');

  • ask your customer to access the webpage using the following query param: http://domain/custompage?mySecretKey={"log4CustomerSupport":{"fileAppender":true, "consoleAppender":true}} to view all logs of that specific logger or use mySecretKey={"log4CustomerSupport":{"fileAppender":true} } to display on screen only info messages for log4CustomerSupport. You can also use mySecretKey={"ALL":{"fileAppender":true}} to view all logs

browser scanned features in fingerprint detection
  • abreviated time zone
  • Math functions and static values
  • computer name (for older IE versions retrieved via ActiveX)
  • installed plugins and supported mime types based on the recursive depth scan
  • webgl support, version , vendor, renderer
  • empty canvas dataUrl, both .png and .jpeg format
  • chrome, netscape specific properties
  • screen info (width, height, colorDepth, pixelRation)
  • browser supported css properties
  • unique property names of supported javascript features (check the .evilUtors) property
  • the evilUtors are a set of evaluable strings meant to return sensitive information about browser and javascript engine