solid-state-tools 1.3.0 → 1.4.0

package/README.md

@@ -1,5 +1,7 @@
 # Solid State Tools
 
+Links: [GitHub Repository](https://github.com/ReedSyllas/solid-state-tools), [NPM Package](https://www.npmjs.com/package/solid-state-tools).
+
 Solid State Tools is a collection of simple utilities for managing [Solid JS](https://docs.solidjs.com/) state.
 
 All features are intended to compliment Solid JS's existing state system, building upon the existing foundation.
@@ -29,12 +31,15 @@ const count: Atom<Signal<number>> = atom(createSignal(0));
 
 console.log(count()); // 0
 
+// Sets count to 100.
 count(100);
 console.log(count()); // 100
 
+// Sets count to its current value plus one.
 count(count() + 1);
 console.log(count()); // 101
 
+// Sets count to its current value plus one (alternative syntax).
 count((c) => c + 1);
 console.log(count()); // 102
 ```
@@ -56,6 +61,14 @@ const count: Asig<number> = asig(0);
 const count: Atom<Signal<number>> = atom(createSignal(0));
 ```
 
+The second parameter (optional) is the config object, which is simply forwarded to [createSignal's options](https://docs.solidjs.com/reference/basic-reactivity/create-signal#options).
+
+```ts
+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.
@@ -71,8 +84,8 @@ Why?
 	```ts
 	const [ _count, setCount ] = createSignal(0);
 
-	console.log(setCount(10));         // Prints: 10
-	console.log(setCount(x => x + 5)); // Prints: 15
+	console.log(setCount(10));         // 10
+	console.log(setCount(x => x + 5)); // 15
 	```
 
 All of this is to say that creating custom signal pairs can be tedious.
@@ -99,26 +112,28 @@ const [ double, setDouble ] = [
 ];
 ```
 
-With that, all of the statements below work exactly as expected.
+With that, the following statements work (as is expected of a setter):
 
 ```ts
 setDouble(10);              // double: 10, count: 5
 setDouble(x => x + 1);      // double: 11, count: 5.5
-console.log(setDouble(20)); // Prints: 20
+console.log(setDouble(20)); // 20
 ```
 
-But, wouldn't it be convenient if we could skip the crusty boilerplate?
+But, the crusty boilerplate to get it working is annoying as heck.
 
-**Enter the `createCouple` utility**
+**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 the following example:
+It accepts a getter and a writer and returns a signal.
+A writer is similar to a setter, except that it doesn't accept a function as input nor does it return a value.
+Basically, it's the setter of the previous example without all the boilerplate.
+See it in action:
 
 ```ts
 const [ count, setCount ] = createSignal(0);
 
 const [ double, setDouble ] = createCouple(
+	// The provided getter is automatically memoized.
 	() => count() * 2,
 	
 	(newValue) => {
@@ -129,7 +144,7 @@ const [ double, setDouble ] = createCouple(
 	},
 );
 
-// Yet, we can still pass a function in.
+// Yet, we can still inject a function.
 setDouble(x => x + 2);
 console.log(double(), count()); // 2 1
 
@@ -137,16 +152,25 @@ console.log(double(), count()); // 2 1
 console.log(setDouble(10), count()); // 10 5
 ```
 
+It can be succinctly rewritten into this:
+
+```ts
+const [ double, setDouble ] = createCouple(() => count() * 2, (x) => setCount(x / 2));
+```
+
 Much better, right?
 
 > [!NOTE]
-> The getter passed to `createCouple` is always memoized.
-> This has the consequence that the getter is invoked immediately during creation of the couple.
+> The getter passed to `createCouple` is [memoized](https://docs.solidjs.com/concepts/derived-values/memos) unless otherwise set in the `options`.
+> Memoization immediately invokes the getter, so keep that in mind because it can cause undesirable side-effects.
 
-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.
+By the way! The `createCouple` output, like any signal, can be converted into an atom so that the getter and setter are merged together. See [atom](#atoms-atom) for details.
 
 ```ts
-const double = atom(createCouple(/* ... */));
+const double = atom(createCouple(() => count() * 2, (x) => setCount(x / 2)));
+
+double()   // read
+double(10) // write
 ```
 
 ## Atomic couples (`apair`)
@@ -162,6 +186,6 @@ 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.
+Not just what they do individually, but how they work together.
 
-More utilities for this library are in the works and will be coming soon.
+More utilities for this library are in the works and are coming soon.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-state-tools",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A collection of Solid JS state utilities",
   "author": "Reed Syllas <reedsyllas@gmail.com>",
   "license": "ISC",

package/dist/atom.d.ts

@@ -1,95 +0,0 @@
-import { type Accessor, type Signal, type SignalOptions } from "solid-js";
-/**
- * Any tuple of two functions where the first accepts no arguments and the second accepts any amount.
- */
-export type SignalLike = readonly [() => any, (...args: any) => any];
-/**
- * An atom is a polymorphic function that calls one of two
- *  functions depending on the number of arguments it has.
- *
- * If called with zero arguments, the first function is called.
- * Otherwise, the second function is called and all of the arguments are forwarded to it.
- */
-export type Atom<T extends SignalLike = SignalLike> = T[0] & T[1];
-/**
- * Combine a getter and setter function pair into one.
- *
- * Accepts a tuple of two functions.
- * The first is the getter, the second is the setter.
- * A new function is returned that, when called with zero arguments, calls the getter.
- * Otherwise, it calls the setter and forwards all of the arguments.
- *
- * ### Example
- * ```
- * const count = atom(createSignal(0));
- *
- * // Read
- * count();
- *
- * // Write
- * count(100);
- * count(x => x + 1);
- * count(count() + 1);
- * ```
- */
-export declare function atom<const T extends SignalLike>(value: T): Atom<T>;
-/**
- * Similar to a signal setter, except it doesn't accept a mapping function nor return a result.
- */
-export type Cosetter<T> = (value: T) => void;
-/**
- * Create a signal from a cosignal.
- *
- * ### Example
- * ```
- * const [ count, setCount ] = createSignal(0);
- * const [ double, setDouble ] = createSignalPair([
- * 	() => count() * 2,
- * 	(x) => void setCount(x / 2),
- * ]);
- *
- * double(x => x + 2);
- * console.log(double(), count()); // 2 1
- * ```
- */
-export declare function createCouple<T>(getter: Accessor<T>, setter: Cosetter<T>): Signal<T>;
-/**
- * An atomic signal.
- * A signal where the getter and setter are combined into one function.
- */
-export type Asig<T> = Atom<Signal<T>>;
-/**
- * Create an atomic signal.
- * Short for `atom(createSignal(...))`.
- *
- * ### Example
- * ```
- * const count = asig(0);
- *
- * count(10);
- * console.log(count()); // 10
- *
- * count(x => x + 10);
- * console.log(count()); // 20
- * ```
- */
-export declare function asig<T>(): Asig<T | undefined>;
-export declare function asig<T>(value: T, options?: SignalOptions<T>): Asig<T>;
-/**
- * Create an atomic cosignal pair.
- * Short for `atom(createCouple(...))`.
- *
- * ### Example
- * ```
- * const count = asig(0);
- * const double = apair(() => count() * 2, (double) => void count(double / 2));
- *
- * count(10);
- * console.log(count(), double()); // 10 20
- *
- * double(100);
- * console.log(count(), double()); // 50 100
- * ```
- */
-export declare function apair<T>(getter: Accessor<T>, setter: Cosetter<T>): Asig<T>;
-//# sourceMappingURL=atom.d.ts.map

package/dist/atom.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"atom.d.ts","sourceRoot":"","sources":["../src/atom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,QAAQ,EAAe,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAK1H;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,CAAE,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAE,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAmBpE;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAE7C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAmBnF;AAID;;;GAGG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAC/C,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAKvE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAE1E"}

package/dist/atom.js

@@ -1,75 +0,0 @@
-import { createMemo, createSignal, untrack } from "solid-js";
-import { isDev } from "solid-js/web";
-export function atom(value) {
-    if (isDev) {
-        // Assert that the input is valid.
-        // For production, these checks are skipped for performance.
-        if (!Array.isArray(value)) {
-            throw new Error(`expected a getter setter pair as an array, but got ${typeof value}`);
-        }
-        if (typeof value[0] !== "function") {
-            throw new Error(`expected a getter function, but got ${typeof value[0]}`);
-        }
-        if (typeof value[1] !== "function") {
-            throw new Error(`expected a setter function, but got ${typeof value[1]}`);
-        }
-    }
-    return (...args) => (args.length === 0) ? value[0]() : value[1](...args);
-}
-/**
- * Create a signal from a cosignal.
- *
- * ### Example
- * ```
- * const [ count, setCount ] = createSignal(0);
- * const [ double, setDouble ] = createSignalPair([
- * 	() => count() * 2,
- * 	(x) => void setCount(x / 2),
- * ]);
- *
- * double(x => x + 2);
- * console.log(double(), count()); // 2 1
- * ```
- */
-export function createCouple(getter, setter) {
-    if (isDev) {
-        // Assert that the input is valid.
-        // For production, these checks are skipped for performance.
-        if (typeof getter !== "function") {
-            throw new Error(`expected getter to be a function, but got ${typeof getter}`);
-        }
-        if (typeof setter !== "function") {
-            throw new Error(`expected setter to be a function, but got ${typeof setter}`);
-        }
-    }
-    const get = createMemo(getter);
-    const set = ((source) => {
-        const value = (typeof source === "function") ? source(untrack(get)) : source;
-        setter(value);
-        return value;
-    });
-    return [get, set];
-}
-export function asig(value, options) {
-    return atom(createSignal(value, options));
-}
-/**
- * Create an atomic cosignal pair.
- * Short for `atom(createCouple(...))`.
- *
- * ### Example
- * ```
- * const count = asig(0);
- * const double = apair(() => count() * 2, (double) => void count(double / 2));
- *
- * count(10);
- * console.log(count(), double()); // 10 20
- *
- * double(100);
- * console.log(count(), double()); // 50 100
- * ```
- */
-export function apair(getter, setter) {
-    return atom(createCouple(getter, setter));
-}
-//# sourceMappingURL=atom.js.map

package/dist/atom.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"atom.js","sourceRoot":"","sources":["../src/atom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAA+D,MAAM,UAAU,CAAC;AAC1H,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAwCrC,MAAM,UAAU,IAAI,CAAC,KAAc;IAClC,IAAI,KAAK,EAAE,CAAC;QACX,kCAAkC;QAClC,4DAA4D;QAE5D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,sDAAsD,OAAO,KAAK,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,uCAAuC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,uCAAuC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3E,CAAC;IACF,CAAC;IACD,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAE,KAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAE,KAAoB,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACrH,CAAC;AAOD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAI,MAAmB,EAAE,MAAmB;IACvE,IAAI,KAAK,EAAE,CAAC;QACX,kCAAkC;QAClC,4DAA4D;QAE5D,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,6CAA6C,OAAO,MAAM,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,6CAA6C,OAAO,MAAM,EAAE,CAAC,CAAC;QAC/E,CAAC;IACF,CAAC;IACD,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACvB,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,CAAE,MAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3F,MAAM,CAAC,KAAK,CAAC,CAAC;QACd,OAAO,KAAK,CAAC;IACd,CAAC,CAAc,CAAC;IAChB,OAAO,CAAE,GAAG,EAAE,GAAG,CAAW,CAAC;AAC9B,CAAC;AA2BD,MAAM,UAAU,IAAI,CAAI,KAAqB,EAAE,OAAsC;IACpF,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,KAAK,CAAI,MAAmB,EAAE,MAAmB;IAChE,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./atom.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -1,2 +0,0 @@
-export * from "./atom.js";
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}