@figliolia/galena 3.0.2 → 3.0.3

package/src/Galena.ts

@@ -1,27 +1,30 @@
 import { EventEmitter } from "@figliolia/event-emitter";
 import type { Middleware } from "./Middleware";
 import type { State } from "./State";
-import type { AppSubscriber, GalenaSnapshot, StateTypes } from "./types";
+import type {
+  AppSubscriber,
+  GalenaSnapshot,
+  Setter,
+  StateType,
+  StateTypes,
+} from "./types";
 
 /**
- * Galena
+ * ### Galena
  *
- * Galena is designed to house one or more units of `State`
+ * Galena instances are designed to house one or more units of `State`
  * and exist as a pseudo global application state.
  *
  * By design, each of its `State` units have isolated reactivity
  * that prevents entire state trees from updating when a single
  * unit changes.
  *
- * This is dissimilar to redux-like models where downstream reconciliations
- * will propagate everwhere a given store is read from. In galena, downstream
- * reconciliations occur only for consumers of the slice of state that
- * changed - making it safer to use with more frequent state changes.
- *
  * ```typescript
  * import { Galena } from "@figliolia/galena";
  *
  * const AppState = new Galena({
+ *   user: new State("<user-stuff>"),
+ *   business: new State("<business-logic-stuff>")
  *   // your reactive instances
  * }, ...middleware);
  *
@@ -29,8 +32,9 @@ import type { AppSubscriber, GalenaSnapshot, StateTypes } from "./types";
  * const myUnit = AppState.get("<key>"); // Returns State<T>
  *
  * // to run a callback anytime a unit of state changes
- * const unsubscribe = AppState.subscribe(({ updated }) => {
+ * const listener = AppState.subscribe(({ state, updated }) => {
  *   // do something with the `State` instance that updated
+ *   // the entirety of your state
  * });
  * ```
  */
@@ -43,10 +47,47 @@ export class Galena<T extends Record<string, State<any>>> {
     this.registerMiddleware(...middleware);
   }
 
+  /**
+   * Get
+   *
+   * Returns a connected State instance by key
+   */
   public get<K extends Extract<keyof T, string>>(key: K) {
     return this.state[key];
   }
 
+  /**
+   * Set
+   *
+   * Sets a connected State instance's state by key
+   */
+  public set<K extends Extract<keyof T, string>>(
+    key: K,
+    value: StateType<T[K]>,
+  ) {
+    return this.get(key).set(value);
+  }
+
+  /**
+   * Update
+   *
+   * Invokes a connected State instance's update method key
+   */
+  public update<K extends Extract<keyof T, string>>(
+    key: K,
+    updater: Setter<StateType<T[K]>>,
+  ) {
+    return this.get(key).update(updater);
+  }
+
+  /**
+   * Subscribe
+   *
+   * Listen for changes on your Galena instnace. Your provided
+   * callback will be invoked each time an attached state instance
+   * changes. To your callback will be provided the `updated` state
+   * instance, along with the entire `state` tree
+   */
   public subscribe = (subscriber: AppSubscriber<T>) => {
     const ID = this.Emitter.on("change", subscriber);
     const unsubscribers: (() => void)[] = [];
@@ -69,6 +110,12 @@ export class Galena<T extends Record<string, State<any>>> {
     };
   };
 
