@figliolia/galena 2.3.5 → 3.0.1

package/src/Middleware.ts

@@ -0,0 +1,62 @@
+import type { State } from "./State";
+
+/**
+ * Middleware
+ *
+ * Galena's middleware API is designed to provide hooks
+ * for state changes that you can tap into to run your
+ * own logic.
+ *
+ * Middleware is great for logging, analytics, and profiling:
+ *
+ * ```typescript
+ * export class Profiler<T = any> extends Middleware<T> {
+ *   private previousState: T | null = null;
+ *   private startTime: null | number = null;
+ *   constructor(public readonly threshold: number = 16) {
+ *     super();
+ *   }
+ *
+ *   public override onBeforeUpdate(state: State<T>) {
+ *     this.startTime = performance.now();
+ *     this.previousState = state.getSnapshot();
+ *   }
+ *
+ *   public override onUpdate(state: T) {
+ *     const diff = performance.now() - this.startTime;
+ *     if(diff >= this.threshold) {
+ *       console.warn(`A slow state transition was detected when transitioning the following piece of state`);
+ *       console.log('Previous state', this.previousState);
+ *       console.log('Current state', state.getSnapshot());
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * To register your middleware, simply add it when constructing
+ * a `State` or `Galena` instance.
+ *
+ * ```typescript
+ * import { State } from "@figliolia/galena";
+ * import { Profiler } from './myProfiler';
+ *
+ * const myState = new State(5, new Profiler());
+ * ```
+ */
+export class Middleware<T = any> {
+  /**
+   * On Before Update
+   *
+   * Executes prior to a `State` instance being updated.
+   * Receives the state prior to its update as a parameter
+   */
+  public onBeforeUpdate(_state: State<T>) {}
+
+  /**
+   * On Update
+   *
+   * Executes after a `State` instance has been update.
+   * Receives the most recent state as a parameter
+   */
+  public onUpdate(_state: State<T>) {}
+}

package/src/Profiler.ts

@@ -0,0 +1,53 @@
+import { Middleware } from "./Middleware";
+import type { State } from "./State";
+
+/**
+ * Profiler
+ *
+ * A logger for state transitions exceeding a given
+ * millisecond threshold
+ *
+ * ```typescript
+ * const AppState = new Galena({}, new Profiler());
+ * // or
+ * AppState.registerMiddlerware(new Profiler());
+ * // or
+ * const MyState = new State(4, new Profiler());
+ * // or
+ * MyState.registerMiddleware(new Profiler());
+ * ```
+ */
+export class Profiler<T = any> extends Middleware<T> {
+  private previousState: T | null = null;
+  private startTime: null | number = null;
+  constructor(public readonly threshold = 16) {
+    super();
+  }
+
+  public override onBeforeUpdate(state: State<T>) {
+    this.startTime = performance.now();
+    this.previousState = state.getSnapshot();
+  }
+
+  public override onUpdate(state: State<T>) {
+    if (this.startTime === null) {
+      return;
+    }
+    const diff = performance.now() - this.startTime;
+    if (diff >= this.threshold) {
+      console.warn(
+        `A slow state transition of ${diff.toFixed(1)}ms was detected when transitioning the following piece of state`,
+      );
+      console.log(
+        "   %cPrevious State",
+        "color: #26ad65; font-weight: bold",
+        this.previousState,
+      );
+      console.log(
+        "   %cCurrent State    ",
+        "color: rgb(17, 118, 249); font-weight: bold",
+        state.getSnapshot(),
+      );
+    }
+  }
+}

package/src/State.ts

