Legacy Reactor

The Legacy Reactor is a standalone implementation of the vue 2.x observer code for reactivity.

The target environment is ES5+ and will therefore work on any browser that supports it.

Recommended IDE

You should be using Visual Studio Code because its simple, fast, extensible and beloved by many developers.

Make sure to install all the recommended extensions that come with the repository for the best possible coding experience.

NPM Scripts

Note that these examples use yarn but you can use the equivalent npm run <command> instead.

Most of them will automatically run when you perform certain actions on your repository.

Code style

Ensures code consistency in your code base.

These commands automatically get run before commits.

yarn style - Runs all style:* commands.
yarn style:lint - Lints your code using eslint.
yarn style:format - Formats your code using prettier.

Build Tasks

Creates builds from your Typescript files for CommonJS (cjs) and ES6 modules (esm).

yarn build - Runs all build commands which creates builds for different node environments.
yarn build:main - Creates a build using cjs modules.
yarn build:module - Creates a build using esm modules.

Testing

Ensures code is reliable by running your jest unit tests.

Unit tests automatically get run before commits.

yarn test - Runs all tests and generates a code coverage report.
yarn test:watch - Watches file changes and reruns tests for those changed files.

Code Coverage

Generates and publishes documentation based on your typedoc comments.

Code coverages reports are automatically generated and published during CI builds.

yarn cov - Generate a code coverage report.
yarn cov:open - Open generated code coverage report.
yarn cov:publish - Publish generated code coverage reports to codecov. Running this command locally will require the upload token for e.g yarn cov:publish --token="YOUR_TOKEN_HERE"

Documentation

Generate and publishing documentation based on your typedoc comments.

Documentation is automatically generated and published during CI builds.

yarn doc - Generates documentation from code.
yarn doc:open - Opens generated documentation in your default browser.
yarn doc:publish - Publishes generated documentation.

Helpers

These commands perform misc tasks.

yarn commit - Create a new commit using the commitizen cli.
yarn clean - Cleans up all build artifacts such as the distribution folder.

Conventional Commits

Commit messages to this repository that don't follow the conventional commit guidelines will be rejected by a commit-msg git hook.

No one likes rejection so use the yarn commit script which provides a CLI interface for creating formated commits.

Git Hooks

If you would like to run custom tasks during important actions on a repository you can use git hooks.

To make this as simple as possible we use husky which is also used in the conventional commits toolchain.

Debugging

The following launch configurations will assist with debugging your library.

Current TS File - debug current typescript file.
Current Jest Test - debug current jest test.
All Jest Tests - debug all jest tests.

Usage

Computed properties

Computed properties are properties that get their value from other properties.

When you change one of the properties it relies on it will automatically be recalculated.

import { observe } from '@microlibs/legacy-reactor';

const observed = observe({
  price: 55.6,
  qty: 100,
  // Any function in this object is treated as a computed property definition.
  total() {
    return this.price * this.total;
  },
});

console.log(observed.total); // output: 5560

observed.price = 60;
console.log(observed.total); // output: 6000

observed.qty = 50;
console.log(observed.total); // output: 3000

Side Effects

Computed properties disable data updates within them to keep your data predictable.

Setting the value of data within a computed property will cause an exception.

const observed = observe({
  price: 10,
  qty: 5,
  total() {
    // okay
    var value = this.price * this.total;

    // this line will throw an exception
    this.price = 1000;

    return value;
  },
});

Watchers

Watchers are simple functions that get run when the value of an observed property changes.

You can register multiple watchers per property.

import { observe, addPropertyWatcher, removePropertyWatcher } from '@microlibs/legacy-reactor';

const observed = observe({
  price: 55.6,
  qty: 100,
  // Any function in this object is treated as a computed property definition.
  total() {
    return this.price * this.total;
  },
});

// The first parameter is an observed object
// The second parameter is the path to the property in the observed data.
// In case of a nested object {nested: {total: 55 }} you would write 'nested.total'.
// The last parameter is the function to be called when the value of total changes.
const watcher = addPropertyWatcher(observed, 'total', (value, oldValue) => {
  console.log(value, oldValue);
});

observed.price = 100; // output: 10000 5560

removePropertyWatcher(observed, 'total', watcher);

// No output since the watcher was removed
observed.price = 60.56;

Known Issues

Since the reactor uses the same reactivity mechanism as vue does it comes with the same caveats.

Adding properties to an observed object is not tracked.
Deleting properties from an observed object is not tracked.

Due to the above two caveats we decided to seal the observed object. Therefore you cannot add or remove properties once you have created an observed object.
Reassigning array length is not tracked.

It is not possible to define a getter on the length property since it is not configurable.