solid-state-tools 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,78 @@
+# Solid JS State Tools
+
+This package is a collection of utilities for managing [Solid JS](https://docs.solidjs.com/) state.
+
+## Atoms (`atom`)
+
+Atoms combine the getter and setter of a [signal](https://docs.solidjs.com/concepts/signals) into one function.
+
+```ts
+const count = 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, as desired.
+
+Atoms simplify the boilerplate that comes with managing getters and setters separately. However, signals are still preferred for granular control of the getter and setter. Additionally, atoms incur a tiny performance cost. Thus, atoms do not replace signals. They coexist.
+
+## Atomic signals (`asig`)
+
+Because creating and wrapping a signal with `atom` is so common, a shorthand utility was created called `asig` (atomic signal).
+
+```ts
+const count = asig(0);
+// is a shorthand for
+const count = atom(createSignal(0));
+```
+
+## Co-signals (`createCosignal`)
+
+A signal can be summarized as a getter setter pair. However, Solid JS's setters are more complex than just a function that accepts a new value for the signal. They can also accept a function which acts like a map predicate from the old value to the new one.
+
+All this is to say that creating signals manually can be tedious since the setter has to handle this edge case. Co-signals make defining the getter setter pair easy.
+
+```ts
+const [ count, setCount ] = createSignal(0);
+const [ double, setDouble ] = createCosignal([
+	() => count() * 2,
+	
+	// Notice how we don't need to handle `x` being a function here.
+	(x) => void setCount(x / 2),
+]);
+
+// Yet, we can still pass a mapping function here.
+double(x => x + 2);
+console.log(double(), count()); // 12 6
+
+// Or simply use it traditionally.
+double(10);
+console.log(double(), count()); // 10 5
+```
+
+It's important to note that the getter is not automatically memoized and should be wrapped with `createMemo`, when appropriate.
+
+```ts
+const [ double, setDouble ] = createCosignal([
+	// Memoize to reduce extra computation.
+	createMemo(() => count() * 2),
+	/* ... */
+]);
+```
+
+Finally, co-signals can be wrapped with `atom`, of course.
+
+```ts
+const double = atom(createCosignal(/* ... */));
+```
+
+To be clear, `createCosignal` and `createSignal` return the same kind of value and therefore should work in every situation native signals do.

package/dist/atom.d.ts

@@ -8,12 +8,12 @@ export type Asig<T> = Atom<Signal<T>>;
  */
 export declare function asig<T>(): Atom<Signal<T | undefined>>;
 export declare function asig<T>(value: T, options?: SignalOptions<T>): Atom<Signal<T>>;
-export type Cosig<T> = [
+export type Cosignal<T> = [
     () => T,
     (value: T) => T
 ];
 /**
  * Creates a signal from a getter/setter pair.
  */
-export declare function cosig<T>(cosig: Cosig<T>): Signal<T>;
+export declare function createCosignal<T>(cosignal: Cosignal<T>): Signal<T>;
 //# sourceMappingURL=atom.d.ts.map

package/dist/atom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atom.d.ts","sourceRoot":"","sources":["../src/atom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAElF,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAE,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAE,CAAC;AAErE,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAUlE,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtC;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;AACvD,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAK/E,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI;IACtB,MAAM,CAAC;IACP,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAMnD"}
+{"version":3,"file":"atom.d.ts","sourceRoot":"","sources":["../src/atom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAElF,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAE,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAE,CAAC;AAErE,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D,wBAAgB,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAUlE,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEtC;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;AACvD,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAK/E,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACzB,MAAM,CAAC;IACP,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAMlE"}

package/dist/atom.js

@@ -13,8 +13,8 @@ export function asig(...args) {
 /**
  * Creates a signal from a getter/setter pair.
  */
-export function cosig(cosig) {
-    const [get, set] = cosig;
+export function createCosignal(cosignal) {
+    const [get, set] = cosignal;
     return [
         get,
         (value) => set((typeof value === "function") ? value(untrack(get)) : value),

package/dist/atom.js.map

@@ -1 +1 @@
-{"version":3,"file":"atom.js","sourceRoot":"","sources":["../src/atom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAmC,MAAM,UAAU,CAAC;AAOlF,MAAM,UAAU,IAAI,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YACtE,OAAO,CAAC,GAAG,IAAS,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/E,CAAC;IACF,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;AAC1D,CAAC;AASD,MAAM,UAAU,IAAI,CAAI,GAAG,IAA+C;IACzE,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,EAAK,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1F,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,KAAK,CAAI,KAAe;IACvC,MAAM,CAAE,GAAG,EAAE,GAAG,CAAE,GAAG,KAAK,CAAC;IAC3B,OAAO;QACN,GAAG;QACH,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,CAAE,KAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;KACvE,CAAC;AAChB,CAAC"}
+{"version":3,"file":"atom.js","sourceRoot":"","sources":["../src/atom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAmC,MAAM,UAAU,CAAC;AAOlF,MAAM,UAAU,IAAI,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YACtE,OAAO,CAAC,GAAG,IAAS,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/E,CAAC;IACF,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;AAC1D,CAAC;AASD,MAAM,UAAU,IAAI,CAAI,GAAG,IAA+C;IACzE,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,EAAK,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1F,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,cAAc,CAAI,QAAqB;IACtD,MAAM,CAAE,GAAG,EAAE,GAAG,CAAE,GAAG,QAAQ,CAAC;IAC9B,OAAO;QACN,GAAG;QACH,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,CAAE,KAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;KACvE,CAAC;AAChB,CAAC"}

package/package.json

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