@@ -0,0 +1,167 @@
+import { EventEmitter } from "@figliolia/event-emitter";
+import type { Middleware } from "./Middleware";
+import type { NonFunction, Setter, Subscriber } from "./types";
+
+/**
+ * State
+ *
+ * The unit of reactivity for Galena. `State`'s can act
+ * as isolated instances or be part of your global app
+ * state (via `Galena` instances).
+ *
+ * There are three ways to create state instances
+ *
+ * ```typescript
+ * import { State, createState, useState, 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());
+ *
+ * // 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
+ *   );
+ * }
+ * ```
+ */
+export class State<T> {
+  private state: NonFunction<T>;
+  public readonly middleware: Middleware<T>[] = [];
+  private readonly Emitter = new EventEmitter<{ change: NonFunction<T> }>();
+  constructor(
+    public readonly initialState: NonFunction<T>,
+    ...middleware: Middleware<T>[]
+  ) {
+    this.state = initialState;
+    this.registerMiddleware(...middleware);
+  }
+
+  /**
+   * Set
+   *
+   * Updates the current value of state notifying
+   * all interested parties
+   */
+  public readonly set = this.withEmission((state: NonFunction<T>) => state);
+
+  /**
+   * Update
+   *
+   * Updates the current value of state using a setter function
+   * receiving the previous state as a parameter. Notifies all
+   * interested parties
+   */
+  public readonly update = this.withEmission((setter: Setter<T>) => {
+    if (this.diffSetter(setter)) {
+      return setter;
+    }
+    return setter(this.state);
+  });
+
+  /**
+   * Reset
+   *
+   * Resets the current state back to the state which the instance
+   * was initialized with. Notifies all interested parties
+   */
+  public readonly reset = this.withEmission(() => this.initialState);
+
+  /**
+   * Get Snapshot
+   *
+   * Returns the current state. Designed for compatibility with
+   * `useSyncExternalStore`
+   */
+  public readonly getSnapshot = () => {
+    return this.state;
+  };
+
+  /**
+   * Subscribe
+   *
+   * Registers a callback to be executed each time state
+   * changes. Returns an `unsubscribe` function
+   */
+  public readonly subscribe = (fn: Subscriber<T>) => {
+    const ID = this.Emitter.on("change", fn);
+    return () => {
+      this.Emitter.off("change", ID);
+    };
+  };
+
+  /**
+   * Register Middleware
+   *
+   * Registers any number of `Middleware` instances on the
+   * current instance of `State`. Your middleware will begin
+   * executing at the next state transition
+   */
+  public registerMiddleware(...middleware: Middleware<T>[]) {
+    this.middleware.push(...middleware);
+  }
+
+  private withEmission<
+    F extends (...args: any[]) => NonFunction<T> | Promise<NonFunction<T>>,
+  >(fn: F) {
+    return (...args: Parameters<F>) => {
+      const result = fn(...args);
+      if (result instanceof Promise) {
+        void result.then(resolved => this.emit(resolved));
+        return;
+      }
+      return this.emit(result);
+    };
+  }
+
+  private emit(nextState: NonFunction<T>) {
+    this.invokeMiddleware("onBeforeUpdate");
+    this.state = nextState;
+    this.Emitter.emit("change", this.state);
+    this.invokeMiddleware("onUpdate");
+  }
+
+  protected diffSetter(setter: Setter<T>): setter is NonFunction<T> {
+    return typeof setter !== "function";
+  }
+
+  private invokeMiddleware<K extends keyof Middleware<T>>(fn: K) {
+    for (const middleware of this.middleware) {
+      middleware[fn](this);
+    }
+  }
+}
+
+/**
+ * Create State
+ *
+ * Returns the unit of reactivity for Galena. `State`'s can act
+ * as isolated instances or be part of your global app
+ * state (via `Galena` instances);
+ *
+ * ```typescript
+ * import { createState, Profiler } from "@figliolia/galena";
+ *
+ * const myState = createState("<any value>", ...middleware);
+ *
+ * myState.set("<new-value>");
+ * myState.update(previousValue => "<new-value>");
+ * myState.subscribe(nextValue => {});
+ * myState.registerMiddleware(new Profiler());
+ * ```
+ */
+export function createState<T>(
+  ...args: ConstructorParameters<typeof State<T>>
+) {
+  return new State<T>(...args);
+}

package/src/index.ts

@@ -1,3 +1,6 @@
-export * from "Galena";
-export * from "Middleware";
-export * from "Middlewares";
+export * from "./Galena";
+export * from "./Logger";
+export * from "./Middleware";
+export * from "./Profiler";
+export * from "./State";
+export * from "./types";

package/src/types.ts

@@ -0,0 +1,28 @@
+import type { State } from "./State";
+
+export type NonFunction<T> = T extends (...args: any[]) => any ? never : T;
+
+export type PartialSupport<T> = T extends Record<string, any> ? Partial<T> : T;
+
+export type Setter<T> =
+  | NonFunction<T>
+  | ((prevState: NonFunction<T>) => NonFunction<T> | Promise<NonFunction<T>>);
+
+export type Subscriber<T> = ((state: NonFunction<T>) => void) | (() => void);
+
+export interface GalenaSnapshot<
+  T extends Record<string, State<any>>,
+  K extends Extract<keyof T, string> = Extract<keyof T, string>,
+> {
+  updated: T[K];
+  state: T;
+}
+
+export type AppSubscriber<
+  T extends Record<string, State<any>>,
+  K extends Extract<keyof T, string> = Extract<keyof T, string>,
+> = ((payload: GalenaSnapshot<T, K>) => void) | (() => void);
+
+export type StateTypes<T extends Record<string, State<any>>> = ReturnType<
+  T[keyof T]["getSnapshot"]
+>;

