Solid State Tools

Links: GitHub Repository, NPM Package.

Solid State Tools is a collection of simple utilities for managing Solid JS state.

All features are intended to compliment Solid JS's existing state system, building upon the existing foundation.

The package is small and only has a peer dependency of Solid JS.

Usage

This library introduces some new primitives:

1. atom
2. createCouple

And, a few shorthand functions that combine these primitives and those from Solid JS together.

1. asig
2. apair

Read the sections below for a breakdown of each utility.

Atoms (atom)

Atoms combine the getter and setter of a signal into one function.

const count: Atom<Signal<number>> = atom(createSignal(0));

console.log(count()); // 0

count(100);
console.log(count()); // 100

count(count() + 1);
console.log(count()); // 101

count((c) => c + 1);
console.log(count()); // 102

When called with no arguments, the atom acts like the signal's getter. If an argument is passed, it is forwarded to the signal's setter. Note that undefined is considered an argument and is forwarded to the setter.

Atoms simplify the boilerplate that comes with managing separate getters and setters. However, signals are still preferred when granular control of the getter and setter is needed. Additionally, atoms incur a tiny performance cost. Thus, atoms do not replace signals. They coexist.

Atomic signals (asig)

Creating a signal and immediately 'atomizing' it is a common pattern. The asig function was created for this, along with its related type Asig.

const count: Asig<number> = asig(0);
// is short for
const count: Atom<Signal<number>> = atom(createSignal(0));

The second parameter (optional) is the config object, which is simply forwarded to the createSignal call.

const list = asig([], { equals: false });
// is short for
const list = atom(createSignal([], { equals: false }));

Couples (createCouple)

A signal can be summarized as a getter setter pair. However, the setter of a Solid JS signal is more complex than it appears at first glance. Why?

1. It accepts a function which transforms the previous value into the new one.

   setCount(x => x + 1);

2. It also returns the value.

   const [ _count, setCount ] = createSignal(0);
   
   console.log(setCount(10));         // Prints: 10
   console.log(setCount(x => x + 5)); // Prints: 15

All of this is to say that creating custom signal pairs can be tedious. Below is an example showing the complexity involved.

const [ count, setCount ] = createSignal(0);

const [ double, setDouble ] = [
	// The getter
	createMemo(() => count() * 2),
	
	// The setter
	(newValue: number | ((prev: number) => number)) => {
		
		// The function case must be handled.
		const unwrappedNewValue = (typeof newValue === "function") ? newValue(untrack(double)) : newValue;
		
		setCount(unwrappedNewValue / 2);
		
		// And the result must be returned.
		return unwrappedNewValue;
	},
];

With that, the following statements work (as is expected of a setter):

setDouble(10);              // double: 10, count: 5
setDouble(x => x + 1);      // double: 11, count: 5.5
console.log(setDouble(20)); // Prints: 20

But, the crusty boilerplate to get it working is annoying as heck.

Enter the createCouple utility.

It accepts a getter and a co-setter and returns a signal. A co-setter is similar to a setter, except that it doesn't take a function nor does it return a value. Basically, it's the previous example without the boilerplate. See it in action:

const [ count, setCount ] = createSignal(0);

const [ double, setDouble ] = createCouple(
	() => count() * 2,
	
	(newValue) => {
		// Notice how we don't need to handle `newValue` being a function here.
		setCount(newValue / 2);
		
		// Nor do we need to return anything.
	},
);

// Yet, we can still pass a function in.
setDouble(x => x + 2);
console.log(double(), count()); // 2 1

// Or use its return value.
console.log(setDouble(10), count()); // 10 5

Much better, right?

[!NOTE] The getter passed to createCouple is always memoized. This immediately invokes the getter, so keep that in mind.

By the way! A createCouple call, like any expression that evaluates to a signal, can be converted into an atom so that the getter and setter are merged into one.

const double = atom(createCouple(/* ... */));

Atomic couples (apair)

Similar to atomic signals, wrapping a createCouple call with atom is a common enough pattern to warrant a shorthand: apair.

const double = apair(() => count() * 2, (double) => count(double / 2));
// is short for
const double = atom(createCouple(() => count() * 2, (double) => count(double / 2)));

Conclusion

Perhaps you can see the power of the above primitives. Not only in what they do, but also in how they combine.

More utilities for this library are in the works and will be coming soon.