keep-tidy v1.1.1

keep-tidy

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-tidyoryarn 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:

• assert - assertion package used internally;
• debugMe - a debug function factory;
• debug - underlying debug package;
• TidyOwner - the base class constructor, also available as default export;

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:

• assertHooka 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: Objecta keyed container for private data, that should be gracefully cleaned up.
• ownClass: stringclass name (read-only).
• ownId: numberglobally unique class instance number(read-only).

• ownTag: stringis 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.