@figliolia/galena 2.3.4 → 3.0.0

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;
-  }
-}

package/src/Galena/State.ts

@@ -1,344 +0,0 @@
-import { EventEmitter } from "@figliolia/event-emitter";
-import type { Middleware } from "Middleware/Middleware";
-import { MiddlewareEvents } from "Middleware/types";
-import { Scheduler } from "./Scheduler";
-import type { MutationEvent, Subscription } from "./types";
-import { Priority } from "./types";
-
-/**
- * ### 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 "@figliolia/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.state),
-      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: Subscription<T>) {
-    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);
-  }
-
-  /**
-   * Clear All Subscriptions
-   *
-   * Removes all open subscriptions to the `State` instance
-   */
-  public clearAllSubscriptions() {
-    return this.emitter.storage.clear();
-  }
-
-  /**
-   * 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 {
-    switch (typeof state) {
-      case "string":
-        return String(state) as T;
-      case "bigint":
-        return BigInt(state) as T;
-      case "boolean":
-        return Boolean(state) as T;
-      case "number":
-        return Number(state) as T;
-      case "symbol":
-      case "function":
-        return state;
-      case "undefined":
-        return undefined as T;
-      case "object":
-      default:
-        if (!state) {
-          return null as 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

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

package/src/Galena/types.ts

@@ -1,18 +0,0 @@
-import type { Callback } from "@figliolia/event-emitter";
-import type { State } from "./State";
-
-export type MutationEvent<T extends any> = {
-  [key: State<T>["name"]]: T;
-};
-
-export enum Priority {
-  "IMMEDIATE" = 1,
-  "MICROTASK" = 2,
-  "BATCHED" = 3,
-}
-
-export type Task = () => void;
-
-export type SubscriptionTuple = [state: string, ID: string];
-
-export type Subscription<T> = Callback<[nextState: T]>;

package/src/Middleware/Middleware.ts

@@ -1,45 +0,0 @@
-import type { State } from "Galena/State";
-
-/**
- * # Middleware
- *
- * A root interface for all `Galena` Middleware. When creating
- * a middleware for your `Galena` state, simply extend this
- * class any override any of its public lifecycle methods.
- *
- * ### Creating a Profiling Middleware
- *
- * ```typescript
- * export class ProfilerMiddleware extends Middleware {
- *   updateState: number | null = null;
- *
- *   override onBeforeUpdate(state: State) {
- *     this.updateStart = performance.now();
- *   }
- *
- *   override onUpdate(state: State) {
- *     if(this.updateStart) {
- *       const timeToUpdate = performance.now() - this.updateStart;
- *       if(timeToUpdate > 16) {
- *         console.warn("A state transition took more than 16 milliseconds!", State);
- *       }
- *     }
- *   }
- * }
- * ```
- */
-export class Middleware<T extends any = any> {
-  /**
-   * On Before Update
-   *
-   * An event emitted each time a `State` mutation is enqueued
-   */
-  public onBeforeUpdate(_state: State<T>) {}
-
-  /**
-   * On Update
-   *
-   * An event emitted each time a `State` instance is mutated
-   */
-  public onUpdate(_state: State<T>) {}
-}

package/src/Middleware/index.ts

@@ -1,2 +0,0 @@
-export { Middleware } from "./Middleware";
-export * from "./types";

package/src/Middleware/types.ts

@@ -1,4 +0,0 @@
-export enum MiddlewareEvents {
-  "onUpdate" = "onUpdate",
-  "onBeforeUpdate" = "onBeforeUpdate",
-}

package/src/Middlewares/Profiler.ts

@@ -1,41 +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 class Profiler extends Middleware {
-  private threshold: number;
-  private startTime: number | null = null;
-  constructor(threshold = 16) {
-    super();
-    this.threshold = threshold;
-  }
-  onBeforeUpdate(_: State) {
-    this.startTime = performance.now();
-  }
-
-  onUpdate(nextState: State) {
-    if (this.startTime) {
-      const endTime = performance.now();
-      const diff = endTime - this.startTime;
-      if (diff > this.threshold) {
-        console.warn(
-          `A slow state transition was detected on ${nextState.name}`,
-          nextState.getState(),
-        );
-        console.warn(`The last transition took ${diff}ms`);
-      }
-    }
-  }
-}

package/src/Middlewares/index.ts

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