Wondering what’s next for npm?Check out our public roadmap! »

    objerve

    1.0.4 • Public • Published

    objerve

    Define callbacks that get fired when given object properties change.

    picture

    example

    const objerve = require('./main.js')
    
    const obj = objerve()
    
    objerve.addListener(obj, ['a', 'b'], (newValue, oldValue, action, path, obj) => {
      console.log(`${action} ${path.join('.')}: `+
        `${JSON.stringify(oldValue)} -> ${JSON.stringify(newValue)}`)
    })
    
    obj.a = { b: 'hi' }
    obj.a.b = 'hello'
    obj.a = null
    create a.b: undefined -> "hi"
    change a.b: "hi" -> "hello"
    delete a.b: "hello" -> undefined
    

    features

    • Behaves exactly like an ordinary Object
    • Can listen to fixed paths or to all paths with a prefix, and use objerve.each inside paths to match all array indexes.
    • Putting objerve instances (or parts of them) inside each others' properties fully works, and property changes are propagated between instances as you'd expect if they are properties of each other (even with circular references)
    • Can tell apart undefined property value and property deletion, thanks to the action argument passed to callbacks (shows created / changed / deleted).
    • Calls your callbacks in a nesting-respecting order, so your callbacks can setup and teardown state in the correct order (bottom-up construction, top-down destruction)
    • Stores listeners in a prefix tree by target path, to speed up queries with large objects and many listeners.

    api

    objerve([obj])

    Wrap the given object (default {}) so it can be subscribed to.

    The resulting object behaves like the object did before, but changes to its paths can be listened to with objerve.addListener or objerve.addPrefixListener.

    objerve.addListener(obj, path, callback)

    The path can contain objerve.each, which will match any Array index at that position.

    Works inside listener callbacks. If inside a listener you add a new listener that matches the same path, the new listener will also be called with this same change.

    objerve.removeListener(obj, path, callback)

    Remove the listener from the given path, so the callback is no longer called. The path is useful to disambiguate in case the same callback function is being used as the listener for multiple paths.

    Does nothing if it cannot find such a listener.

    Works inside listener callbacks. If you remove a listener for the same path inside a callback for that path, the removed listener won't be called for that change either (unless it was already called before this one).

    objerve.addPrefixListener(obj, path, callback)

    Same as addListener, but will be called for any property at all that has the given path as a prefix. Pass [] for the path to be called for every change to any property.

    objerve.removePrefixListener(obj, path, callback)

    Same as removeListener, but for prefix listeners.

    objerve.each

    A special Symbol value that can be passed as part of a path to listen to. It matches any valid array index, i.e. 0, 1, 999999999 etc, so your listener is called for every element of an array being created, changed, or deleted.

    how callbacks are called

    Your callback function is called immediately before the described change is actually applied to the object, with these arguments:

    • newValue

    • oldValue

    • action: One of the following strings:

      • 'create' if the property did not exist, and is being created
      • 'change' if the property exists, and its value is changing
      • 'delete' if the property exists, but it is being deleted

      Example: Using the action> argument to distinguish property deletion from being set to undefined
      const objerve = require('./main.js')
      const obj = objerve()
      
      objerve.addListener(obj, ['x'], (newValue, oldValue, action) => {
        console.log(`${action} ${oldValue} -> ${newValue}`)
      })
      
      obj.x = true
      obj.x = undefined
      delete obj.x
      create undefined -> true
      change true -> undefined
      delete undefined -> undefined
      

      Note how although both the obj.x = undefined and delete obj.x lines triggered a callback with newValue undefined, their actions differed: 'change' and 'delete'.

    • path: An Array representing the property path through the object at which this update happened. Useful if you have a single callback function listening to multiple paths.

    • obj: A reference to the object as it currently exists (just before the described update is actually applied).

    • updateId: A number uniquely identifying the currently happening change. All listeners that get called due to the same change (or caused by a callback reacting to the same change) see the same identifier.

      Example: same update id when a listener itself triggers a change
      const objerve = require('./main.js')
      const obj = objerve()
      
      // Listen to changes to 'obj.a'.  Reduce it by 1 unless it's 0.
      objerve.addListener(obj, ['a'],
        (val, previousVal, action, path, objRef, updateId) => {
          console.log(`[${action}] ${previousVal} -> ${val} (updateId ${updateId})`)
          if (val > 0) {
            obj.a = val - 1
          }
        })
      // Also create a listener listening to all properties on 'obj'.
      objerve.addPrefixListener(obj, [],
        (val, previousVal, action, path, objRef, updateId) => {
          console.log(`prefix listener called (updateId ${updateId})`)
        })
      
      obj.a = 3
      console.log(obj.a)
      obj.a = 2
      console.log(obj.a)

      Each time something is assigned to obj.a, the first listener gets called, and assigns it 1 lower, until it's 0:

      prefix listener called (updateId 0)
      [create] undefined -> 3 (updateId 0)
      prefix listener called (updateId 0)
      [create] undefined -> 2 (updateId 0)
      prefix listener called (updateId 0)
      [create] undefined -> 1 (updateId 0)
      prefix listener called (updateId 0)
      [create] undefined -> 0 (updateId 0)
      0
      prefix listener called (updateId 1)
      [change] 0 -> 2 (updateId 1)
      prefix listener called (updateId 1)
      [change] 0 -> 1 (updateId 1)
      prefix listener called (updateId 1)
      [change] 0 -> 0 (updateId 1)
      0
      

      Note that for each individual change (obj.a = 3 and obj.a = 2), both listeners were called multiple times, but during each change both were called with the same updateId.

    If your callback wants to cancel the described change from happening, simply assign a value to the property being changed and it will take priority.

    Note that callbacks are always called for every matching change, even if changes essentially invalidate previous ones by overwriting their values. Some use-cases (such as updating a UI in response to property changes) may only care about the final results at the end of this event loop tick, so you may wish to accumulate the changes and defer your rendering with an API appropriate for your use-case (such as setImmediate, process.nextTick, queueMicrotask, requestAnimationFrame, etc).

    Example: Accumulating changes and deferring rendering using process.nextTick
    const objerve = require('./main.js')
    const ArrayKeyedMap = require('array-keyed-map')
    
    const obj = objerve()
    const accumulatedChanges = new ArrayKeyedMap()
    
    const render = () => {
      // Put your expensive UI rendering code here
      console.log(Array.from(accumulatedChanges.entries()))
      accumulatedChanges.clear()
    }
    
    objerve.addListener(obj, ['a'],
      (newVal, oldVal, action, path) => {
        if (accumulatedChanges.size === 0) process.nextTick(render)
        if (!accumulatedChanges.has(path)) {
          accumulatedChanges.set(path, {newVal, oldVal})
        } else {
          accumulatedChanges.get(path).newVal = newVal
        }
      })
    
    // Make a bunch of changes
    obj.a = 1
    obj.a = 2
    obj.a = 3

    The render function only gets called on next event loop tick tick, with the total accumulated change from undefined to 3, and none of the intermediate states between:

    [ [ [ 'a' ], { newVal: 3, oldVal: undefined } ] ]
    

    call order

    When one change triggers multiple callbacks, the order they are called depends on whether the change is constructive or destructive: If the property is being created or changed, callbacks are called in root→leaf order. If the property is being deleted, callbacks are called in leaf→root order.

    Because of this feature, your listeners can setup or teardown state (e.g. managing DOM elements) in response to creation or deletion, and sub-properties can use that state (e.g. appending their own DOM elements to the parent's ones) while still being able to clean up the sub-properties' state gracefully and in the right order even when a whole chain of properties is deleted all at once.

    Example: Construction and destruction call order
    const objerve = require('./main.js')
    const obj = objerve()
    
    const callback = (name) => {
      return (val, previousVal, action) => {
        console.log(`${action} ${name}`)
      }
    }
    
    objerve.addListener(obj, ['a'], callback('a'))
    objerve.addListener(obj, ['a', 'b'], callback('a.b'))
    objerve.addListener(obj, ['a', 'b', 'c'], callback('a.b.c'))
    
    obj.a = { b: { c: 'value' } }
    delete obj.a
    create a
    create a.b
    create a.b.c
    delete a.b.c
    delete a.b
    delete a
    

    Prefix listeners and objerve.each-matching listeners are also considered "parents" of concrete property paths, so their listeners are called before the concrete path's listeners on creation/change (prefix→each→concrete), and after them on deletion (concrete→each→prefix).

    Example: Construction and destruction call order, with prefix- and objerve.each-listeners
    const objerve = require('./main.js')
    const obj = objerve([])
    
    const callback = (name) => {
      return (val, previousVal, action) => console.log(`${action} ${name}`)
    }
    
    // Listen for property '0'
    objerve.addListener(obj, [0], callback('concrete'))
    // Listen for any array index
    objerve.addListener(obj, [objerve.each], callback('each'))
    // Listen for all properties
    objerve.addPrefixListener(obj, [], callback('prefix'))
    
    obj[0] = true
    delete obj[0]
    create prefix
    create each
    create concrete
    delete concrete
    delete each
    delete prefix
    

    If there are multiple listeners for a property that changes, the listeners are called in insertion order.

    Other than the above rules, the relative order in which any two paths' callbacks are called may be arbitrary, so you shouldn't rely on it.

    use-cases

    • Binding data to UI.
    • Testing. Transparently adding logging to property changes is handy.
    • Reactive programming.

    license

    ISC; summary: use for anything, credit me, no warranty

    Keywords

    none

    Install

    npm i objerve

    DownloadsWeekly Downloads

    52

    Version

    1.0.4

    License

    ISC

    Unpacked Size

    67.3 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar