Neurotic and Probably Misinformed

    icaro

    1.2.1 • Public • Published

    icaro

    A smart and efficient javascript object observer, ideal for batching DOM updates (~1kb)

    Build Status NPM version NPM downloads MIT License

    Installation

    Via npm

    $ npm i icaro -S

    Script import

    Via <script>

    <script src='path/to/icaro.js'></script>

    Via ES2015 modules

    import icaro from 'icaro'

    Via commonjs

    const icaro = require('icaro')

    Demos

    Performance

    icaro is really fast compared to the other reactive libs because it smartly throttles all the state changes.

    Usage

    icaro will let you listen to all the changes happening in a javascript object or array, grouping them efficiently, and optimizing the performance of your listeners.

     
    const obj = icaro({})
     
    // the variable "changes" here is a Map and the function is async
    obj.listen(function(changes) {
      console.log(changes.get('foo')) // 'hi'
      console.log(changes.get('bar')) // 'there'
      console.log(changes.get('baz')) // 'dude'
     
      // kill all the listeners
      obj.unlisten()
    })
     
    obj.foo = 'hi'
    obj.bar = 'there'
    obj.baz = 'dude'
     

    icaro will also let you listen to nested objects and all the non primitive properties added to an icaro object will be automatically converted into icaro observable objects.

    const obj = icaro({})
     
    // listen only the changes happening on the root object
    obj.listen(function(changes) {
    })
     
    obj.nested = {
     
    }
     
    obj.nested.listen(function(changes) {
      // listen only the changes of obj.nested
    })
     
    obj.nested.someVal = 'hello'
     

    icaro is able also to listen changes in arrays. Any change to the items indexes will dispatch events.

     
    // Here a bit of hardcore async stuff
     
    const arr = icaro([])
     
    // here you will get the index of the items added or who changed their position
    arr.listen(function(changes) {
      console.log(changes.get('0')) // 'foo'
      console.log(changes.get('1')) // 'bar'
      // kill all the listeners this included
      arr.unlisten()
     
      // add a brand new listener recursively.. why not?
      arr.listen(function(changes) {
        // the change was triggered by a 'reverse' and all indexes were updated
        console.log(changes.get('0')) // 'bar'
        console.log(changes.get('1')) // 'foo'
      })
     
      // update all the indexes
      arr.reverse()
    })
     
    // initial dispatch
    arr.push('foo')
    arr.push('bar')
     

    You can also avoid unsubscribing ("unlisten") because icaro will automatically remove event listeners when the object is about to be garbage collected.

    API

    Any icaro call will return a Proxy with the following api methods

    icaro.listen(callback)

    Listen any object or array calling the callback function asynchronously grouping all the contiguous changes via setImmediate

    @returns self

    icaro.unlisten(callback|null)

    Unsubscribing a callback previously subscribed to the object, if no callback is provided all the previous subscriptions will be cleared

    @returns self

    icaro.toJSON()

    Return all data contained in an icaro Proxy as JSON object

    @returns Object

    Support

    icaro uses advanced es6 features like Proxies, WeakMaps, Maps and Symbols and it targets only modern browsers

    All major evergreen browsers (Edge, Chrome, Safari, Firefox) should be supported

    Install

    npm i icaro

    DownloadsWeekly Downloads

    1

    Version

    1.2.1

    License

    MIT

    Last publish

    Collaborators

    • gianlucaguarini