@figliolia/galena 3.0.2 → 4.0.0

package/README.md

@@ -2,9 +2,9 @@
 
 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.
-
-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.
+[State](#the-state-model)
+[Galena](#the-galena-model)
+[For use with react](#frameworks)
 
 ## Installation
 
@@ -18,30 +18,34 @@ 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";
+import { State, createState } from "@figliolia/galena";
 
-const MyState = new State(/* any value */, /* middleware */);
+const myState = new State(/* any value */, /* middleware */);
+// or
+const myState = createState(/* any value */, /* middleware */);
 
-const subscription = MyState.subscribe(value => {
-  // do something with changed values
-});
+const currentValue = myState.getState();
+const subscriber = myState.subscribe(nextValue => {});
+myState.set(/* new value */);
+myState.update(previousValue => /* new value */);
 
-// to unsubscribe
-subscription();
+// to reset state back to its original value
+myState.reset();
 
-MyState.set(/* new value */);
-MyState.update(previousValue => /* new value */);
-MyState.reset(); // reset state back to the initial value
+// to unregister the subscription
+subscriber();
 ```
 
 Instances of `State` are ultimately what compose all reactivity in Galena. They can exist as islands compose larger stateful model.
 
 ### 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 +59,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 +77,22 @@ 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 */);
+
+// to get the current value of the state tree
+const state = AppState.getState();
 ```
 
 ### 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 +137,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
+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 { 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
-
-```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";
@@ -181,7 +169,7 @@ export class Logger<T = any> extends Middleware<T> {
 
   override onBeforeUpdate(state: State<T>) {
     // capture the previous state before an update takes place
-    this.previousState = state.getSnapshot();
+    this.previousState = state.getState();
   }
 
   override onUpdate(state: State<T>) {
@@ -202,7 +190,7 @@ export class Logger<T = any> extends Middleware<T> {
     console.log(
       "   %cNext State    ",
       "color: rgb(17, 118, 249); font-weight: bold",
-      state.getSnapshot(),
+      state.getState(),
     );
   }
 
@@ -232,7 +220,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/API.cjs

@@ -0,0 +1,9 @@
+//#region src/API.ts
+var API = class {
+	middleware = [];
+	constructor(...middleware) {
+		this.registerMiddleware(...middleware);
+	}
+};
+//#endregion
+exports.API = API;

package/dist/API.d.cts

@@ -0,0 +1,13 @@
+import { Middleware } from "./Middleware.cjs";
+
+//#region src/API.d.ts
+declare abstract class API<T, E, M = T> {
+  readonly middleware: Middleware<M>[];
+  constructor(...middleware: Middleware<M>[]);
+  abstract getState(): T;
+  abstract subscribe(subscriber: (payload: E) => void): () => void;
+  abstract registerMiddleware(...middlewares: Middleware<M>[]): void;
+}
+//#endregion
+export { API };
+//# sourceMappingURL=API.d.cts.map

package/dist/API.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"API.d.cts","names":[],"sources":["../src/API.ts"],"mappings":";;;uBAEsB,GAAA,WAAc,CAAA;EAAA,SAClB,UAAA,EAAY,UAAA,CAAW,CAAA;iBACxB,UAAA,EAAY,UAAA,CAAW,CAAA;EAAA,SAItB,QAAA,CAAA,GAAY,CAAA;EAAA,SACZ,SAAA,CAAU,UAAA,GAAa,OAAA,EAAS,CAAA;EAAA,SAChC,kBAAA,CAAA,GAAsB,WAAA,EAAa,UAAA,CAAW,CAAA;AAAA"}

package/dist/API.d.mts

@@ -0,0 +1,13 @@
+import { Middleware } from "./Middleware.mjs";
+
+//#region src/API.d.ts
+declare abstract class API<T, E, M = T> {
+  readonly middleware: Middleware<M>[];
+  constructor(...middleware: Middleware<M>[]);
+  abstract getState(): T;
+  abstract subscribe(subscriber: (payload: E) => void): () => void;
+  abstract registerMiddleware(...middlewares: Middleware<M>[]): void;
+}
+//#endregion
+export { API };
+//# sourceMappingURL=API.d.mts.map

package/dist/API.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"API.d.mts","names":[],"sources":["../src/API.ts"],"mappings":";;;uBAEsB,GAAA,WAAc,CAAA;EAAA,SAClB,UAAA,EAAY,UAAA,CAAW,CAAA;iBACxB,UAAA,EAAY,UAAA,CAAW,CAAA;EAAA,SAItB,QAAA,CAAA,GAAY,CAAA;EAAA,SACZ,SAAA,CAAU,UAAA,GAAa,OAAA,EAAS,CAAA;EAAA,SAChC,kBAAA,CAAA,GAAsB,WAAA,EAAa,UAAA,CAAW,CAAA;AAAA"}

package/dist/API.mjs

@@ -0,0 +1,11 @@
+//#region src/API.ts
+var API = class {
+	middleware = [];
+	constructor(...middleware) {
+		this.registerMiddleware(...middleware);
+	}
+};
+//#endregion
+export { API };
+
+//# sourceMappingURL=API.mjs.map

package/dist/API.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"API.mjs","names":[],"sources":["../src/API.ts"],"sourcesContent":["import type { Middleware } from \"./Middleware\";\n\nexport abstract class API<T, E, M = T> {\n  public readonly middleware: Middleware<M>[] = [];\n  constructor(...middleware: Middleware<M>[]) {\n    this.registerMiddleware(...middleware);\n  }\n\n  public abstract getState(): T;\n  public abstract subscribe(subscriber: (payload: E) => void): () => void;\n  public abstract registerMiddleware(...middlewares: Middleware<M>[]): void;\n}\n"],"mappings":";AAEA,IAAsB,MAAtB,MAAuC;CACrC,aAA8C,EAAE;CAChD,YAAY,GAAG,YAA6B;AAC1C,OAAK,mBAAmB,GAAG,WAAW"}

package/dist/Galena.cjs

@@ -1,45 +1,90 @@
+const require_API = require("./API.cjs");
 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);
 *
 * // to retreive and work with an individual unit
-* const myUnit = AppState.get("<key>"); // Returns State<T>
+* const userState = AppState.get("user"); // 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
 * });
+*
+* // get the current application state
+* const currentState = AppState.getState();
+*
+* // operate on an instance of state
+* AppState.update("user", userState => ({
+*   ...userState,
+*   // your updates
+* }));
 * ```
 */
-var Galena = class {
+var Galena = class extends require_API.API {
 	Emitter = new _figliolia_event_emitter.EventEmitter();
 	constructor(state, ...middleware) {
+		super(...middleware);
 		this.state = state;
-		this.registerMiddleware(...middleware);
 	}
+	getState() {
+		const result = {};
+		for (const key in this.state) {
+			const state = key;
+			result[state] = this.state[key].getState();
+		}
+		return result;
+	}
+	/**
+	* 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 +101,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,34 +115,41 @@ 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);
 *
 * // to retreive and work with an individual unit
-* const myUnit = AppState.get("<key>"); // Returns State<T>
+* const userState = AppState.get("user"); // 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
 * });
+*
+* // get the current application state
+* const currentState = AppState.getState();
+*
+* // operate on an instance of state
+* AppState.update("user", userState => ({
+*   ...userState,
+*   // your updates
+* }));
 * ```
 */
 const createGalena = (...args) => {

package/dist/Galena.d.cts

@@ -1,77 +1,124 @@
-import { AppSubscriber, StateTypes } from "./types.cjs";
+import { AppSubscriber, GalenaSnapshot, GalenaState, Setter, StateType, StateTypes } from "./types.cjs";
 import { State } from "./State.cjs";
 import { Middleware } from "./Middleware.cjs";
+import { API } from "./API.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);
  *
  * // to retreive and work with an individual unit
- * const myUnit = AppState.get("<key>"); // Returns State<T>
+ * const userState = AppState.get("user"); // 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
  * });
+ *
+ * // get the current application state
+ * const currentState = AppState.getState();
+ *
+ * // operate on an instance of state
+ * AppState.update("user", userState => ({
+ *   ...userState,
+ *   // your updates
+ * }));
  * ```
  */
-declare class Galena<T extends Record<string, State<any>>> {
+declare class Galena<T extends Record<string, State<any>>> extends API<GalenaState<T>, GalenaSnapshot<T>, StateTypes<T>> {
   readonly state: T;
   private Emitter;
   constructor(state: T, ...middleware: Middleware<StateTypes<T>>[]);
+  getState(): GalenaState<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);
  *
  * // to retreive and work with an individual unit
- * const myUnit = AppState.get("<key>"); // Returns State<T>
+ * const userState = AppState.get("user"); // 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
  * });
+ *
+ * // get the current application state
+ * const currentState = AppState.getState();
+ *
+ * // operate on an instance of state
+ * AppState.update("user", userState => ({
+ *   ...userState,
+ *   // your updates
+ * }));
  * ```
  */
 declare const createGalena: <T extends Record<string, State<any>>>(...args: ConstructorParameters<typeof Galena<T>>) => Galena<T>;

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":";;;;;;;;AAmDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,MAAA,WAAiB,MAAA,SAAe,KAAA,gBAAqB,GAAA,CAChE,WAAA,CAAY,CAAA,GACZ,cAAA,CAAe,CAAA,GACf,UAAA,CAAW,CAAA;EAAA,SAIO,KAAA,EAAO,CAAA;EAAA,QAFjB,OAAA;cAEU,KAAA,EAAO,CAAA,KACpB,UAAA,EAAY,UAAA,CAAW,UAAA,CAAW,CAAA;EAKhC,QAAA,CAAA,GAAQ,WAAA,CAAA,CAAA;EAbiD;;;;;EA2BzD,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CAAY,GAAA,EAAK,CAAA,GAAC,CAAA,CAAA,CAAA;EA3BW;;;;;EAoCzD,GAAA,WAAc,OAAA,OAAc,CAAA,UAAA,CACjC,GAAA,EAAK,CAAA,EACL,KAAA,EAAO,SAAA,CAAU,CAAA,CAAE,CAAA;EAnCV;;;;;EA6CJ,MAAA,WAAiB,OAAA,OAAc,CAAA,UAAA,CACpC,GAAA,EAAK,CAAA,EACL,OAAA,EAAS,MAAA,CAAO,SAAA,CAAU,CAAA,CAAE,CAAA;EA3CZ;;;;;;;;EAwDX,SAAA,GAAa,UAAA,EAAY,aAAA,CAAc,CAAA;EApCnC;;;;;;EAgEJ,kBAAA,CAAA,GAAsB,WAAA,EAAa,UAAA,CAAW,UAAA,CAAW,CAAA;EAAA,QAMxD,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CV;;;;;;;cAAa,YAAA,aAA0B,MAAA,SAAe,KAAA,WACjD,IAAA,EAAM,qBAAA,QAA6B,MAAA,CAAO,CAAA,OAAG,MAAA,CAAA,CAAA"}