tracked-built-ins

tracked-built-ins

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);
}

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

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
• Embroider or ember-auto-import v2

TypeScript

This project follows the current draft of the Semantic Versioning for TypeScript Types specification.

• Currently supported TypeScript versions: v4.4, v4.5, and v4.6
• Compiler support policy: simple majors
• Public API: all published types not in a -private module are public

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Changelog

v3.3.0 (2023-09-22)

:rocket: Enhancement

• #408 Move Array#fill to "write then read" methods so the template correctly updates (@locks)

:memo: Documentation

• #410 Update compatibility section in README.md (@SergeAstapov)

:house: Internal

• #409 Update test-app to the latest blueprint (@ef4)

Committers: 4

• Chris Krycho (@chriskrycho)
• Edward Faulkner (@ef4)
• Ricardo Mendes (@locks)
• Sergey Astapov (@SergeAstapov)