package/dist/cjs/Galena/Galena.js

@@ -1,223 +0,0 @@
-"use strict";
-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
- *
- * A performant global state solution that scales
- *
- * ### Creating State
- *
- * ```typescript
- * // AppState.ts
- * import { Galena } from "@figliolia/galena";
- *
- * const AppState = new Galena([...middleware]);
- *
- * const NavigationState = AppState.composeState("navigation", {
- *   currentRoute: "/",
- *   userID: "12345",
- *   permittedRoutes: ["/*"]
- * });
- * ```
- *
- * ### Subscribing to State Changes
- * #### Using the Galena Instance
- * ```typescript
- * import { AppState } from "./AppState";
- *
- * AppState.subscribe(appState => {
- *   const navState = appState.get("navigation");
- *   const { currentRoute } = navState.state;
- *   // do something with state changes!
- * });
- * ```
- * #### Using the State Instance
- * ```typescript
- * NavigationState.subscribe(navigation => {
- *   const { currentRoute } = navigation
- *   // do something with state changes!
- * });
- * ```
- *
- * #### Using Global Subscriptions
- * ```typescript
- * NavigationState.subscribeAll(nextState => {
- *   const { currentRoute } = nextState.navigation
- *   // do something with state changes!
- * });
- * ```
- *
- * ### Mutating State
- * ```typescript
- * NavigationState.update(state => {
- *   state.currentRoute = "/profile";
- *   // You can mutate state without creating new objects!
- * });
- * ```
- */
-class Galena extends Guards_1.Guards {
-    constructor(middleware = []) {
-        super();
-        this.state = {};
-        this.middleware = [];
-        this.IDs = new event_emitter_1.AutoIncrementingID();
-        this.subscriptions = new Map();
-        this.middleware = middleware;
-    }
-    /**
-     * Compose State
-     *
-     * Creates a new `State` instance and returns it. Your new state
-     * becomes immediately available on your `Galena` instance and
-     * is wired into your middleware. All existing subscriptions to
-     * state will automatically receive updates when your new unit of
-     * state updates
-     */
-    composeState(name, initialState, Model) {
-        this.guardDuplicateStates(name, this.state);
-        const StateModel = Model || (State_1.State);
-        const state = new StateModel(name, initialState);
-        state.registerMiddleware(...this.middleware);
-        this.mutable[name] = state;
-        this.reIndexSubscriptions(name);
-        return state;
-    }
-    /**
-     * Get State
-     *
-     * Returns a mutable state instance
-     */
-    getState() {
-        return this.state;
-    }
-    /**
-     * Get
-     *
-     * Returns a unit of `State` by name
-     */
-    get(name) {
-        this.warnForUndefinedStates(name, this.state);
-        return this.state[name];
-    }
-    /**
-     * Mutable
-     *
-     * Returns a mutable state instance
-     */
-    get mutable() {
-        return this.state;
-    }
-    /**
-     * Update
-     *
-     * Runs a mutation on the specified unit of state
-     */
-    update(name, mutation) {
-        return this.get(name).update(mutation);
-    }
-    /**
-     * Background Update
-     *
-     * Runs a higher priority mutation on the specified unit of
-     * state
-     */
-    backgroundUpdate(name, mutation) {
-        return this.get(name).backgroundUpdate(mutation);
-    }
-    /**
-     * Priority Update
-     *
-     * Runs an immediate priority mutation on the specified unit
-     * of state
-     */
-    priorityUpdate(name, mutation) {
-        return this.get(name).priorityUpdate(mutation);
-    }
-    /**
-     * Subscribe
-     *
-     * Given the name of a unit of state, this method registers
-     * a subscription on the target state instance. The callback
-     * you provide will execute each time state changes. Returns
-     * a unique identifier for your subscription. To clean up your
-     * subscription, call `Galena.unsubscribe()` with the ID returned
-     * by this method
-     */
-    subscribe(name, callback) {
-        return this.get(name).subscribe(callback);
-    }
-    /**
-     * Unsubscribe
-     *
-     * Given a subscription ID returned from the `subscribe` method,
-     * this method removes and cleans up the corresponding subscription
-     */
-    unsubscribe(name, ID) {
-        return this.get(name).unsubscribe(ID);
-    }
-    /**
-     * Subscribe All
-     *
-     * Registers a callback on each registered `State` instance and
-     * is invoked each time your state changes. Using `Galena`'s
-     * `subscribeAll` method, although performant, can be less
-     * performant than subscribing directly to a target `State`
-     * instance using `Galena.subscribe()`. To clean up your
-     * subscription, call `Galena.unsubscribeAll()` with the ID
-     * returned
-     */
-    subscribeAll(callback) {
-        const stateSubscriptions = [];
-        for (const key in this.state) {
-            stateSubscriptions.push([
-                key,
-                this.state[key].subscribe(() => {
-                    void callback(this.state);
-                }),
-            ]);
-        }
-        const subscriptionID = this.IDs.get();
-        this.subscriptions.set(subscriptionID, stateSubscriptions);
-        return subscriptionID;
-    }
-    /**
-     * Unsubscribe
-     *
-     * Given a subscription ID returned from the `subscribeAll()` method,
-     * this method removes and cleans up the corresponding subscription
-     */
-    unsubscribeAll(ID) {
-        const IDs = this.subscriptions.get(ID);
-        if (IDs) {
-            for (const [state, ID] of IDs) {
-                this.state[state].unsubscribe(ID);
-            }
-            this.subscriptions.delete(ID);
-        }
-    }
-    /**
-     * ReIndex Subscriptions
-     *
-     * When units of state are created lazily, this method updates
-     * each existing subscription to receive mutations occurring on
-     * recently created `State` instances that post-date prior
-     * subscriptions
-     */
-    reIndexSubscriptions(name) {
-        var _a, _b;
-        for (const [ID, unitSubscriptions] of this.subscriptions) {
-            const [stateName, listenerID] = unitSubscriptions[0];
-            const subscriptions = this.state[stateName]["emitter"].storage.get(stateName);
-            const listener = (_b = (_a = subscriptions === null || subscriptions === void 0 ? void 0 : subscriptions.storage) === null || _a === void 0 ? void 0 : _a.get) === null || _b === void 0 ? void 0 : _b.call(_a, listenerID);
-            if (listener) {
-                unitSubscriptions.push([name, this.state[name].subscribe(listener)]);
-                this.subscriptions.set(ID, unitSubscriptions);
-            }
-        }
-    }
-}
-exports.Galena = Galena;

