DerivableJS API

Creates a new derivation based on the application of f to the current value of this derivable. e.g.

const x = atom(4);
const timesTwo = (n) => n * 2;
const xTimesTwo = x.derive(timesTwo);

xTimesTwo.get();
// => 8

Creates a new derivation based on property lookup. e.g.

const obj = atom({foo: 'FOO!', bar: 'BAR!'});
const foo = obj.derive('foo');

foo.get();
// => 'FOO!'

const obj = atom({foo: 'FOO!', bar: 'BAR!'});
const prop = atom('foo');
const item = obj.derive(prop);

item.get();
// => 'FOO!'

prop.set('bar');
item.get();
// => 'BAR!'

Creates a new derivation based on index lookup. e.g.

const arr = atom(['one', 'two', 'three']);
const middle = arr.derive(1);

middle.get();
// => 'two'

const arr = atom(['one', 'two', 'three']);
const idx = atom(0);
const item = arr.derive(idx);

item.get();
// => 'one'

idx.set(1);
item.get();
// => 'two'

Creates a new derivation based on regexp matching. e.g.

const str = atom('hello there');
const match = str.derive(/\w+/g);

match.get()
// => ['hello', 'there']

const str = atom('hello there');
const re = atom(/\w+/);
const match = str.derive(re);

match.get()
// => [ 'hello', index: 0, input: 'hello there' ]

re.set(/e.*?\b/g);
match.get()
// => ['ello', 'ere']

Creates a new derivation based on the application of f to the current value of this derivable. e.g.

const x = atom(4);
const timesTwo = (n) => n * 2;
const timesFour = (n) => n * 4;
const f = atom(timesTwo);
const fx = x.derive(f);

fx.get();
// => 8

f.set(timesFour);
fx.get();
// => 16

Lets one combine all the above and destructure the result. e.g.

const x = atom('hello there');
const index = atom(0);

const [words, len, upper, char] = x.derive([
  /\w+/g, 'length', s => s.toUpperCase(), index
]);

words.get();
// => ['hello', 'there']

len.get();
// => 11

upper.get();
// => 'HELLO THERE'

char.get();
// => 'h'

index.set(2);
char.get();
// => 'l'

Creates a new derivation based on the application of f to the current value of this derivable and a. e.g.

const x = atom(4);
const times = (a, b) => a * b;
const xTimesTwo = x.derive(times, 2);

xTimesTwo.get();
// => 8

const y = atom(5);
const xTimesY = x.derive(times, y);

xTimesY.get();
// => 20

y.set(10);
xTimesY.get();
// => 40

Any-arity version of above. Unpacks all args.

nil-shortcutting version of derive. e.g.

const x = atom(null);
const timesTwo = (n) => n * 2;
const xTimesTwo = x.derive(timesTwo);
const mXTimesTwo = x.mDerive(timesTwo);

mXTimesTwo.get();
// => null

xTimesTwo.get();
// throws error because we try to multiply null by 2

Declares an anonymous reactor based on f being applied to this derivable.

The default lifecycle options are:

{
  from: true,   // i.e. the reactor is initialized immediately
  when: true,   // i.e. the reactor is always active
  until: false, // i.e. the reactor is never killed
  skipFirst: false,
  once: false
}

e.g.

const n = atom(0);

n.react(n => console.log(`n is ${n}`), {
  from: () => n.get() > 0,      // start when n > 0
  when: () => n.get() %2 === 0, // only react when n is even
  until: () => n.get() => 5     // stop when n >= 5
});
// ... no output

n.set(1);
// ... no output (n is odd)

n.set(2);
// $> n is 2

n.set(3);
// ... no output (n is odd)

n.set(4);
// $> n is 4

n.set(5);
// ... no output (reactor was killed)

n.set(4);
// ... no output (reactors don't come back from the dead)

Returns the current value of this derivable.

const x = atom(`a string`);
x.get();
// => 'a string'

