solid-state-tools 1.4.0 → 1.4.1

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 createCouple} (for example usage)
+ */
+export type Writer<T> = (value: T) => void;
+export interface CoupleOptions {
+    /**
+     * @default true
+     */
+    memoized: boolean;
+}
+/**
+ * @description
+ * Create a signal from a getter setter pair.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#couples-createcouple)
+ *
+ * **The getter is immediately invoked for memoization.**
+ *
+ * @see {@link Accessor} (input), {@link Writer} (input), {@link Signal} (output)
+ *
+ * @example
+ * ```
+ * const [ count, setCount ] = createSignal(0);
+ * const [ double, setDouble ] = createCouple(() => count() * 2, (x) => setCount(x / 2));
+ *
+ * setDouble(x => x + 2);
+ * console.log(double(), count()); // 2 1
+ * ```
+ */
+export declare function createCouple<T>(getter: Accessor<T>, setter: Writer<T>, options?: CoupleOptions): 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(createCouple(...))`.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#atomic-couples-apair)
+ *
+ * @see {@link Accessor} (input), {@link Writer} (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>): 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,aAAa;IAC7B;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,CAmB1G;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,GAAG,IAAI,CAAC,CAAC,CAAC,CAExE"}

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#couples-createcouple)
+ *
+ * **The getter is immediately invoked for memoization.**
+ *
+ * @see {@link Accessor} (input), {@link Writer} (input), {@link Signal} (output)
+ *
+ * @example
+ * ```
+ * const [ count, setCount ] = createSignal(0);
+ * const [ double, setDouble ] = createCouple(() => count() * 2, (x) => setCount(x / 2));
+ *
+ * setDouble(x => x + 2);
+ * console.log(double(), count()); // 2 1
+ * ```
+ */
+export function createCouple(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(createCouple(...))`.
+ * [See documentation.](https://github.com/ReedSyllas/solid-state-tools#atomic-couples-apair)
+ *
+ * @see {@link Accessor} (input), {@link Writer} (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) {
+    return atom(createCouple(getter, setter));
+}
+//# 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,YAAY,CAAI,MAAmB,EAAE,MAAiB,EAAE,OAAuB;IAC9F,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;IAC9D,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/package.json

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