{"_id":"observe-js","_rev":"2772517","name":"observe-js","description":"observe-js is a library for observing changes on JavaScript objects/arrays","dist-tags":{"latest":"0.5.7"},"maintainers":[{"name":"azakus","email":""}],"time":{"modified":"2022-05-23T09:41:45.000Z","created":"2013-08-22T14:22:12.488Z","0.5.7":"2015-11-12T23:10:15.055Z","0.4.2":"2014-11-06T00:02:29.106Z","0.1.0":"2013-08-22T14:22:12.488Z"},"users":{},"author":{"name":"The Polymer Authors"},"repository":{"type":"git","url":"git+https://github.com/Polymer/observe-js.git"},"versions":{"0.5.7":{"name":"observe-js","version":"0.5.7","description":"observe-js is a library for observing changes on JavaScript objects/arrays","main":"src/observe.js","directories":{"example":"examples","test":"tests"},"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"repository":{"type":"git","url":"git+https://github.com/Polymer/observe-js.git"},"author":{"name":"The Polymer Authors"},"license":"BSD","devDependencies":{"chai":"*","mocha":"*","grunt":"*","grunt-karma":"*","karma":"~0.12.0","karma-mocha":"*","karma-firefox-launcher":"*","karma-ie-launcher":"*","karma-safari-launcher":"*","karma-script-launcher":"*","karma-crbot-reporter":"*"},"contributors":[{"name":"Google Inc.","email":"*@google.com"}],"gitHead":"9bb2c57d851820c55a92097c99be69101a0e9697","bugs":{"url":"https://github.com/Polymer/observe-js/issues"},"homepage":"https://github.com/Polymer/observe-js#readme","_id":"observe-js@0.5.7","_shasum":"5ae7466cf04b9a1d7cf8a029f5e1a806fda93ab6","_from":".","_npmVersion":"3.3.6","_nodeVersion":"5.0.0","_npmUser":{"name":"azakus","email":"dfreedm2@gmail.com"},"maintainers":[{"name":"azakus","email":""}],"dist":{"shasum":"5ae7466cf04b9a1d7cf8a029f5e1a806fda93ab6","size":36280,"noattachment":false,"key":"/observe-js/-/observe-js-0.5.7.tgz","tarball":"http://registry.cnpm.dingdandao.com/observe-js/download/observe-js-0.5.7.tgz"},"publish_time":1447369815055,"_hasShrinkwrap":false,"_cnpm_publish_time":1447369815055,"_cnpmcore_publish_time":"2021-12-17T00:32:14.928Z"},"0.4.2":{"name":"observe-js","version":"0.4.2","description":"observe-js is a library for observing changes on JavaScript objects/arrays","main":"src/observe.js","directories":{"example":"examples","test":"tests"},"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"repository":{"type":"git","url":"https://github.com/Polymer/observe-js.git"},"author":{"name":"The Polymer Authors"},"license":"BSD","devDependencies":{"chai":"*","mocha":"*","grunt":"*","grunt-karma":"*","karma":"~0.12.0","karma-mocha":"*","karma-firefox-launcher":"*","karma-ie-launcher":"*","karma-safari-launcher":"*","karma-script-launcher":"*","karma-crbot-reporter":"*"},"contributors":[{"name":"Google Inc.","email":"*@google.com"}],"gitHead":"061f240589fda4d357a8e2ac23ebcf398915378b","bugs":{"url":"https://github.com/Polymer/observe-js/issues"},"homepage":"https://github.com/Polymer/observe-js","_id":"observe-js@0.4.2","_shasum":"efcd942847e9b8ed24b2db865e711fd7c7d2ce96","_from":".","_npmVersion":"1.4.28","_npmUser":{"name":"azakus","email":"dfreedm@google.com"},"maintainers":[{"name":"azakus","email":""}],"dist":{"shasum":"efcd942847e9b8ed24b2db865e711fd7c7d2ce96","size":315467,"noattachment":false,"key":"/observe-js/-/observe-js-0.4.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/observe-js/download/observe-js-0.4.2.tgz"},"publish_time":1415232149106,"_hasShrinkwrap":false,"_cnpm_publish_time":1415232149106,"_cnpmcore_publish_time":"2021-12-17T00:32:16.050Z"},"0.1.0":{"name":"observe-js","version":"0.1.0","description":"observe-js is a library for observing changes on JavaScript objects/arrays","contributors":[{"name":"Sam Duvall","email":"sam@rocketwhale.com"}],"main":"src/observe.js","directories":{"example":"examples","test":"tests"},"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"repository":{"type":"git","url":"https://github.com/Polymer/ObserveJS.git"},"author":"","license":"BSD","readmeFilename":"README.md","gitHead":"123e411687c6199c240b709d582b0e939cb14080","devDependencies":{"chai":"*","mocha":"*"},"bugs":{"url":"https://github.com/Polymer/ObserveJS/issues"},"_id":"observe-js@0.1.0","dist":{"shasum":"3f5416a5348ef3653010cace182318119f7d2822","size":33118,"noattachment":false,"key":"/observe-js/-/observe-js-0.1.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/observe-js/download/observe-js-0.1.0.tgz"},"_from":".","_npmVersion":"1.3.5","_npmUser":{"name":"samduvall","email":"SamDuvall@gmail.com"},"maintainers":[{"name":"azakus","email":""}],"publish_time":1377181332488,"_hasShrinkwrap":false,"_cnpm_publish_time":1377181332488,"_cnpmcore_publish_time":"2021-12-17T00:32:16.348Z"}},"readme":"[![Analytics](https://ga-beacon.appspot.com/UA-39334307-2/Polymer/observe-js/README)](https://github.com/igrigorik/ga-beacon)\n\n## Learn the tech\n\n### Why observe-js?\n\nobserve-js is a library for observing changes in JavaScript data. It exposes a high-level API and uses [Object.observe](https://github.com/arv/ecmascript-object-observe) if available, and otherwise performs dirty-checking. observe-js requires ECMAScript 5.\n\n### Observable\n\nobserve-js implements a set of observers (PathObserver, ArrayObserver, ObjectObserver, CompoundObserver, ObserverTransform) which all implement the Observable interface:\n\n```JavaScript\n{\n  // Begins observation. Value changes will be reported by invoking |changeFn| with\n  // |opt_receiver| as the target, if provided. Returns the initial value of the observation.\n  open: function(changeFn, opt_receiver) {},\n\n  // Report any changes now (does nothing if there are no changes to report).\n  deliver: function() {},\n\n  // If there are changes to report, ignore them. Returns the current value of the observation.\n  discardChanges: function() {},\n\n  // Ends observation. Frees resources and drops references to observed objects.\n  close: function() {}\n}\n```\n\n### PathObserver\n\nPathObserver observes a \"value-at-a-path\" from a given object:\n\n```JavaScript\nvar obj = { foo: { bar: 'baz' } };\nvar defaultValue = 42;\nvar observer = new PathObserver(obj, 'foo.bar', defaultValue);\nobserver.open(function(newValue, oldValue) {\n  // respond to obj.foo.bar having changed value.\n});\n```\n\nPathObserver will report a change whenever the value obtained by the corresponding path expression (e.g. `obj.foo.bar`) would return a different value.\n\nPathObserver also exposes a `setValue` method which attempts to update the underlying value. Setting the value does not affect notification state (in other words, a caller sets the value but does not `discardChanges`, the `changeFn` will be notified of the change).\n\n```JavaScript\nobserver.setValue('boo');\nassert(obj.foo.bar == 'boo');\n```\n\nNotes:\n * If the path is ever unreachable, the value is considered to be `undefined` (unless you pass an overriding `defaultValue` to `new PathObserver(...)` as shown in the above example).\n * If the path is empty (e.g. `''`), it is said to be the empty path and its value is its root object.\n * PathObservation respects values on the prototype chain\n\n### ArrayObserver\n\nArrayObserver observes the index-positions of an Array and reports changes as the minimal set of \"splices\" which would have had the same effect.\n\n```JavaScript\nvar arr = [0, 1, 2, 4];\nvar observer = new ArrayObserver(arr);\nobserver.open(function(splices) {\n  // respond to changes to the elements of arr.\n  splices.forEach(function(splice) {\n    splice.index; // the index position that the change occurred.\n    splice.removed; // an array of values representing the sequence of removed elements\n    splice.addedCount; // the number of elements which were inserted.\n  });\n});\n```\n\nArrayObserver also exposes a utility function: `applySplices`. The purpose of `applySplices` is to transform a copy of an old state of an array into a copy of its current state, given the current state and the splices reported from the ArrayObserver.\n\n```JavaScript\nAraryObserver.applySplices = function(previous, current, splices) { }\n```\n\n### ObjectObserver\n\nObjectObserver observes the set of own-properties of an object and their values.\n\n```JavaScript\nvar myObj = { id: 1, foo: 'bar' };\nvar observer = new ObjectObserver(myObj);\nobserver.open(function(added, removed, changed, getOldValueFn) {\n  // respond to changes to the obj.\n  Object.keys(added).forEach(function(property) {\n    property; // a property which has been been added to obj\n    added[property]; // its value\n  });\n  Object.keys(removed).forEach(function(property) {\n    property; // a property which has been been removed from obj\n    getOldValueFn(property); // its old value\n  });\n  Object.keys(changed).forEach(function(property) {\n    property; // a property on obj which has changed value.\n    changed[property]; // its value\n    getOldValueFn(property); // its old value\n  });\n});\n```\n\n### CompoundObserver\n\nCompoundObserver allows simultaneous observation of multiple paths and/or Observables. It reports any and all changes in to the provided `changeFn` callback.\n\n```JavaScript\nvar obj = {\n  a: 1,\n  b: 2,\n};\n\nvar otherObj = { c: 3 };\n\nvar observer = new CompoundObserver();\nobserver.addPath(obj, 'a');\nobserver.addObserver(new PathObserver(obj, 'b'));\nobserver.addPath(otherObj, 'c');\nvar logTemplate = 'The %sth value before & after:';\nobserver.open(function(newValues, oldValues) {\n  // Use for-in to iterate which values have changed.\n  for (var i in oldValues) {\n    console.log(logTemplate, i, oldValues[i], newValues[i]);\n  }\n});\n```\n\n\n### ObserverTransform\n\nObserverTransform is used to dynamically transform observed value(s).\n\n```JavaScript\nvar obj = { value: 10 };\nvar observer = new PathObserver(obj, 'value');\nfunction getValue(value) { return value * 2 };\nfunction setValue(value) { return value / 2 };\n\nvar transform = new ObserverTransform(observer, getValue, setValue);\n\n// returns 20.\ntransform.open(function(newValue, oldValue) {\n  console.log('new: ' + newValue + ', old: ' + oldValue);\n});\n\nobj.value = 20;\ntransform.deliver(); // 'new: 40, old: 20'\ntransform.setValue(4); // obj.value === 2;\n```\n\nObserverTransform can also be used to reduce a set of observed values to a single value:\n\n```JavaScript\nvar obj = { a: 1, b: 2, c: 3 };\nvar observer = new CompoundObserver();\nobserver.addPath(obj, 'a');\nobserver.addPath(obj, 'b');\nobserver.addPath(obj, 'c');\nvar transform = new ObserverTransform(observer, function(values) {\n  var value = 0;\n  for (var i = 0; i < values.length; i++)\n    value += values[i]\n  return value;\n});\n\n// returns 6.\ntransform.open(function(newValue, oldValue) {\n  console.log('new: ' + newValue + ', old: ' + oldValue);\n});\n\nobj.a = 2;\nobj.c = 10;\ntransform.deliver(); // 'new: 14, old: 6'\n```\n\n### Path objects\n\nA path is an ECMAScript expression consisting only of identifiers (`myVal`), member accesses (`foo.bar`) and key lookup with literal values (`arr[0]` `obj['str-value'].bar.baz`).\n\n`Path.get('foo.bar.baz')` returns a Path object which represents the path. Path objects have the following API:\n\n```JavaScript\n{\n  // Returns the current value of the path from the provided object. If eval() is available,\n  // a compiled getter will be used for better performance. Like PathObserver above, undefined\n  // is returned unless you provide an overriding defaultValue.\n  getValueFrom: function(obj, defaultValue) { },\n\n  // Attempts to set the value of the path from the provided object. Returns true IFF the path\n  // was reachable and set.\n  setValueFrom: function(obj, newValue) { }\n}\n```\n\nPath objects are interned (e.g. `assert(Path.get('foo.bar.baz') === Path.get('foo.bar.baz'));`) and are used internally to avoid excessive parsing of path strings. Observers which take path strings as arguments will also accept Path objects.\n\n## About delivery of changes\n\nobserve-js is intended for use in environments which implement Object.observe, but it supports use in environments which do not.\n\nIf `Object.observe` is present, and observers have changes to report, their callbacks will be invoked at the end of the current turn (microtask). In a browser environment, this is generally at the end of an event.\n\nIf `Object.observe` is absent, `Platform.performMicrotaskCheckpoint()` must be called to trigger delivery of changes. If `Object.observe` is implemented, `Platform.performMicrotaskCheckpoint()` has no effect.\n","_attachments":{},"homepage":"https://github.com/Polymer/observe-js#readme","bugs":{"url":"https://github.com/Polymer/observe-js/issues"},"license":"BSD"}