tracked-built-ins

Note: This addon does NOT support IE 11 or older browsers. If you need to support them, consider using tracked-maps and sets instead.

This addon provides tracked versions of JavaScript's built-ins:

import {
  TrackedObject,
  TrackedArray,
  TrackedMap,
  TrackedSet,
  TrackedWeakMap,
  TrackedWeakSet,
} from 'tracked-built-ins';

These classes have the same APIs as their native equivalents, but reading from them or writing to them will be tracked, allowing you to use them in your Ember apps and have changes automatically propagate!

Also included is an enhanced version of the @tracked decorator, which automatically shallow-wraps the native versions of these classes:

import { tracked } from 'tracked-built-ins';

class Foo {
  @tracked value = 123;

  obj = tracked({});
  arr = tracked([]);
  map = tracked(Map);
  set = tracked(Set);
  weakMap = tracked(WeakMap);
  weakSet = tracked(WeakSet);
}

Installation

ember install tracked-built-ins

Usage

See the MDN documentation for each class to learn more about it:

• Object
• Array
• Map
• Set
• WeakMap
• WeakSet

All public APIs are the same, with a few exceptions:

1. new TrackedArray() should receive an array instead of variable number of arguments. This decision was due to the confusing nature of new Array() in general, and for symmetry with the other new APIs.

   // bad
   new TrackedArray(123);
   new TrackedArray('foo', 'bar', 'baz');
   
   // good
   new TrackedArray([123]);
   new TrackedArray(['foo', 'bar', 'baz']);

2. new TrackedObject() returns a copy of the object passed back to it, whereas new Object() will return the original object. This is to prevent accidentally mutating the original object.

   let original = {};
   let obj = new TrackedObject(original);
   
   obj.foo = 123;
   original.foo; // undefined;

3. Static Array and Object methods that do not create a new Array/Object have been omitted. In general, you should use the original static methods for these features, since autotracking has nothing to do with them. The static methods that are supported are:

   • Array
     • from
     • of
   • Object
     • fromEntries

   Object.create has also been omitted, even though it creates an instance, because manual prototype manipulation is an advanced use case in general that is not currently supported.

All types will also register as instanceof their base type, so they can be used as fully transparent replacements in most circumstances.

Compatibility

• Ember.js v3.24 (LTS) or above
• Ember CLI v3.23 or above
• Node.js v12 or above

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.