@figliolia/galena 1.0.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@figliolia/galena",
+  "version": "1.0.0",
+  "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",
+  "files": [
+    "dist",
+    "src/*"
+  ],
+  "author": "Alex Figliolia",
+  "license": "MIT",
+  "homepage": "https://github.com/alexfigliolia/galena#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexfigliolia/galena.git"
+  },
+  "keywords": [
+    "state",
+    "state management",
+    "mutable",
+    "extendable",
+    "event",
+    "emitter",
+    "flux",
+    "island",
+    "batch",
+    "performance"
+  ],
+  "scripts": {
+    "test": "jest",
+    "coverage": "jest --env=jsdom --coverage --testResultsProcessor ./node_modules/jest-junit",
+    "build": "rm -rf dist && tsc --project tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "lint": "tsc --noemit && eslint ./ --fix"
+  },
+  "dependencies": {
+    "@figliolia/event-emitter": "^1.0.6"
+  },
+  "devDependencies": {
+    "@types/node": "^16.7.13",
+    "@typescript-eslint/eslint-plugin": "^5.59.1",
+    "@typescript-eslint/parser": "^5.59.1",
+    "eslint": "^8.39.0",
+    "eslint-config-airbnb": "^19.0.4",
+    "eslint-config-airbnb-typescript": "^17.0.0",
+    "eslint-config-prettier": "^8.8.0",
+    "eslint-import-resolver-typescript": "^3.5.5",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-prettier": "^4.2.1",
+    "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "prettier": "^2.8.8",
+    "ts-node": "^10.9.1",
+    "tsc-alias": "^1.8.6",
+    "typescript": "^4.4.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Galena/Galena.ts

@@ -0,0 +1,253 @@
+import { AutoIncrementingID } from "@figliolia/event-emitter";
+
+import type { Middleware } from "Middleware/Middleware";
+
+import { State } from "Galena/State";
+
+/**
+ * ## Galena
+ *
+ * A performant global state solution that scales
+ *
+ * ### Creating State
+ *
+ * ```typescript
+ * // AppState.ts
+ * import { Galena } from "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.state
+ *  // do something with state changes!
+ * });
+ * ```
+ *
+ * #### Using Global Subscriptions
+ * ```typescript
+ * NavigationState.subscribeAll(galenaInstance => {
+ *  const { currentRoute } = galenaInstance.get("navigation").state
+ *  // do something with state changes!
+ * });
+ * ```
+ *
+ * ### Mutating State
+ * ```typescript
+ * NavigationState.update(state => {
+ *  state.currentRoute = "/profile";
+ *  // You can mutate state without creating new objects!
+ * });
+ * ```
+ */
+export class Galena<
+  T extends Record<string, State<any>> = Record<string, State<any>>
+> {
+  public readonly state = {} as T;
+  private readonly middleware: Middleware[] = [];
+  private readonly IDs = new AutoIncrementingID();
+  private readonly subscriptions = new Map<
+    string,
+    [state: string, ID: string][]
+  >();
+  constructor(middleware: Middleware[] = []) {
+    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
+   */
+  public composeState<
+    S extends any,
+    M extends typeof State<S> = typeof State<S>
+  >(
+    name: string,
+    initialState: S,
+    // @ts-ignore
+    Model: M = State<S>
+  ) {
+    const state = new Model(name, initialState);
+    state.registerMiddleware(...this.middleware);
+    this.mutable[name] = state;
+    this.reIndexSubscriptions(name);
+    return state as InstanceType<M>;
+  }
+
+  /**
+   * Get
+   *
+   * Returns a unit of `State` by name
+   */
+  public get<K extends keyof T>(name: K): T[K] {
+    return this.state[name];
+  }
+
+  /**
+   * Mutable
+   *
+   * Returns a mutable state instance
+   */
+  private get mutable() {
+    return this.state as Record<string, State>;
+  }
+
+  /**
+   * Update
+   *
+   * Runs a mutation on the specified unit of state
+   */
+  public update<K extends keyof T>(
+    name: K,
+    mutation: Parameters<T[K]["update"]>["0"]
+  ) {
+    return this.get(name).update(mutation);
+  }
+
+  /**
+   * Background Update
+   *
+   * Runs a higher priority mutation on the specified unit of
+   * state
+   */
+  public backgroundUpdate<K extends keyof T>(
+    name: K,
+    mutation: Parameters<T[K]["backgroundUpdate"]>["0"]
+  ) {
+    return this.get(name).backgroundUpdate(mutation);
+  }
+
+  /**
+   * Priority Update
+   *
+   * Runs an immediate priority mutation on the specified unit
+   * of state
+   */
+  public priorityUpdate<K extends keyof T>(
+    name: K,
+    mutation: Parameters<T[K]["priorityUpdate"]>["0"]
+  ) {
+    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
+   */
+  public subscribe<K extends keyof T>(
+    name: K,
+    mutation: Parameters<T[K]["subscribe"]>["0"]
+  ) {
+    return this.get(name).subscribe(mutation);
+  }
+
+  /**
+   * Unsubscribe
+   *
+   * 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) {
+    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
+   */
+  public subscribeAll(callback: (state: Galena<T>) => void) {
+    const subscriptionID = this.IDs.get();
+    const stateSubscriptions: [state: string, ID: string][] = [];
+    for (const key in this.state) {
+      stateSubscriptions.push([
+        key,
+        this.state[key].subscribe(() => {
+          callback(this);
+        }),
+      ]);
+    }
+    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
+   */
+  public unsubscribeAll(ID: string) {
+    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
+   */
+  private reIndexSubscriptions(name: string) {
+    for (const [ID, unitSubscriptions] of this.subscriptions) {
+      for (const [state, subscriptionID] of unitSubscriptions) {
+        const callback = this.state[state]["emitter"]
+          .get(state)
+          ?.get(subscriptionID);
+        if (callback) {
+          unitSubscriptions.push([
+            name,
+            this.state[name].subscribe(() => {
+              void callback(this.state);
+            }),
+          ]);
+          this.subscriptions.set(ID, unitSubscriptions);
+          break;
+        }
+      }
+    }
+  }
+}

package/src/Galena/Scheduler.ts

@@ -0,0 +1,85 @@
+import type { Task } from "./types";
+import { Priority } from "./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
+ */
+export class Scheduler<T extends Task = Task> {
+  private task: null | T = null;
+  private schedule: ReturnType<typeof setTimeout> | null = null;
+  constructor() {
+    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
+   */
+  protected scheduleTask(task: T, priority: Priority) {
+    this.task = task;
+    switch (priority) {
+      case Priority.IMMEDIATE:
+        return this.executeTasks();
+      case Priority.MICROTASK:
+        return Promise.resolve().then(() => {
+          return this.executeTasks();
+        });
+      case Priority.BATCHED:
+      default:
+        if (!this.schedule) {
+          this.createSchedule();
+        }
+    }
+  }
+
+  /**
+   * Create Schedule
+   *
+   * Schedules the execution of the current task after 5 milliseconds
+   */
+  private createSchedule() {
+    this.clearSchedule();
+    this.schedule = setTimeout(this.executeTasks, 5);
+  }
+
+  /**
+   * Clear Schedule
+   *
+   * Clears the schedule if it exists
+   */
+  private clearSchedule() {
+    if (this.schedule !== null) {
+      clearTimeout(this.schedule);
+      this.schedule = null;
+    }
+  }
+
+  /**
+   * Execute Tasks
+   *
+   * Clears the schedule if it exists and executes the current task
+   */
+  private executeTasks() {
+    this.clearSchedule();
+    this.task?.();
+    this.task = null;
+  }
+}

package/src/Galena/State.ts

@@ -0,0 +1,311 @@
+import { MiddlewareEvents } from "Middleware/types";
+import type { Middleware } from "Middleware/Middleware";
+import { EventEmitter } from "@figliolia/event-emitter";
+import { Priority, type MutationEvent } from "./types";
+import { Scheduler } from "./Scheduler";
+
+/**
+ * ### State
+ *
+ * The root of all reactivity in Galena. State instances can
+ * operate in isolation by calling `new State(...args)` or as
+ * part of your application's larger global state by using
+ * `new Galena().composeState()`.
+ *
+ * `State` instances operate on the premise of pub-sub and mutability.
+ * This provides significant performance improvement over more traditional
+ * state management tools because
+ *
+ * 1. Mutations can occur in O(1) space
+ * 2. Mutations can be batched when dispatching updates to subscribers
+ *
+ * When deciding how many `State` instances are required for your
+ * applications needs, we suggest creating and organizing state in
+ * accordance with your application logic. Meaning, you might have a
+ * `State` instance for navigation/routing, another `State` instance
+ * for storing user information, and so on. Performance can improve
+ * significantly when state is dispersed amongst multiple instances
+ *
+ * #### Creating State Instances
+ *
+ * ```typescript
+ * const MyState = new State("MyState", {
+ *   someData: true,
+ *   listItems: [1, 2, 3, 4];
+ *   // ...etc
+ * });
+ * ```
+ *
+ * #### Updating State
+ * ##### Synchronous updates
+ * ```typescript
+ * MyState.update((state) => {
+ *   state.listItems.push(5);
+ * });
+ * ```
+ * ##### Asynchronous updates
+ * ```typescript
+ * MyState.update(async (state) => {
+ *   const listItems = await fetch("/list-items");
+ *   state.listItems = listItems;
+ * });
+ * ```
+ *
+ * #### Subscribing to State Changes
+ * ```typescript
+ * MyState.subscribe(({ state }) => {
+ *   const { listItems } = state
+ *   // Do something with your list items!
+ * });
+ * ```
+ */
+export class State<T extends any = any> extends Scheduler {
+  public state: T;
+  public readonly name: string;
+  public readonly initialState: T;
+  private readonly middleware: Middleware[] = [];
+  private readonly emitter = new EventEmitter<MutationEvent<T>>();
+  constructor(name: string, initialState: T) {
+    super();
+    this.name = name;
+    this.state = initialState;
+    this.initialState = State.clone(initialState);
+  }
+
+  /**
+   * Get State
+   *
+   * Returns a readonly snapshot of the current state
+   */
+  public getState() {
+    return this.state as Readonly<T>;
+  }
+
+  /**
+   * Update
+   *
+   * Mutates state and notifies any open subscriptions. This method
+   * by default uses task batching for optimized performance. In almost
+   * every use-case, this method is the correct way to mutate state. If
+   * you need to bypass batching for higher-priority state updates, you
+   * can use `State.priorityUpdate()` or `State.backgroundUpdate()`
+   *
+   * ##### Synchronous updates
+   * ```typescript
+   * MyState.update((state, initialState) => {
+   *   state.listItems.push(5);
+   * });
+   * ```
+   * ##### Asynchronous updates
+   * ```typescript
+   * MyState.update(async (state, initialState) => {
+   *   const listItems = await fetch("/list-items");
+   *   state.listItems = listItems;
+   * });
+   * ```
+   */
+  public update = this.mutation(
+    (func: (state: T, initialState: T) => void | Promise<void>) => {
+      return func(this.state, this.initialState);
+    },
+    Priority.BATCHED
+  );
+
+  /**
+   * Background Update
+   *
+   * Mutates state and notifies any open subscriptions. This method
+   * bypasses Galena's internal task batching for a more immediate
+   * state update and propagation of state to consumers. It utilizes
+   * a micro-task that allows for the current call stack to clear
+   * ahead of propagating state updates to consumers
+   *
+   * ##### Synchronous updates
+   * ```typescript
+   * MyState.backgroundUpdate((state, initialState) => {
+   *   state.listItems.push(5);
+   * });
+   * ```
+   * ##### Asynchronous updates
+   * ```typescript
+   * MyState.backgroundUpdate(async (state, initialState) => {
+   *   const listItems = await fetch("/list-items");
+   *   state.listItems = listItems;
+   * });
+   * ```
+   */
+  public backgroundUpdate = this.mutation(
+    (func: (state: T, initialState: T) => void | Promise<void>) => {
+      return func(this.state, this.initialState);
+    },
+    Priority.MICROTASK
+  );
+
+  /**
+   * Priority Update
+   *
+   * Mutates state and notifies any open subscriptions. This method
+   * bypasses optimizations for task batching and scheduling. This means
+   * that state updates made with this method propagate to subscriptions
+   * as immediately as possible. Overusing this method can cause your
+   * state updates to perform slower in certain cases. The usage of this
+   * method should be conserved for state mutations that need to occur
+   * at a certain frame rate
+   *
+   * ##### Synchronous updates
+   * ```typescript
+   * MyState.priorityUpdate((state, initialState) => {
+   *   state.listItems.push(5);
+   * });
+   * ```
+   * ##### Asynchronous updates
+   * ```typescript
+   * MyState.priorityUpdate(async (state, initialState) => {
+   *   const listItems = await fetch("/list-items");
+   *   state.listItems = listItems;
+   * });
+   * ```
+   */
+  public priorityUpdate = this.mutation(
+    (func: (state: T, initialState: T) => void | Promise<void>) => {
+      return func(this.state, this.initialState);
+    },
+    Priority.IMMEDIATE
+  );
+
+  /**
+   * Reset
+   *
+   * Resets the current state to its initial state
+   */
+  public reset = this.mutation(() => {
+    this.state = State.clone(this.initialState);
+  });
+
+  /**
+   * Mutation
+   *
+   * This method can be used to wrap arbitrary functions that when invoked
+   * will:
+   * 1. Notify your subscriptions with the latest state
+   * 2. Execute any registered middleware (such as loggers or profiling tools)
+   *
+   * Using this method, developers can compose and extend `Galena`'s internal
+   * infrastructure for state mutations to create proprietary models for your
+   * state
+   *
+   * ```typescript
+   * import { State } from "galena";
+   *
+   * // Extend of Galena State
+   * class MyState extends State {
+   *   addListItem = mutation((newListItem) => {
+   *     this.state.list.push(newListItem);
+   *   });
+   * }
+   *
+   * // Create an instance
+   * const myState = new MyState("myState", { list: [] });
+   *
+   * // Invoke your custom mutation method
+   * myState.addListItem("new-item");
+   * ```
+   */
+  protected mutation<F extends (...args: any[]) => any>(
+    func: F,
+    priority: Priority = Priority.BATCHED
+  ) {
+    return (...args: Parameters<F>) => {
+      this.lifeCycleEvent(MiddlewareEvents.onBeforeUpdate);
+      const returnValue = func(...args);
+      if (returnValue instanceof Promise) {
+        return returnValue.then((v) => {
+          this.scheduleUpdate(priority);
+          return v;
+        });
+      }
+      this.scheduleUpdate(priority);
+      return returnValue;
+    };
+  }
+
+  /**
+   * Schedule Update
+   *
+   * Schedules an update to State subscribers and emits the
+   * `onUpdate` lifecycle hook
+   */
+  private scheduleUpdate(priority: Priority) {
+    this.lifeCycleEvent(MiddlewareEvents.onUpdate);
+    void this.scheduleTask(() => this.emitter.emit(this.name, this), priority);
+  }
+
+  /**
+   * Register Middleware
+   *
+   * Caches a `Middleware` instance and invokes its
+   * lifecycle subscriptions on all state transitions
+   */
+  public registerMiddleware(...middleware: Middleware[]) {
+    this.middleware.push(...middleware);
+  }
+
+  /**
+   * Subscribe
+   *
+   * Registers a subscription on the state instance. The
+   * callback you provide will execute each time state changes.
+   * Returns a unique identifier for your subscription
+   */
+  public subscribe(callback: (nextState: State<T>) => void) {
+    return this.emitter.on(this.name, callback);
+  }
+
+  /**
+   * Unsubscribe
+   *
+   * Given a subscription ID, removes a registered subscription
+   * from the `State` instance
+   */
+  public unsubscribe(ID: string) {
+    return this.emitter.off(this.name, ID);
+  }
+
+  /**
+   * Life Cycle Event
+   *
+   * Triggers a life cycle event for each registered middleware
+   */
+  private lifeCycleEvent<E extends MiddlewareEvents>(event: E) {
+    const maxIndex = this.middleware.length - 1;
+    for (let i = maxIndex; i > -1; i--) {
+      this.middleware[i][event](this);
+    }
+  }
+
+  /**
+   * Clone
+   *
+   * `State` instances accept any value as a form of reactive
+   * state. In order to maintain the initial state past any state
+   * transitions, this method clones the initial values provided
+   * to the `State` constructor and caches them to allow for
+   * developers to easily reset their current state back to its
+   * initial value
+   */
+  public static clone<T>(state: T): T {
+    if (Array.isArray(state)) {
+      return [...state] as T;
+    }
+    if (state instanceof Set) {
+      return new Set(state) as T;
+    }
+    if (state instanceof Map) {
+      return new Map(state) as T;
+    }
+    if (state && typeof state === "object") {
+      return { ...state } as T;
+    }
+    return state;
+  }
+}

package/src/Galena/index.ts

@@ -0,0 +1,3 @@
+export { Galena } from "./Galena";
+export { State } from "./State";
+export * from "./types";