@figliolia/galena 2.3.5 → 3.0.0

package/package.json

@@ -1,73 +1,52 @@
 {
   "name": "@figliolia/galena",
-  "version": "2.3.5",
-  "description": "A performant state management library supporting mutable state, batched updates, middleware and a rich development API",
-  "main": "dist/cjs/index.js",
-  "module": "dist/mjs/index.js",
-  "types": "dist/types/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/mjs/index.js",
-      "require": "./dist/cjs/index.js",
-      "types": "./dist/types/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "src/*"
-  ],
-  "author": "Alex Figliolia",
-  "license": "MIT",
+  "version": "3.0.0",
+  "description": "A performant state management library supporting middleware and a rich developer API",
   "homepage": "https://github.com/alexfigliolia/galena#readme",
+  "license": "MIT",
+  "author": "Alex Figliolia",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alexfigliolia/galena.git"
   },
-  "keywords": [
-    "state",
-    "state management",
-    "mutable",
-    "extendable",
-    "event",
-    "emitter",
-    "flux",
-    "island",
-    "batch",
-    "performance"
+  "files": [
+    "dist",
+    "src",
+    "media"
   ],
-  "scripts": {
-    "build": "ts-packager -e src",
-    "lint": "tsx ci/commands/Lint.ts",
-    "test": "tsx ci/commands/Test.ts"
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
   },
-  "dependencies": {
-    "@figliolia/event-emitter": "^1.1.5"
+  "publishConfig": {
+    "access": "public"
   },
-  "peerDependencies": {
-    "@figliolia/event-emitter": "^1.1.5"
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint --type-aware --type-check --report-unused-disable-directives --fix && oxfmt"
   },
   "devDependencies": {
-    "@figliolia/child-process": "^1.0.1",
-    "@figliolia/ts-packager": "^1.1.0",
-    "@types/node": "^20.11.19",
-    "@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.6.1",
-    "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-json-format": "^2.0.1",
-    "eslint-plugin-prettier": "^5.1.3",
-    "eslint-plugin-simple-import-sort": "^10.0.0",
-    "eslint-plugin-unused-imports": "3",
-    "prettier": "^3.2.4",
-    "tsc-alias": "^1.8.8",
-    "tsx": "^4.7.1",
-    "typescript": "^5.3.3"
+    "@figliolia/event-emitter": "^1.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "eslint": "^10.0.3",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.36.0",
+    "oxlint-tsgolint": "^0.17.0",
+    "tsdown": "^0.21.1",
+    "typescript": "^5.9.3"
   },
-  "publishConfig": {
-    "access": "public"
+  "peerDependencies": {
+    "@figliolia/event-emitter": ">=1.2.0"
   }
-}
+}

package/src/Galena.ts

@@ -0,0 +1,120 @@
+import { EventEmitter } from "@figliolia/event-emitter";
+import type { Middleware } from "./Middleware";
+import type { State } from "./State";
+import type { AppSubscriber, GalenaSnapshot, StateTypes } from "./types";
+
+/**
+ * Galena
+ *
+ * Galena is 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({
+ *   // your reactive instances
+ * }, ...middleware);
+ *
+ * // to retreive and work with an individual unit
+ * const myUnit = AppState.get("<key>"); // Returns State<T>
+ *
+ * // to run a callback anytime a unit of state changes
+ * const unsubscribe = AppState.subscribe(({ updated }) => {
+ *   // do something with the `State` instance that updated
+ * });
+ * ```
+ */
+export class Galena<T extends Record<string, State<any>>> {
+  private Emitter = new EventEmitter<{ change: GalenaSnapshot<T> }>();
+  constructor(
+    public readonly state: T,
+    ...middleware: Middleware<StateTypes<T>>[]
+  ) {
+    this.registerMiddleware(...middleware);
+  }
+
+  public get<K extends Extract<keyof T, string>>(key: K) {
+    return this.state[key];
+  }
+
+  public subscribe = (subscriber: AppSubscriber<T>) => {
+    const ID = this.Emitter.on("change", subscriber);
+    const unsubscribers: (() => void)[] = [];
+    for (const key in this.state) {
+      const instance = this.state[key];
+      if (!instance) {
+        continue;
+      }
+      unsubscribers.push(
+        instance.subscribe(() =>
+          this.emit({ state: this.state, updated: instance }),
+        ),
+      );
+    }
+    return () => {
+      this.Emitter.off("change", ID);
+      while (unsubscribers.length) {
+        unsubscribers.pop?.()?.();
+      }
+    };
+  };
+
+  public registerMiddleware(...middlewares: Middleware<StateTypes<T>>[]) {
+    for (const key in this.state) {
+      this.state[key]?.registerMiddleware?.(...middlewares);
+    }
+  }
+
+  private emit<K extends Extract<keyof T, string>>(
+    event: GalenaSnapshot<T, K>,
+  ) {
+    this.Emitter.emit("change", event);
+  }
+}
+
+/**
+ * Create Galena
+ *
+ * Galena is 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";
+ *
+ * const AppState = createGalena({
+ *   // your reactive instances
+ * }, ...middleware);
+ *
+ * // to retreive and work with an individual unit
+ * const myUnit = AppState.get("<key>"); // Returns State<T>
+ *
+ * // to run a callback anytime a unit of state changes
+ * const unsubscribe = AppState.subscribe(({ updated }) => {
+ *   // do something with the `State` instance that updated
+ * });
+ * ```
+ */
+export const createGalena = <T extends Record<string, State<any>>>(
+  ...args: ConstructorParameters<typeof Galena<T>>
+) => {
+  return new Galena(...args);
+};

package/src/{Middlewares/Logger.ts → Logger.ts}

@@ -1,5 +1,5 @@
-import { State } from "Galena/State";
-import { Middleware } from "Middleware/Middleware";
+import { Middleware } from "./Middleware";
+import type { State } from "./State";
 
 /**
  * Logger
@@ -9,24 +9,26 @@ import { Middleware } from "Middleware/Middleware";
  * along with a before and after snapshot of the current state:
  *
  * ```typescript
- * const State = new Galena([new Logger()]);
- * // if using isolated state instances:
- * const MyState = new State(...args);
- * MyState.registerMiddleware(new Logger())
+ * const AppState = new Galena({}, new Logger());
+ * // or
+ * AppState.registerMiddlerware(new Logger());
+ * // or
+ * const MyState = new State(4, new Logger());
+ * // or
+ * MyState.registerMiddleware(new Logger());
  * ```
  */
-export class Logger extends Middleware {
-  private previousState: Record<string, any> | null = null;
+export class Logger<T = any> extends Middleware {
+  private previousState: T | null = null;
 
-  override onBeforeUpdate(state: State) {
-    this.previousState = State.clone(state.state);
+  override onBeforeUpdate(state: State<T>) {
+    this.previousState = state.getSnapshot();
   }
 
-  override onUpdate(state: State) {
+  override onUpdate(state: State<T>) {
     console.log(
       "%cMutation:",
       "color: rgb(187, 186, 186); font-weight: bold",
-      state.name,
       "@",
       this.time,
     );
@@ -38,9 +40,8 @@ export class Logger extends Middleware {
     console.log(
       "   %cNext State    ",
       "color: rgb(17, 118, 249); font-weight: bold",
-      state.getState(),
+      state.getSnapshot(),
     );
-    this.previousState = null;
   }
 
   /**

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"]
+>;