particl

A small, easy to use JavaScript module that provides asynchronous control flow, event/property listeners, barriers, and more.

particl is the spiritual successor to atom, using some more modern language features and adding Promise support and more thorough tests.

Features

• Small, depending only on core-js for older browser support.
• Allows you to clearly code using a variety of async control flow patterns, even ones that would be cumbersome to implement clearly with just Promises.

Install

  npm install particl

Tutorial

Constructor

You can call the particl() constructor without arguments, but it's also possible to pass in initial properties as an object, and/or a callback function which will be immediately invoked.

  // no arguments
  let p = particl();

  // initial values
  p = particl({ prop1: 'value1', prop2: 'value2' });

  // exploded api view
  p = particl(({ get, set, need, provide, ... }) => {
    ...
  });
  p = particl({ prop1: 'value1' }, ({ get, set, need, provide, ... }) => {
    ...
  });

The exploded api form simply makes the entire instance API available as the first argument to the callback, so that you can easily select the portion of the api you want to interact with using argument destructuring.

So the following are identical:

  const p = particl();
  p.set('foo', 'bar');

  const p = particl({ foo: 'bar' });

  const p = particl(({ set }) => {
    set({ foo: 'bar' });
  });

Properties

A particl has properties. The get() and set() methods may be employed to read and write values of any type:

  particl(({ get, set }) => {

    set('key', 'value');
    console.log('Value of key:', get('key'));

    set({
      pi: 3.141592653,
      r: 5,
      circumference: () => 2 * get('pi') * get('r'),
    });
    console.log('Circumference:', get('circumference')());
  });

If an object is passed in to the constructor, it will initialize properties:

  p = particl({ p: 3.141592653, r: 5 });

Use has() to query for existence of a property, and keys() to get a list of all properties that have been set.

  if (p.has('skills')) {
    console.log('What "p" brings to the table:', p.keys());
  }

The each() method lets you execute a function on a series of properties.

  p.set({ r: 0xBA, g: 0xDA, b: 0x55 });
  p.each(['r', 'g', 'b'], (key, value) => {
    console.log(`${key}:${value}`);
  });

Listeners

Listeners may be attached to particls in a variety of ways.

To be notified as soon as a property is set, use the once() method. The callback will be called immediately if the property is already set.

  p.once('user', (user) => {
    alert(`Welcome, ${user.name}!`);
  });

or

  p.once('user').then((user) => {
    alert(`Welcome, ${user.name}!`);
  });

Many particl methods can work with more than one property at a time.

  p.once(['app', 'user'], (app, user) => {
    alert(`Welcome to ${app.name}, ${user.name}!`);
  });

or

  p.once(['app', 'user']).then(({ app, user }) => {
    alert(`Welcome to ${app.name}, ${user.name}!`);
  });

When you just want to know about the next change, even if the property is already set, use next().

  p.next('click', (click) => {
    alert(`Are you done clicking on ${click.button} yet?`);
  });

To watch for any future changes to a property, use the on() method.

  function myErrorHandler(error) {
    console.log(`There was a grievous calamity of code in ${p.get('module')}`);
    console.log(error);
  }
  p.on('error', myErrorHandler);

Note that setting a property with a primitive (string/number/boolean) value will only trigger listeners if the value is different. On the other hand, setting an array or object value will always trigger listeners.

You can unregister any listener using off().

  p.off(myErrorHandler);

Needs and Providers

You can register a provider for a property.

  particl(({ need, on, provide }) => {
    provide('privacyPolicy', () => fetch(`${baseUrl}/privacy.txt`));

    on('clickPrivacy', async () => {
      element.innerText = await need('privacyPolicy');
    });
  });

Providers only get invoked if there is a need, and if the property is not already set. Use the need() method to declare a need for a particular property. If a corresponding provider is registered, it will be invoked. Otherwise, need() behaves just like once().

Exploded view

If you call explode(func) or else just pass in a function to the constructor, it will be called with the entire api object, allowing you to easily select just individual methods you want with argument destructuring:

  particl(async ({ get, need, on, provide, set }) => {
    set({ logDefaults: { appName: 'myApp' }});

    on('log', (event) => {
      console.log({
        ...get('logDefaults'),
        ...event,
        timestamp: Date.now(),
      });
    });
    const log = event => set('log', event);

    provide('data', () => fetch('${baseUrl}/api/data'));

    const data = await need('data');
    log({ msg: 'data loaded '});

    ...
  });

Extending functionality with mixins

The particl constructor provides a way to incorporate mixins that extend the particl's api. Use it like this:

  particl(
    [ ...mixins ],
    ({ on, set, get, need, customMethodFromMixin, ... }) => {

    }
  );

Some helpful mixins are included in the mixins/ directory. Fox example, use the customListeners mixin to create customized method names for specific properties:

  const customListenersMixin = require('particl/dist/mixins/customListeners');

  particl(
    [customListenersMixin('event')],
    ({ onEvent, onceEvent, setEvent }) => {
      // This is a convenient shorthand for on('event', (evt) => { ... })
      onEvent((evt) => {
        console.log('Something happened:', evt);
      });
    }
  );

Or use the matchers mixin to add validation to your property listeners:

  const matchersMixin = require('particl/dist/mixins/matchers');

  particl(
    [matchersMixin],
    async ({ onceMatch, set }) => {
      set('authStatus', { authenticated: false });

      ...

      const isAuthenticated = (authStatus) => (authStatus?.authenticated);
      await onceMatch('authStatus', isAuthenticated);
      // We only get here once the user is authenticated
    }
  );