@figliolia/galena 2.3.5 → 3.0.1

package/dist/types/Middlewares/Profiler.d.ts

@@ -1,22 +0,0 @@
-import type { State } from "../Galena/State";
-import { Middleware } from "../Middleware/Middleware";
-/**
- * Profiler
- *
- * A logger for state transitions exceeding a given threshold
- * for duration:
- *
- * ```typescript
- * const State = new Galena([new Profiler()]);
- * // if using isolated state instances:
- * const MyState = new State(...args);
- * MyState.registerMiddleware(new Profiler())
- * ```
- */
-export declare class Profiler extends Middleware {
-    private threshold;
-    private startTime;
-    constructor(threshold?: number);
-    onBeforeUpdate(_: State): void;
-    onUpdate(nextState: State): void;
-}

package/dist/types/Middlewares/index.d.ts

@@ -1,2 +0,0 @@
-export { Logger } from "./Logger";
-export { Profiler } from "./Profiler";

package/dist/types/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./Galena";
-export * from "./Middleware";
-export * from "./Middlewares";

package/src/Galena/Galena.ts

@@ -1,252 +0,0 @@
-import { AutoIncrementingID } from "@figliolia/event-emitter";
-import { State } from "Galena/State";
-import type { Middleware } from "Middleware/Middleware";
-import { Guards } from "./Guards";
-import type { Subscription, SubscriptionTuple } from "./types";
-
-/**
- * ## 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!
- * });
- * ```
- */
-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, SubscriptionTuple[]>();
-  constructor(middleware: Middleware[] = []) {
-    super();
-    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 Record<string, any>, M extends typeof State<S>>(
-    name: string,
-    initialState: S,
-    Model?: M,
-  ) {
-    this.guardDuplicateStates(name, this.state);
-    const StateModel = Model || State<S>;
-    const state = new StateModel(name, initialState);
-    state.registerMiddleware(...this.middleware);
-    this.mutable[name] = state;
-    this.reIndexSubscriptions(name);
-    return state as InstanceType<M>;
-  }
-
-  /**
-   * Get State
-   *
-   * Returns a mutable state instance
-   */
-  public getState() {
-    return this.state as Readonly<T>;
-  }
-
-  /**
-   * Get
-   *
-   * Returns a unit of `State` by name
-   */
-  public get<K extends Extract<keyof T, string>>(name: K): T[K] {
-    this.warnForUndefinedStates(name, this.state);
-    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 Extract<keyof T, string>>(
-    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 Extract<keyof T, string>>(
-    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 Extract<keyof T, string>>(
-    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 Extract<keyof T, string>>(
-    name: K,
-    callback: Parameters<T[K]["subscribe"]>["0"],
-  ) {
-    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
-   */
-  public unsubscribe<K extends Extract<keyof T, string>>(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: Subscription<T>) {
-    const stateSubscriptions: [state: string, ID: string][] = [];
-    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
-   */
-  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) {
-      const [stateName, listenerID] = unitSubscriptions[0];
-      const subscriptions =
-        this.state[stateName]["emitter"].storage.get(stateName);
-      const listener = subscriptions?.storage?.get?.(listenerID);
-      if (listener) {
-        unitSubscriptions.push([name, this.state[name].subscribe(listener)]);
-        this.subscriptions.set(ID, unitSubscriptions);
-      }
-    }
-  }
-}

package/src/Galena/Guards.ts

@@ -1,49 +0,0 @@
-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<T extends Record<string, State<any>>>(
-    name: string,
-    state: T,
-  ) {
-    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
-   */
-  protected guardDuplicateStates<T extends Record<string, State<any>>>(
-    name: string,
-    state: T,
-  ) {
-    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`,
-      );
-    }
-  }
-}

package/src/Galena/Scheduler.ts

@@ -1,85 +0,0 @@
-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;
-  }
-}