@figliolia/galena 2.0.0 → 2.0.2

package/README.md

@@ -531,4 +531,5 @@ As the application scales with more state updates and connected components, the
 ### Support for Frontend Frameworks!
 `Galena` provides bindings for React through [react-galena](https://github.com/alexfigliolia/react-galena). This package provides factories for generating HOC's and hooks from your Galena instances and units of State!
 
-
+#### Demo Application
+To see some basic usage using Galena with React, please check out this [Example App](https://github.com/alexfigliolia/galena-quick-start)

package/dist/Galena/Galena.d.ts

@@ -1,5 +1,6 @@
 import type { Middleware } from "../Middleware/Middleware";
 import { State } from "./State";
+import { Guards } from "./Guards";
 /**
  * ## Galena
  *
@@ -55,11 +56,11 @@ import { State } from "./State";
  * });
  * ```
  */
-export declare class Galena<T extends Record<string, State<any>> = Record<string, State<any>>> {
+export declare class Galena<T extends Record<string, State<any>> = Record<string, State<any>>> extends Guards {
     readonly state: T;
+    private readonly subscriptions;
     private readonly middleware;
     private readonly IDs;
-    private readonly subscriptions;
     constructor(middleware?: Middleware[]);
     /**
      * Compose State
@@ -76,7 +77,7 @@ export declare class Galena<T extends Record<string, State<any>> = Record<string
      *
      * Returns a unit of `State` by name
      */
-    get<K extends keyof T>(name: K): T[K];
+    get<K extends Extract<keyof T, string>>(name: K): T[K];
     /**
      * Mutable
      *
@@ -88,21 +89,21 @@ export declare class Galena<T extends Record<string, State<any>> = Record<string
      *
      * Runs a mutation on the specified unit of state
      */
-    update<K extends keyof T>(name: K, mutation: Parameters<T[K]["update"]>["0"]): any;
+    update<K extends Extract<keyof T, string>>(name: K, mutation: Parameters<T[K]["update"]>["0"]): any;
     /**
      * Background Update
      *
      * Runs a higher priority mutation on the specified unit of
      * state
      */
-    backgroundUpdate<K extends keyof T>(name: K, mutation: Parameters<T[K]["backgroundUpdate"]>["0"]): any;
+    backgroundUpdate<K extends Extract<keyof T, string>>(name: K, mutation: Parameters<T[K]["backgroundUpdate"]>["0"]): any;
     /**
      * Priority Update
      *
      * Runs an immediate priority mutation on the specified unit
      * of state
      */
-    priorityUpdate<K extends keyof T>(name: K, mutation: Parameters<T[K]["priorityUpdate"]>["0"]): any;
+    priorityUpdate<K extends Extract<keyof T, string>>(name: K, mutation: Parameters<T[K]["priorityUpdate"]>["0"]): any;
     /**
      * Subscribe
      *
@@ -113,14 +114,14 @@ export declare class Galena<T extends Record<string, State<any>> = Record<string
      * subscription, call `Galena.unsubscribe()` with the ID returned
      * by this method
      */
-    subscribe<K extends keyof T>(name: K, callback: Parameters<T[K]["subscribe"]>["0"]): string;
+    subscribe<K extends Extract<keyof T, string>>(name: K, callback: Parameters<T[K]["subscribe"]>["0"]): string;
     /**
      * Unsubscribe
      *
      * Given a subscription ID returned from the `subscribe` method,
      * this method removes and cleans up the corresponding subscription
      */
-    unsubscribe<K extends keyof T>(name: K, ID: string): boolean | undefined;
+    unsubscribe<K extends Extract<keyof T, string>>(name: K, ID: string): boolean | undefined;
     /**
      * Subscribe All
      *

package/dist/Galena/Galena.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Galena = void 0;
 const event_emitter_1 = require("@figliolia/event-emitter");
 const State_1 = require("./State");
+const Guards_1 = require("./Guards");
 /**
  * ## Galena
  *
@@ -58,12 +59,13 @@ const State_1 = require("./State");
  * });
  * ```
  */
-class Galena {
+class Galena extends Guards_1.Guards {
     constructor(middleware = []) {
+        super();
         this.state = {};
+        this.subscriptions = new Map();
         this.middleware = [];
         this.IDs = new event_emitter_1.AutoIncrementingID();
-        this.subscriptions = new Map();
         this.middleware = middleware;
     }
     /**
@@ -78,6 +80,7 @@ class Galena {
     composeState(name, initialState, 
     // @ts-ignore
     Model = (State_1.State)) {
+        this.guardDuplicateStates(name, this.state);
         const state = new Model(name, initialState);
         state.registerMiddleware(...this.middleware);
         this.mutable[name] = state;
@@ -90,6 +93,7 @@ class Galena {
      * Returns a unit of `State` by name
      */
     get(name) {
+        this.warnForUndefinedStates(name, this.state);
         return this.state[name];
     }
     /**
@@ -160,7 +164,6 @@ class Galena {
      * returned
      */
     subscribeAll(callback) {
-        const subscriptionID = this.IDs.get();
         const stateSubscriptions = [];
         for (const key in this.state) {
             stateSubscriptions.push([
@@ -170,6 +173,7 @@ class Galena {
                 }),
             ]);
         }
+        const subscriptionID = this.IDs.get();
         this.subscriptions.set(subscriptionID, stateSubscriptions);
         return subscriptionID;
     }

package/dist/Galena/Guards.d.ts

@@ -0,0 +1,36 @@
+import type { State } from "./State";
+/**
+ * Guards
+ *
+ * Development-only warnings and runtime errors designed to
+ * guard developers against possible pitfalls when using
+ * Galena. This interface provides composable error and
+ * warning methods that can be used to prevent invalid usage
+ * of the library
+ */
+export declare class Guards {
+    /**
+     * Warn For Undefined States
+     *
+     * In Galena, it's normal to lazy initialize a unit of state
+     * in attached to a `Galena` instance. This warning lets
+     * developers know that they are attempting to manipulate a
+     * unit of state that has not yet been initialized
+     */
+    protected warnForUndefinedStates: (name: string, state: Record<string, State<any>>) => void;
+    /**
+     * Guard Duplicate States
+     *
+     * Throws an error if a developer attempts to create
+     * more than one state with the same name on a single
+     * `Galena` instance
+     */
+    protected guardDuplicateStates: (name: string, state: Record<string, State<any>>) => void;
+    /**
+     * Development Guard
+     *
+     * Wraps a provided function in a check for `process.env.NODE_ENV`
+     * equaling "development". Returns the callback
+     */
+    private developmentGuard;
+}

package/dist/Galena/Guards.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Guards = void 0;
+/**
+ * Guards
+ *
+ * Development-only warnings and runtime errors designed to
+ * guard developers against possible pitfalls when using
+ * Galena. This interface provides composable error and
+ * warning methods that can be used to prevent invalid usage
+ * of the library
+ */
+class Guards {
+    constructor() {
+        /**
+         * Warn For Undefined States
+         *
+         * In Galena, it's normal to lazy initialize a unit of state
+         * in attached to a `Galena` instance. This warning lets
+         * developers know that they are attempting to manipulate a
+         * unit of state that has not yet been initialized
+         */
+        this.warnForUndefinedStates = this.developmentGuard((name, state) => {
+            if (!process.env.IGNORE_LAZY_STATE_WARNINGS && !(name in state)) {
+                console.warn(`A unit of state with the name "${name}" does not yet exist on this Galena instance. If this is expected, you can ignore this warning. To make these warnings go away, you can enable this process argument - "IGNORE_WARNINGS_FOR_LAZY_STATES=1"`);
+            }
+        });
+        /**
+         * Guard Duplicate States
+         *
+         * Throws an error if a developer attempts to create
+         * more than one state with the same name on a single
+         * `Galena` instance
+         */
+        this.guardDuplicateStates = this.developmentGuard((name, state) => {
+            if (name in state) {
+                throw new Error(`A unit of state with the name "${name}" already exists on this Galena instance. Please re-name this new unit of state to something unique`);
+            }
+        });
+    }
+    /**
+     * Development Guard
+     *
+     * Wraps a provided function in a check for `process.env.NODE_ENV`
+     * equaling "development". Returns the callback
+     */
+    developmentGuard(guard) {
+        return (...args) => {
+            if (process.env.NODE_ENV === "development") {
+                guard(...args);
+            }
+        };
+    }
+}
+exports.Guards = Guards;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figliolia/galena",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A performant state management library supporting mutable state, batched updates, middleware and a rich development API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/Galena/Galena.ts

@@ -3,6 +3,7 @@ import { AutoIncrementingID } from "@figliolia/event-emitter";
 import type { Middleware } from "Middleware/Middleware";
 
 import { State } from "Galena/State";
+import { Guards } from "./Guards";
 
 /**
  * ## Galena
@@ -61,15 +62,16 @@ import { State } from "Galena/State";
  */
 export class Galena<
   T extends Record<string, State<any>> = Record<string, State<any>>
-> {
+> extends Guards {
   public readonly state = {} as T;
-  private readonly middleware: Middleware[] = [];
-  private readonly IDs = new AutoIncrementingID();
   private readonly subscriptions = new Map<
     string,
     [state: string, ID: string][]
   >();
+  private readonly middleware: Middleware[] = [];
+  private readonly IDs = new AutoIncrementingID();
   constructor(middleware: Middleware[] = []) {
+    super();
     this.middleware = middleware;
   }
 
@@ -91,6 +93,7 @@ export class Galena<
     // @ts-ignore
     Model: M = State<S>
   ) {
+    this.guardDuplicateStates(name, this.state);
     const state = new Model(name, initialState);
     state.registerMiddleware(...this.middleware);
     this.mutable[name] = state;
@@ -103,7 +106,8 @@ export class Galena<
    *
    * Returns a unit of `State` by name
    */
-  public get<K extends keyof T>(name: K): T[K] {
+  public get<K extends Extract<keyof T, string>>(name: K): T[K] {
+    this.warnForUndefinedStates(name, this.state);
     return this.state[name];
   }
 
@@ -121,7 +125,7 @@ export class Galena<
    *
    * Runs a mutation on the specified unit of state
    */
-  public update<K extends keyof T>(
+  public update<K extends Extract<keyof T, string>>(
     name: K,
     mutation: Parameters<T[K]["update"]>["0"]
   ) {
@@ -134,7 +138,7 @@ export class Galena<
    * Runs a higher priority mutation on the specified unit of
    * state
    */
-  public backgroundUpdate<K extends keyof T>(
+  public backgroundUpdate<K extends Extract<keyof T, string>>(
     name: K,
     mutation: Parameters<T[K]["backgroundUpdate"]>["0"]
   ) {
@@ -147,7 +151,7 @@ export class Galena<
    * Runs an immediate priority mutation on the specified unit
    * of state
    */
-  public priorityUpdate<K extends keyof T>(
+  public priorityUpdate<K extends Extract<keyof T, string>>(
     name: K,
     mutation: Parameters<T[K]["priorityUpdate"]>["0"]
   ) {
@@ -164,7 +168,7 @@ export class Galena<
    * subscription, call `Galena.unsubscribe()` with the ID returned
    * by this method
    */
-  public subscribe<K extends keyof T>(
+  public subscribe<K extends Extract<keyof T, string>>(
     name: K,
     callback: Parameters<T[K]["subscribe"]>["0"]
   ) {
@@ -177,7 +181,7 @@ export class Galena<
    * Given a subscription ID returned from the `subscribe` method,
    * this method removes and cleans up the corresponding subscription
    */
-  public unsubscribe<K extends keyof T>(name: K, ID: string) {
+  public unsubscribe<K extends Extract<keyof T, string>>(name: K, ID: string) {
     return this.get(name).unsubscribe(ID);
   }
 
@@ -193,7 +197,6 @@ export class Galena<
    * returned
    */
   public subscribeAll(callback: (nextState: T) => void) {
-    const subscriptionID = this.IDs.get();
     const stateSubscriptions: [state: string, ID: string][] = [];
     for (const key in this.state) {
       stateSubscriptions.push([
@@ -203,6 +206,7 @@ export class Galena<
         }),
       ]);
     }
+    const subscriptionID = this.IDs.get();
     this.subscriptions.set(subscriptionID, stateSubscriptions);
     return subscriptionID;
   }

package/src/Galena/Guards.ts

@@ -0,0 +1,67 @@
+import type { State } from "./State";
+
+/**
+ * Guards
+ *
+ * Development-only warnings and runtime errors designed to
+ * guard developers against possible pitfalls when using
+ * Galena. This interface provides composable error and
+ * warning methods that can be used to prevent invalid usage
+ * of the library
+ */
+export class Guards {
+  /**
+   * Warn For Undefined States
+   *
+   * In Galena, it's normal to lazy initialize a unit of state
+   * in attached to a `Galena` instance. This warning lets
+   * developers know that they are attempting to manipulate a
+   * unit of state that has not yet been initialized
+   */
+  protected warnForUndefinedStates = this.developmentGuard(
+    <T extends Record<string, State<any>>, K extends Extract<keyof T, string>>(
+      name: K,
+      state: T
+    ) => {
+      if (!process.env.IGNORE_LAZY_STATE_WARNINGS && !(name in state)) {
+        console.warn(
+          `A unit of state with the name "${name}" does not yet exist on this Galena instance. If this is expected, you can ignore this warning. To make these warnings go away, you can enable this process argument - "IGNORE_LAZY_STATE_WARNING=1"`
+        );
+      }
+    }
+  );
+
+  /**
+   * Guard Duplicate States
+   *
+   * Throws an error if a developer attempts to create
+   * more than one state with the same name on a single
+   * `Galena` instance
+   */
+  protected guardDuplicateStates = this.developmentGuard(
+    <T extends Record<string, State<any>>, K extends Extract<keyof T, string>>(
+      name: K,
+      state: T
+    ) => {
+      if (name in state) {
+        throw new Error(
+          `A unit of state with the name "${name}" already exists on this Galena instance. Please re-name this new unit of state to something unique`
+        );
+      }
+    }
+  );
+
+  /**
+   * Development Guard
+   *
+   * Wraps a provided function in a check for `process.env.NODE_ENV`
+   * equaling "development". Returns the callback
+   */
+  private developmentGuard<F extends (...args: any[]) => void>(guard: F) {
+    return (...args: Parameters<F>) => {
+      if (process.env.NODE_ENV === "development") {
+        guard(...args);
+      }
+    };
+  }
+}