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-tidy
oryarn add keep-tidy
Usage
{ this // console output like: 'A#2 resized +0ms 3' } let superItem = // Nested structures are OK. superItemownitem1 = superItemownsomethingElse = 1 2 3 // Lots of interecting things in between... superItem // 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:
assertHook
a class (not instance) method - a convenience shortcut forassert.hook()
.debug
(...)
see debugging for details.debugOn
([*]): *
for re-generating thedebug
method and returningthis
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 theown
container, firingdispose
method of every object instance having it. Then it un-registers all handlers set byownOn
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
registersevent
handler
withemitter
object. If emitter API differs fromaddEventListener/removeEventListener
or$on/$off
oron/off
, then you need explicitly define the API, like['listenTo', 'ignore']
. Thehandler
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 toownClass
+ '#' +
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 = const myDebug = debug = D // --> 'main.js try(1, 2) +0ms 3' debug '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.