keep-tidy

Simple utilities and ES5 base class for robust and maintainable code.

Usage no npm install needed!

<script type="module">
  import keepTidy from 'https://cdn.skypack.dev/keep-tidy';
</script>

README

keep-tidy

Build Status Code coverage

A tiny ES5 base class featuring clean disposal of bound resources. It also provides a simple API for easier debugging and diagnostics. All this works in both back-end and front-end environments.

Processing DOM events or similar in OO code implies correct set-up and releasing of event handlers. Also, cross-referenced class instances and other objects need special care to prevent the dreaded memory leaks. The TidyOwner base class interface of own property and dispose() method may save you from writing boring boilerplate code and possibly making mistakes in those cases.

Installation

npm install -S keep-tidy
or
yarn add keep-tidy

Usage

  import Tidy from 'keep-tidy'

  class A extends Tidy {
    resizeHandler() { 
      this.debug('resized')           //  console output like: 'A#2 resized +0ms 3'
    }
  }

  let superItem = new A() 
  //  Nested structures are OK.
  superItem.own.item1 = new A().ownOn('resize', 'resizeHandler', window).debugOn(true)
  superItem.own.somethingElse = [1, 2, 3]
  //  Lots of interecting things in between...
  superItem.dispose()                             //  Tidy up everything now...
  superItem = undefined                           //  ... and yes, this is no C++ ;)

There is also lightweight debugging and assertion helpers available even if you won't use Javascript classes at all.

API

The package exports the following API:

Some parts can be loaded individually: 'owner-class/debug' and 'owner-class/helpers'.

Baseclass

constructor TidyOwner([classNameOverride : string])

When using this baseclass, you'll avoid writing boilerplate code for releasing event handlers and freeing other resources. Its interface consists of:

  • assertHook
    a class (not instance) method - a convenience shortcut for assert.hook().
  • debug(...)
    see debugging for details.
  • debugOn([*]): *
    for re-generating the debug method and returning this for chaining, if argument supplied; otherwise returns boolean showing if debugging is enabled.
  • 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.
  • 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.
  • ownOn(event : string, handler, emitter, api=) : this
    registers event handler with emitter object. If emitter API differs from addEventListener/removeEventListener or $on/$off or on/off, then you need explicitly define the API, like ['listenTo', 'ignore']. The handler parameter can be instance method name or a function.
  • own: Object
    a keyed container for private data, that should be gracefully cleaned up.
  • ownClass: string
    class name (read-only).
  • ownId: number
    globally unique class instance number(read-only).
  • ownTag: string
    is set to ownClass+ '#' +ownId (read-only).

Assigning a value to any instance property will throw TypeError.

Debugging

Debugging machinery uses debug NPM package and is available only in development mode. In production mode all its API methods will be just empty functions.

debugMe( tag: string, [yesNo : boolean]) : {function(...)}
exported from the main package is factory function returning the actual debug function.

The same factory function is default export from the sub-package (see example below).

Debugging plain javascript code:

  const D = require('keep-tidy/debug')
  const myDebug = D(main.js, true), { debug } = D

  myDebug('try(%d, %o)', 1, 2, 3)       // --> 'main.js try(1, 2) +0ms 3'
  debug.enable('*')
  debug('natively')('yay!')             // --> 'natively yay! +0ms'

Compatibility

The package should be ECMAScript 2015 and it should run virtually anywhere. If you find any issues, please do not hesitate to report.