+  /**
+   * Register Middleware
+   *
+   * Adds middleware instances to each of the connected
+   * `State` instances
+   */
   public registerMiddleware(...middlewares: Middleware<StateTypes<T>>[]) {
     for (const key in this.state) {
       this.state[key]?.registerMiddleware?.(...middlewares);
@@ -83,24 +130,21 @@ export class Galena<T extends Record<string, State<any>>> {
 }
 
 /**
- * Create Galena
+ * ### createGalena
  *
- * Galena is designed to house one or more units of `State`
+ * Galena instances are designed to house one or more units of `State`
  * and exist as a pseudo global application state.
  *
  * By design, each of its `State` units have isolated reactivity
  * that prevents entire state trees from updating when a single
  * unit changes.
  *
- * This is dissimilar to redux-like models where downstream reconciliations
- * will propagate everwhere a given store is read from. In galena, downstream
- * reconciliations occur only for consumers of the slice of state that
- * changed - making it safer to use with more frequent state changes.
- *
  * ```typescript
- * import { createGalena } from "@figliolia/galena";
+ * import { Galena } from "@figliolia/galena";
  *
- * const AppState = createGalena({
+ * const AppState = new Galena({
+ *   user: new State("<user-stuff>"),
+ *   business: new State("<business-logic-stuff>")
  *   // your reactive instances
  * }, ...middleware);
  *
@@ -108,8 +152,9 @@ export class Galena<T extends Record<string, State<any>>> {
  * const myUnit = AppState.get("<key>"); // Returns State<T>
  *
  * // to run a callback anytime a unit of state changes
- * const unsubscribe = AppState.subscribe(({ updated }) => {
+ * const listener = AppState.subscribe(({ state, updated }) => {
  *   // do something with the `State` instance that updated
+ *   // the entirety of your state
  * });
  * ```
  */

package/src/State.ts

@@ -3,7 +3,7 @@ import type { Middleware } from "./Middleware";
 import type { NonFunction, Setter, Subscriber } from "./types";
 
 /**
- * State
+ * ### State
  *
  * The unit of reactivity for Galena. `State`'s can act
  * as isolated instances or be part of your global app
@@ -12,7 +12,7 @@ import type { NonFunction, Setter, Subscriber } from "./types";
  * There are three ways to create state instances
  *
  * ```typescript
- * import { State, createState, useState, Profiler } from "@figliolia/galena";
+ * import { State, createState, Profiler } from "@figliolia/galena";
  * // for island states that can be shared between react components
  * const myState = new State("<any value>", ...middleware);
  * // or
@@ -22,17 +22,7 @@ import type { NonFunction, Setter, Subscriber } from "./types";
  * myState.update(previousValue => "<new-value>");
  * myState.subscribe(nextValue => {});
  * myState.registerMiddleware(new Profiler());
- *
- * // Similarly if you wish to use your state inside a react component
- * const MyComponent = () => {
- *   const [state, setState] = useState(myState);
- *   // or
- *   const [state, setState] = useMyState("<any-value>", ...middlware);
- *
- *   return (
- *      // your jsx
- *   );
- * }
+ * myState.reset(); // reset back to it's original value
  * ```
  */
 export class State<T> {
@@ -143,21 +133,26 @@ export class State<T> {
 }
 
 /**
- * Create State
+ * ### createState
  *
- * Returns the unit of reactivity for Galena. `State`'s can act
+ * The unit of reactivity for Galena. `State`'s can act
  * as isolated instances or be part of your global app
- * state (via `Galena` instances);
+ * state (via `Galena` instances).
  *
- * ```typescript
- * import { createState, Profiler } from "@figliolia/galena";
+ * There are three ways to create state instances
  *
+ * ```typescript
+ * import { State, createState, Profiler } from "@figliolia/galena";
+ * // for island states that can be shared between react components
+ * const myState = new State("<any value>", ...middleware);
+ * // or
  * const myState = createState("<any value>", ...middleware);
  *
  * myState.set("<new-value>");
  * myState.update(previousValue => "<new-value>");
  * myState.subscribe(nextValue => {});
  * myState.registerMiddleware(new Profiler());
+ * myState.reset(); // reset back to it's original value
  * ```
  */
 export function createState<T>(

package/src/types.ts

@@ -24,5 +24,7 @@ export type AppSubscriber<
 > = ((payload: GalenaSnapshot<T, K>) => void) | (() => void);
 
 export type StateTypes<T extends Record<string, State<any>>> = ReturnType<
-  T[keyof T]["getSnapshot"]
+  StateType<T[keyof T]>
 >;
+
+export type StateType<T extends State<any>> = ReturnType<T["getSnapshot"]>;