@figliolia/galena 3.0.1 → 3.0.3

package/README.md

@@ -2,9 +2,26 @@
 
 Lightning fast, framework agnostic state, that doesn't glue your state operations to your UI components!
 
-Galena was originally designed to manage game state in TypeScript application with over 1000 stateful values. Existing state management utilities such as Zustand and Redux became cumbersome when modeling a huge amount of state and operations.
+## Basic Usage
+
+```typescript
+import { State, createState } from "@figliolia/galena";
+
+const myState = new State(/* any value */);
+// or
+const myState = createState(/* any value */);
+
+const currentValue = myState.getSnapshot();
+const subscriber = myState.subscribe(nextValue => {});
+myState.set(/* new value */);
+myState.update(previousValue => /* new value */);
 
-With Redux, the action-driven model became a juggling act of action names and tracing changes between them. With Zustand, the `create()` function felt limiting in the usage of JavaScript language constructs. It also lacked a construct for global application state.
+// to reset state back to its original value
+myState.reset();
+
+// to unregister the subscription
+subscriber();
+```
 
 ## Installation
 
@@ -18,19 +35,19 @@ npm i @figliolia/react-galena
 
 ### The State Model
 
-The instancable `State` object in Galena is easy to get started with and setup. It's effectively reactive wrapper around any value passed into it.
+The instancable `State` object in Galena is a reactive wrapper around any value. You can use it to apply reactivity to large objects or simple values
 
 ```typescript
 import { State } from "@figliolia/galena";
 
 const MyState = new State(/* any value */, /* middleware */);
 
-const subscription = MyState.subscribe(value => {
+const subscriber = MyState.subscribe(value => {
   // do something with changed values
 });
 
 // to unsubscribe
-subscription();
+subscriber();
 
 MyState.set(/* new value */);
 MyState.update(previousValue => /* new value */);
@@ -41,7 +58,9 @@ Instances of `State` are ultimately what compose all reactivity in Galena. They
 
 ### The Galena Model
 
-Creating Global application state(s) in Galena is simple. They are effectively just connected instances of your `State`'s.
+`Galena` objects are designed to "link" multiple instances of `State` together to create a "global" application state.
+
+To use it simply define your `State`'s and pass them to a `Galena` instance
 
 ```typescript
 import { Galena, State } from "@figliolia/galena";
@@ -55,16 +74,14 @@ const AppState = new Galena(
     user: new State({
       userID: "<id>",
       membershipTier: "free",
-      friends: ["<id1>", "<id2>"],
+      friends: ["<id-1>", "<id-2>"],
     }),
     // ...and so on
   } /* middleware */,
 );
