valango / val-front

simple front-end code helpers (not to be published yet)

val-front

Simple code snippets for making front-end coding more fun.

Note: this project is just a collection of sketches. Published packages vue-proper and assert-fine both emerged from here.

The package in intended for using with ES5+ source code. It has the following parts:

• assert - enables debugger breakpoints for assertions;
• debug - convenience wrapper around popular debug package;
• mixin - Vue.js mix-in for cleaner and safer code;
• Own - ES5 base class for more maintainable code;
• performance - a simple API for code profiling;
• vueName - get Vue.js comnponent instance name.

These parts can be loaded individually, like import dbg from 'val-front/debug'
or together, like import {assert, mixin} frpm 'val-front'

Assertions

import { assert } from 'val-front'

//  You can this to find out what causes seemingly random assertions.
assert.callback((...args) => {
  //  Great place for debugger breakpoint!
})

assert( someCondition, ... )  // Optional extra arguments for console.assert() 

On success, assert returns its first argument value. Otherwise, an exception with message 'AssertionError' is thrown after callback (if set). In non-production mode, console.assert() is called before throwing exception, so there will be some useful information on the console.

Debugging

Debugging machinery is based on debug NPM package and is available only in development mode. In production mode all it's API methods will be just empty functions. Here are simple examples:

Debugging plain javascript code:

  const debug = require('val-front/debug')('main.js')

  debug('try(%d, %o)', 1, 2, 3)  // main.js try(1, 2) +0ms 3

Debugging class instances:

  import Own from 'val-front/Own'

  class A extends Own {}

  new A().debug('yay')  //  A#1 yay +0ms

Debugging Vue.js components: Just make sure your component has mixin imported from 'val-front' - your component instance will have debug() method.

Fine control of debugging

By default, call to debug() method will generate console output. It may generate quite a mess on console, as your code grows.

To be more selective, you may do the following:

1. assign a mask to debug.enabled in your app root module:
   require('val-front').debug.enabled = '*, -proven*';
2. use DEBUG environment variable (may be a bit less convenient);
3. explicitly set debugOn instance variable to true or false;
4. in plain javascript: const debug = require('val-front').debug('main.js', trueOrFalse)

Tricks #2, #3 will override the effects of #1, #2.

Own baseclass

constructor Own(className= : {string})

This baseclass provides API for safer code and some diagnostic support as well:

• method debug(...) - see debugging for details.
• method dispose() - call this to free up all bound resources. Base class method cleans the own container, firing dispose method of every object instance having it. Then it un-registers all handlers set by ownOn method.
• function ownOff (event= : string, emitter= : Object) : this - un-registers handlers registered for matching (event, emitter) pairs. It is called by dispose(), so in most cases you don't need to call it explicitly.
• function ownOn (event : string, handler, emitter, api=) : this - registers event handler with emitter object. If emitter API differs from addEventListener/removeEventListener or $on/$off, then you need explicitly define api, like ['on', 'off']. The handler parameter can be instance method name or a function.
• property debugOn : {boolean|undefined} - see debugging for details.
• property own : {Object} - a keyed container for private data, that should be gracefully cleaned up.
• property ownClass : {string} - class name.
• property ownNumber : {number} - globally unique class instance number.
• property ownName : {string} - initially set to ownClass + '#' + ownNumber.

Mutating debugOn or className property will re-generate debug() instance method.

Performance

This is a simple wrapper for Windows User Timing API. In production mode it does nothing. Usage example:

  import {perfB, perfE, perfDump} from 'val-front/performance'

  perfB('crazy-effort')   //  Create begin mark.
  performCrazyEffort()
  perfE('crazy-effort')   //  Create end mark and measure.

  perfDump().forEach(d => console.log(d))   //  Get results

API methods:

• perfB(name : {string}) - create begin mark.
• perfE(name : {string}) - create end mark and measure entry. Throws exception, if tag does not match any pending begin mark.
• perfGet(sortBy : {string}) : {Object[]} - returns sorted array of statistics. sortBy parameter defaults to 'total'. Each entry is an object with fields:
  • avg average duration per call,
  • count calls count,
  • max maximum duration,
  • name set via perfB/perfE,
  • total total duration of all calls with this name.
• perfDump(sortBy : {string}) : {string[]} - like perfGet, returning strings.
• perfReset() - resets measurements statistics..

Vue.js mixin

This mix-in will provide a Vue.js component with Own class API described above.

vueName function

vueName( vm, tryHarder = false ) : {string | undefined}
Try to get a meaningful name for a Vue.js component instance. It returns '#root#' for root instance or value of vm.name if defined or value of instance options name property.

If all the above fails, but tryHarder is set, it will try to use component tag or filename.