Returns a derivable which represents the equality of the values held in this and other.

let a = atom(`a`),
    b = atom(`b`);

let same = a.is(b);

same.get();
// => false

b.set(`a`);

same.get();
// => true

Returns a derivable which represents the boolean AND composition of the values held in this and other.

const condition = atom(`truthy value`);

const result = condition.and(`yes truthy`);

result.get();
// => `yes truthy`

condition.set(false);

result.get();
// => false

other can be a derivable.

const result2 = result.and(condition.derive(s => s.split(` `)[0]));

result2.get();
// => false

condition.set(`some string`);

result2.get();
// => `some`

Due to derivable's laziness, we can be sure that the derivation of condition (the string splitting bit) will only ever be evaluated when condition contains a truthy value.

Returns a derivable which represents other iff this derivable doesn't represent null or undefined. Otherwise the returned derivable representsthe same value as this derivable.

Returns a derivable which represents the boolean OR composition of the values held in this and other.

const first = atom(`truthy value`);
const second = atom(false);

first.or(second).get();
// => `truthy value`

second.or(first).get();
// => `truthy value`

first.set(false);

second.or(first).get();
// => false

first.set(`first`);
second.set(`second`);

first.or(second).get();
// => `first`

second.or(first).get();
// => `second`

Returns a derivable which represents other iff this derivable represents null or undefined. Otherwise represents the same value as this derivable

Returns a derivable which represents the value of thenD if this is truthy, or elseD otherwise.

Equivalent to:

this.and(thenD).or(elseD);

Returns a derivable which represents the value of thenD if this is not null or undefined, otherwise elseD.

Returns a derivable which represents the boolean complement of the truthiness of the the value represented by this.

Equivalent to:

this.derive(x => !x);

…args is a flat list of (comparatee, value) pairs. If the value represented by this derivable is equal to a comparatee (which can be derivable or not), a derivable representing the comparatee's corresponding value is returned. If none match, the value represented is undefined unless a trailing value is supplied.

const x = atom(3);

const y = x.switch(
  1, `one`,
  2, `two`,
  3, `three`
);

y.get();
// => `three`

x.set(4);

y.get();
// => undefined

const z = x.switch(
  5, `five`,
  6, `six`,
  `other`
);

z.get();
// => `other`

Returns an copy of this derivable, except the equality checking logic is provided by equals.

DerivableJS provides strict equality checking by default, delegating to a .equals method if present. But if e.g. you need deep equality checking for plain objects as provided by some deepEquals function:

const $SomeState = atom({blah: true})
  .withEquality(deepEquals);

$SomeState.reactor(() => console.log('side effects!')).start();

$SomeState.set({blah: true});
// no side effects occurred!

Creates a link between r and this derivable. r should be a 'fresh' reactor. i.e. it should not have been linked to any other derivable in the past. For examples see Reactor.

Only use this if Lifecycle doesn't fit your needs.

Creates and returns a new Reactor based on f being applied to this derivable. e.g.

Only use this if Lifecycle doesn't fit your needs.

const x = atom(4);
const r = x.reactor(x => console.log(`x is`, x));

x.set(8);

// .reactor creats the reactor, but doesn't start it,
// so nothing gets printed yet

r.start();

// now that the reactor has started it will respond
// to changes in x

x.set(16);
// $> x is 16

x.set(32);
// $> x is 32

Sets the value of this atom to be value, returns this atom

Sets the value of this atom to be the value returned when f is applied to the current value of this and …args. Returns this.

Equivalent to:

this.set(f.apply(null, [this.get()].concat(args)));

Returns a new atom connected to this one via the logic encapsulated by lens.

Returns the lensed value extracted from source.

Called with this set to null.

Returns the transformed version of source which includes value.

Called with this set to null.

Should dereference one or more derivables to return a value of type T

Should propagate value back up to any relevant atoms.

Runs all pending reactions

Releases this ticker, rendering it useless