solid-state-tools 1.4.0 → 1.5.0

package/README.md

@@ -10,15 +10,12 @@ The package is small and only has a peer dependency of Solid JS.
 
 # Usage
 
-This library introduces some new primitives:
-
-1. [atom](#atoms-atom)
-2. [createCouple](#couples-createcouple)
-
-And, a few shorthand functions that combine these primitives and those from Solid JS together.
-
-1. [asig](#atomic-signals-asig)
-2. [apair](#atomic-couples-apair)
+| Utility                         | Summary                                          |
+| ------------------------------- | ------------------------------------------------ |
+| [atom](#atoms-atom)             | Combines a getter setter pair into one function. |
+| [createPair](#pairs-createpair) | Creates a signal from a getter setter pair.      |
+| [asig](#atomic-signals-asig)    | Shorthand for `atom(createSignal(...))`          |
+| [apair](#atomic-pairs-apair)    | Shorthand for `atom(createCouple(...))`          |
 
 Read the sections below for a breakdown of each utility.
 
@@ -69,7 +66,7 @@ const list = asig([], { equals: false });
 const list = atom(createSignal([], { equals: false }));
 ```
 
-## Couples (`createCouple`)
+## Pairs (`createPair`)
 
 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.
@@ -122,7 +119,7 @@ console.log(setDouble(20)); // 20
 
 But, the crusty boilerplate to get it working is annoying as heck.
 
-**Enter the `createCouple` utility.**
+**Enter the `createPair` utility.**
 
 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.
@@ -132,7 +129,7 @@ See it in action:
 ```ts
 const [ count, setCount ] = createSignal(0);
 
-const [ double, setDouble ] = createCouple(
+const [ double, setDouble ] = createPair(
 	// The provided getter is automatically memoized.
 	() => count() * 2,
 	
@@ -155,32 +152,32 @@ 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));
+const [ double, setDouble ] = createPair(() => count() * 2, (x) => setCount(x / 2));
 ```
 
 Much better, right?
 
 > [!NOTE]
-> The getter passed to `createCouple` is [memoized](https://docs.solidjs.com/concepts/derived-values/memos) unless otherwise set in the `options`.
+> The getter passed to `createPair` 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! 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.
+By the way! The `createPair` 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(() => count() * 2, (x) => setCount(x / 2)));
+const double = atom(createPair(() => count() * 2, (x) => setCount(x / 2)));
 
 double()   // read
 double(10) // write
 ```
 
-## Atomic couples (`apair`)
+## Atomic pairs (`apair`)
 
-Similar to [atomic signals](#atomic-signals-asig), wrapping a `createCouple` call with `atom` is a common enough pattern to warrant a shorthand: `apair`.
+Similar to [atomic signals](#atomic-signals-asig), wrapping a `createPair` call with `atom` is a common enough pattern to warrant a shorthand: `apair`.
 
 ```ts
 const double = apair(() => count() * 2, (double) => count(double / 2));
 // is short for
-const double = atom(createCouple(() => count() * 2, (double) => count(double / 2)));
+const double = atom(createPair(() => count() * 2, (double) => count(double / 2)));
 ```
 
 # Conclusion

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import { type Accessor, type Signal, type SignalOptions } from "solid-js";
+/**
+ * @description
+ * Any tuple of two functions where the first accepts no arguments and the second accepts any amount.
+ *
+ * Used as the source of an {@link Atom}.
+ *
+ * @see {@link Atom}, {@link atom}
+ */
+export type SignalLike = readonly [() => any, (...args: any) => any];
+/**
+ * @description
+ * An {@link 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 with all arguments forwarded to it.
+ *
+ * @see {@link SignalLike}, {@link atom} (constructor)
+ */
+export type Atom<T extends SignalLike = SignalLike> = T[0] & T[1];
+/**
+ * @description
+ * Combine a getter and setter function pair into one.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#atoms-atom)
+ *
+ * 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.
+ *
+ * @see {@link SignalLike} (input), {@link Atom} (output)
+ *
+ * @example
+ * ```
+ * const count: Atom<Signal<T>> = atom(createSignal(0));
+ *
+ * // Read
+ * count();
+ *
+ * // Write
+ * count(100);
+ * count(x => x + 1);
+ * count(count() + 1);
+ * ```
+ */
+export declare function atom<const T extends SignalLike>(signal: T): Atom<T>;
+/**
+ * @description
+ * Similar to a signal setter, except it doesn't accept a mapping function nor return a result.
+ *
+ * @see {@link createPair} (for example usage)
+ */
+export type Writer<T> = (value: T) => void;
+export interface PairOptions {
+    /**
+     * @default true
+     */
+    memoized: boolean;
+}
+/**
+ * @description
+ * Create a signal from a getter setter pair.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#pairs-createpair)
+ *
+ * **The getter is immediately invoked for memoization.**
+ *
+ * @see {@link Accessor} (input), {@link Writer} (input), {@link PairOptions} (input), {@link Signal} (output)
+ *
+ * @example
+ * ```
+ * const [ count, setCount ] = createSignal(0);
+ * const [ double, setDouble ] = createPair(() => count() * 2, (x) => setCount(x / 2));
+ *
+ * setDouble(x => x + 2);
+ * console.log(double(), count()); // 2 1
+ * ```
+ */
+export declare function createPair<T>(getter: Accessor<T>, setter: Writer<T>, options?: PairOptions): Signal<T>;
+/**
+ * @description
+ * An atomic signal. A signal where the getter and setter are combined into one function.
+ *
+ * @see {@link Atom}, {@link asig} (constructor)
+ */
+export type Asig<T> = Atom<Signal<T>>;
+/**
+ * @description
+ * Create an atomic signal. Short for `atom(createSignal(...))`.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#atomic-signals-asig)
+ *
+ * @see {@link Asig} (output), {@link Atom}, {@link atom}
+ *
+ * @example
+ * ```
+ * const count = asig(0);
+ *
+ * count(10);
+ * console.log(count()); // 10
+ *
+ * count(x => x + 10);
+ * console.log(count()); // 20
+ * ```
+ */
+export declare function asig<T>(value: T, options?: SignalOptions<T>): Asig<T>;
+export declare function asig<T>(): Asig<T | undefined>;
+/**
+ * @description
+ * Create an atomic getter setter pair. Short for `atom(createPair(...))`.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#atomic-pairs-apair)
+ *
+ * @see {@link Accessor} (input), {@link Writer} (input), {@link PairOptions} (input), {@link Asig} (output)
+ *
+ * @example
+ * ```
+ * const count = asig(0);
+ * const double = apair(() => count() * 2, (x) => count(x / 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: Writer<T>, options?: PairOptions): Asig<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,QAAQ,EAAe,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAK1H;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,CAAE,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAE,CAAC;AAEvE;;;;;;;;;GASG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAiBnE;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAE3C,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,CAmBtG;AAID;;;;;GAKG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AACvE,wBAAgB,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAK/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC,CAAC,CAAC,CAE/F"}

package/dist/index.js

@@ -0,0 +1,107 @@
+import { createMemo, createSignal, untrack } from "solid-js";
+import { isDev } from "solid-js/web";
+/**
+ * @description
+ * Combine a getter and setter function pair into one.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#atoms-atom)
+ *
+ * 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.
+ *
+ * @see {@link SignalLike} (input), {@link Atom} (output)
+ *
+ * @example
+ * ```
+ * const count: Atom<Signal<T>> = atom(createSignal(0));
+ *
+ * // Read
+ * count();
+ *
+ * // Write
+ * count(100);
+ * count(x => x + 1);
+ * count(count() + 1);
+ * ```
+ */
+export function atom(signal) {
+    if (isDev) {
+        // Assert that the input is valid.
+        // For production, these checks are skipped for performance.
+        if (!Array.isArray(signal)) {
+            throw new Error(`expected a getter setter pair as an array, but got ${typeof signal}`);
+        }
+        if (typeof signal[0] !== "function") {
+            throw new Error(`expected a getter function, but got ${typeof signal[0]}`);
+        }
+        if (typeof signal[1] !== "function") {
+            throw new Error(`expected a setter function, but got ${typeof signal[1]}`);
+        }
+    }
+    const [getter, setter] = signal;
+    return (...args) => (args.length === 0) ? getter() : setter(...args);
+}
+/**
+ * @description
+ * Create a signal from a getter setter pair.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#pairs-createpair)
+ *
+ * **The getter is immediately invoked for memoization.**
+ *
+ * @see {@link Accessor} (input), {@link Writer} (input), {@link PairOptions} (input), {@link Signal} (output)
+ *
+ * @example
+ * ```
+ * const [ count, setCount ] = createSignal(0);
+ * const [ double, setDouble ] = createPair(() => count() * 2, (x) => setCount(x / 2));
+ *
+ * setDouble(x => x + 2);
+ * console.log(double(), count()); // 2 1
+ * ```
+ */
+export function createPair(getter, setter, options) {
+    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 = options?.memoized === false ? getter : 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));
+}
+/**
+ * @description
+ * Create an atomic getter setter pair. Short for `atom(createPair(...))`.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#atomic-pairs-apair)
+ *
+ * @see {@link Accessor} (input), {@link Writer} (input), {@link PairOptions} (input), {@link Asig} (output)
+ *
+ * @example
+ * ```
+ * const count = asig(0);
+ * const double = apair(() => count() * 2, (x) => count(x / 2));
+ *
+ * count(10);
+ * console.log(count(), double()); // 10 20
+ *
+ * double(100);
+ * console.log(count(), double()); // 50 100
+ * ```
+ */
+export function apair(getter, setter, options) {
+    return atom(createPair(getter, setter, options));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAA+D,MAAM,UAAU,CAAC;AAC1H,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AA0BrC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,IAAI,CAA6B,MAAS;IACzD,IAAI,KAAK,EAAE,CAAC;QACX,kCAAkC;QAClC,4DAA4D;QAE5D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,sDAAsD,OAAO,MAAM,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,uCAAuC,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,uCAAuC,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5E,CAAC;IACF,CAAC;IACD,MAAM,CAAE,MAAM,EAAE,MAAM,CAAE,GAAG,MAAM,CAAC;IAClC,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;AACjF,CAAC;AAiBD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CAAI,MAAmB,EAAE,MAAiB,EAAE,OAAqB;IAC1F,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,OAAO,EAAE,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACtE,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;AAgCD,MAAM,UAAU,IAAI,CAAI,KAAqB,EAAE,OAAsC;IACpF,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,KAAK,CAAI,MAAmB,EAAE,MAAiB,EAAE,OAAqB;IACrF,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAClD,CAAC"}

package/package.json

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