package/dist/cjs/Galena/Guards.js

@@ -1,40 +0,0 @@
-"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 {
-    /**
-     * 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
-     */
-    warnForUndefinedStates(name, state) {
-        if (!(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`);
-        }
-    }
-    /**
-     * 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
-     */
-    guardDuplicateStates(name, state) {
-        if (name in state) {
-            console.warn(`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`);
-        }
-    }
-}
-exports.Guards = Guards;

package/dist/cjs/Galena/Scheduler.js

@@ -1,84 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Scheduler = void 0;
-const types_1 = require("./types");
-/**
- * Scheduler
- *
- * Scheduling dispatched events to state consumers is how Galena
- * out-performs just about every state management library out there.
- * The scheduler offers the ability to dispatch state updates on 3
- * priorities:
- *
- * 1. Immediate - Immediate synchronous task execution and propagation of
- * changes to consumers
- * 2. Microtask - Immediate task execution and scheduled propagation of
- * changes to consumers
- * 3. Batched - Immediate task execution and batched propagation of
- * changes to consumers
- *
- * This module manages the propagation of changes to State consumers
- * by implementing the three priorities outlined above
- */
-class Scheduler {
-    constructor() {
-        this.task = null;
-        this.schedule = null;
-        this.executeTasks = this.executeTasks.bind(this);
-    }
-    /**
-     * Schedule Task
-     *
-     * Given a task (the emission of state changes to consumers)
-     * and a priority, this method executes the task on the priority
-     * level specified
-     */
-    scheduleTask(task, priority) {
-        this.task = task;
-        switch (priority) {
-            case types_1.Priority.IMMEDIATE:
-                return this.executeTasks();
-            case types_1.Priority.MICROTASK:
-                return Promise.resolve().then(() => {
-                    return this.executeTasks();
-                });
-            case types_1.Priority.BATCHED:
-            default:
-                if (!this.schedule) {
-                    this.createSchedule();
-                }
-        }
-    }
-    /**
-     * Create Schedule
-     *
-     * Schedules the execution of the current task after 5 milliseconds
-     */
-    createSchedule() {
-        this.clearSchedule();
-        this.schedule = setTimeout(this.executeTasks, 5);
-    }
-    /**
-     * Clear Schedule
-     *
-     * Clears the schedule if it exists
-     */
-    clearSchedule() {
-        if (this.schedule !== null) {
-            clearTimeout(this.schedule);
-            this.schedule = null;
-        }
-    }
-    /**
-     * Execute Tasks
-     *
-     * Clears the schedule if it exists and executes the current task
-     */
-    executeTasks() {
-        var _a;
-        this.clearSchedule();
-        (_a = this.task) === null || _a === void 0 ? void 0 : _a.call(this);
-        this.task = null;
-    }
-}
-exports.Scheduler = Scheduler;