-```
-
-From here, operations on any slice of state are type-aware and operable via a single construct:
 
-```typescript
+// From here, operations on any slice of state are type-aware
+// and operable via a single construct:
 const subscriber = AppState.subscribe(
   ({
     state, // The entire state object at the time of change
@@ -75,23 +92,19 @@ const subscriber = AppState.subscribe(
 );
 
 // to unsubscribe
-subscription();
+subscriber();
 
+// to access an instance of state
+const UserState = AppState.get("user");
 // to operate
-AppState.get("user").update(state => ({
-  ...state,
-  friends: [...state.friends, "<new-friend-id>"],
-}));
-
-AppState.get("navigation").update(state => ({
-  ...state,
-  navigationMenuOpen: true,
-}));
+UserState.update(state => /* next state */);
+// or
+AppState.update("user", state => /* next state */)
 ```
 
 ### Beyond the Basics
 
-#### Models
+#### Modeling Data with Mutations
 
 `State` in Galena is designed for extension and instancing - a need that ultimately motivated the library's development.
 
@@ -136,42 +149,29 @@ export class MyGameState extends State<IMyGameState> {
 }
 ```
 
-This extension of state, can now be used any number of times throughout your application simply by calling
-
-```typescript
-import { MyGameState } from "./MyGameState";
-
-const player1 = new MyGameState("<playerID>");
-const player2 = new MyGameState("<playerID>");
-```
-
-Each instance has a shared API and defined set of state operations that make for predictable operability
-
-This instances or robust models can also be used on your `Galena` instances
+These more "robust" state models assist in standardizing a developer API along with your data models. The models you create are also compatible with your your `Galena` instances:
 
 ```typescript
-import { Galena, State } from "@figliolia/galena";
+import { Galena } from "@figliolia/galena";
 import { MyGameState } from "./MyGameState";
 
 const MyAppState = new Galena({
-  navigation: new State({
-    currentScreen: "/",
-    navigationMenuOpen: false,
-  }),
   player1: new MyGameState(),
   player2: new MyGameState(),
 });
 
 // Operate
 MyAppState.get("player1").incrementScore(100);
-MyAppState.get("player1").raiseLevel();
+MyAppState.get("player2").raiseLevel();
 ```
 
 ### Middleware
 
-Middleware provides a developer API for building out robust tooling for your state.
+Middleware provides a developer API for building out custom tooling for your state.
+
+Building middleware is as simple as extending `Galena`'s `Middleware` class and registering on your state.
 
-Building an registering middleware is simple. Let's build a redux-style logger:
+Here's a quick example using the redux-like logger provided by this package:
 
 ```typescript
 import { Middleware, type State } from "@figliolia/galena";
@@ -232,7 +232,7 @@ const MyAppState = new Galena({
   // state
 }, new Logger(), new Profiler());
 
-// To apply middleware to a single of `State`
+// To apply middleware to a single piece of `State`
 const MyState = new State(
   /* reactive value */,
   new Logger(),

package/dist/Galena.cjs

@@ -1,24 +1,21 @@
 let _figliolia_event_emitter = require("@figliolia/event-emitter");
 //#region src/Galena.ts
 /**
-* 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);
 *
@@ -26,8 +23,9 @@ let _figliolia_event_emitter = require("@figliolia/event-emitter");
 * 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
 * });
 * ```
 */
@@ -37,9 +35,38 @@ var Galena = class {
 		this.state = state;
 		this.registerMiddleware(...middleware);
 	}
+	/**
+	* Get
+	*
+	* Returns a connected State instance by key
+	*/
 	get(key) {
 		return this.state[key];
 	}
+	/**
+	* Set
+	*
+	* Sets a connected State instance's state by key
+	*/
+	set(key, value) {
+		return this.get(key).set(value);
+	}
+	/**
+	* Update
+	*
+	* Invokes a connected State instance's update method key
+	*/
+	update(key, updater) {
+		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
+	*/
 	subscribe = (subscriber) => {
 		const ID = this.Emitter.on("change", subscriber);
 		const unsubscribers = [];
@@ -56,6 +83,12 @@ var Galena = class {
 			while (unsubscribers.length) unsubscribers.pop?.()?.();
 		};
 	};
+	/**
+	* Register Middleware
+	*
+	* Adds middleware instances to each of the connected
+	* `State` instances
+	*/
 	registerMiddleware(...middlewares) {
 		for (const key in this.state) this.state[key]?.registerMiddleware?.(...middlewares);
 	}
@@ -64,24 +97,21 @@ var Galena = class {
 	}
 };
 /**
-* 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);
 *
@@ -89,8 +119,9 @@ var Galena = class {
 * 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/dist/Galena.d.cts

@@ -1,27 +1,24 @@
-import { AppSubscriber, StateTypes } from "./types.cjs";
+import { AppSubscriber, Setter, StateType, StateTypes } from "./types.cjs";
 import { State } from "./State.cjs";
 import { Middleware } from "./Middleware.cjs";
 
 //#region src/Galena.d.ts
 /**
- * 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 +26,9 @@ import { Middleware } from "./Middleware.cjs";
  * 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
  * });
  * ```
  */
@@ -38,30 +36,58 @@ declare class Galena<T extends Record<string, State<any>>> {
   readonly state: T;
   private Emitter;
   constructor(state: T, ...middleware: Middleware<StateTypes<T>>[]);
+  /**
+   * Get
+   *
+   * Returns a connected State instance by key
+   */
   get<K extends Extract<keyof T, string>>(key: K): T[K];
+  /**
+   * Set
+   *
+   * Sets a connected State instance's state by key
+   */
+  set<K extends Extract<keyof T, string>>(key: K, value: StateType<T[K]>): void;
+  /**
+   * Update
+   *
+   * Invokes a connected State instance's update method key
+   */
+  update<K extends Extract<keyof T, string>>(key: K, updater: Setter<StateType<T[K]>>): void;
+  /**
+   * 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
+   */
   subscribe: (subscriber: AppSubscriber<T>) => () => void;
+  /**
+   * Register Middleware
+   *
+   * Adds middleware instances to each of the connected
+   * `State` instances
+   */
   registerMiddleware(...middlewares: Middleware<StateTypes<T>>[]): void;
   private emit;
 }
 /**
- * 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);
  *
@@ -69,8 +95,9 @@ declare 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/dist/Galena.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"Galena.d.cts","names":[],"sources":["../src/Galena.ts"],"mappings":";;;;;;;AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,MAAA,WAAiB,MAAA,SAAe,KAAA;EAAA,SAGzB,KAAA,EAAO,CAAA;EAAA,QAFjB,OAAA;cAEU,KAAA,EAAO,CAAA,KACpB,UAAA,EAAY,UAAA,CAAW,UAAA,CAAW,CAAA;EAKhC,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CAAY,GAAA,EAAK,CAAA,GAAC,CAAA,CAAA,CAAA;EAI9C,SAAA,GAAa,UAAA,EAAY,aAAA,CAAc,CAAA;EAsBvC,kBAAA,CAAA,GAAsB,WAAA,EAAa,UAAA,CAAW,UAAA,CAAW,CAAA;EAAA,QAMxD,IAAA;AAAA;;;;;;;;;;;;;;;;;;AAsCV;;;;;;;;;;;;;;cAAa,YAAA,aAA0B,MAAA,SAAe,KAAA,WACjD,IAAA,EAAM,qBAAA,QAA6B,MAAA,CAAO,CAAA,OAAG,MAAA,CAAA,CAAA"}
+{"version":3,"file":"Galena.d.cts","names":[],"sources":["../src/Galena.ts"],"mappings":";;;;;;;AAwCA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,MAAA,WAAiB,MAAA,SAAe,KAAA;EAAA,SAGzB,KAAA,EAAO,CAAA;EAAA,QAFjB,OAAA;cAEU,KAAA,EAAO,CAAA,KACpB,UAAA,EAAY,UAAA,CAAW,UAAA,CAAW,CAAA;EA0Ec;;;;;EAhE9C,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CAAY,GAAA,EAAK,CAAA,GAAC,CAAA,CAAA,CAAA;EAdV;;;;;EAuBpC,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CACjC,GAAA,EAAK,CAAA,EACL,KAAA,EAAO,SAAA,CAAU,CAAA,CAAE,CAAA;EAtBH;;;;;EAgCX,MAAA,WAAiB,OAAA,OAAc,CAAA,UAAA,CACpC,GAAA,EAAK,CAAA,EACL,OAAA,EAAS,MAAA,CAAO,SAAA,CAAU,CAAA,CAAE,CAAA;EAvBnB;;;;;;;;EAoCJ,SAAA,GAAa,UAAA,EAAY,aAAA,CAAc,CAAA;EA3BzB;;;;;;EAuDd,kBAAA,CAAA,GAAsB,WAAA,EAAa,UAAA,CAAW,UAAA,CAAW,CAAA;EAAA,QAMxD,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;AAoCV;;;;;;;cAAa,YAAA,aAA0B,MAAA,SAAe,KAAA,WACjD,IAAA,EAAM,qBAAA,QAA6B,MAAA,CAAO,CAAA,OAAG,MAAA,CAAA,CAAA"}

package/dist/Galena.d.mts

@@ -1,27 +1,24 @@
-import { AppSubscriber, StateTypes } from "./types.mjs";
+import { AppSubscriber, Setter, StateType, StateTypes } from "./types.mjs";
 import { State } from "./State.mjs";
 import { Middleware } from "./Middleware.mjs";
 
 //#region src/Galena.d.ts
 /**
- * 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 +26,9 @@ import { Middleware } from "./Middleware.mjs";
  * 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
  * });
  * ```
  */
@@ -38,30 +36,58 @@ declare class Galena<T extends Record<string, State<any>>> {
   readonly state: T;
   private Emitter;
   constructor(state: T, ...middleware: Middleware<StateTypes<T>>[]);
+  /**
+   * Get
+   *
+   * Returns a connected State instance by key
+   */
   get<K extends Extract<keyof T, string>>(key: K): T[K];
+  /**
+   * Set
+   *
+   * Sets a connected State instance's state by key
+   */
+  set<K extends Extract<keyof T, string>>(key: K, value: StateType<T[K]>): void;
+  /**
+   * Update
+   *
+   * Invokes a connected State instance's update method key
+   */
+  update<K extends Extract<keyof T, string>>(key: K, updater: Setter<StateType<T[K]>>): void;
+  /**
+   * 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
+   */
   subscribe: (subscriber: AppSubscriber<T>) => () => void;
+  /**
+   * Register Middleware
+   *
+   * Adds middleware instances to each of the connected
+   * `State` instances
+   */
   registerMiddleware(...middlewares: Middleware<StateTypes<T>>[]): void;
   private emit;
 }
 /**
- * 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);
  *
@@ -69,8 +95,9 @@ declare 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/dist/Galena.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Galena.d.mts","names":[],"sources":["../src/Galena.ts"],"mappings":";;;;;;;AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,MAAA,WAAiB,MAAA,SAAe,KAAA;EAAA,SAGzB,KAAA,EAAO,CAAA;EAAA,QAFjB,OAAA;cAEU,KAAA,EAAO,CAAA,KACpB,UAAA,EAAY,UAAA,CAAW,UAAA,CAAW,CAAA;EAKhC,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CAAY,GAAA,EAAK,CAAA,GAAC,CAAA,CAAA,CAAA;EAI9C,SAAA,GAAa,UAAA,EAAY,aAAA,CAAc,CAAA;EAsBvC,kBAAA,CAAA,GAAsB,WAAA,EAAa,UAAA,CAAW,UAAA,CAAW,CAAA;EAAA,QAMxD,IAAA;AAAA;;;;;;;;;;;;;;;;;;AAsCV;;;;;;;;;;;;;;cAAa,YAAA,aAA0B,MAAA,SAAe,KAAA,WACjD,IAAA,EAAM,qBAAA,QAA6B,MAAA,CAAO,CAAA,OAAG,MAAA,CAAA,CAAA"}
+{"version":3,"file":"Galena.d.mts","names":[],"sources":["../src/Galena.ts"],"mappings":";;;;;;;AAwCA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,MAAA,WAAiB,MAAA,SAAe,KAAA;EAAA,SAGzB,KAAA,EAAO,CAAA;EAAA,QAFjB,OAAA;cAEU,KAAA,EAAO,CAAA,KACpB,UAAA,EAAY,UAAA,CAAW,UAAA,CAAW,CAAA;EA0Ec;;;;;EAhE9C,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CAAY,GAAA,EAAK,CAAA,GAAC,CAAA,CAAA,CAAA;EAdV;;;;;EAuBpC,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CACjC,GAAA,EAAK,CAAA,EACL,KAAA,EAAO,SAAA,CAAU,CAAA,CAAE,CAAA;EAtBH;;;;;EAgCX,MAAA,WAAiB,OAAA,OAAc,CAAA,UAAA,CACpC,GAAA,EAAK,CAAA,EACL,OAAA,EAAS,MAAA,CAAO,SAAA,CAAU,CAAA,CAAE,CAAA;EAvBnB;;;;;;;;EAoCJ,SAAA,GAAa,UAAA,EAAY,aAAA,CAAc,CAAA;EA3BzB;;;;;;EAuDd,kBAAA,CAAA,GAAsB,WAAA,EAAa,UAAA,CAAW,UAAA,CAAW,CAAA;EAAA,QAMxD,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;AAoCV;;;;;;;cAAa,YAAA,aAA0B,MAAA,SAAe,KAAA,WACjD,IAAA,EAAM,qBAAA,QAA6B,MAAA,CAAO,CAAA,OAAG,MAAA,CAAA,CAAA"}