@figliolia/galena 1.0.0

package/dist/Galena/Galena.js

@@ -0,0 +1,219 @@
+"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");
+/**
+ * ## 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!
+ * });
+ * ```
+ */
+class Galena {
+    constructor(middleware = []) {
+        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, 
+    // @ts-ignore
+    Model = (State_1.State)) {
+        const state = new Model(name, initialState);
+        state.registerMiddleware(...this.middleware);
+        this.mutable[name] = state;
+        this.reIndexSubscriptions(name);
+        return state;
+    }
+    /**
+     * Get
+     *
+     * Returns a unit of `State` by name
+     */
+    get(name) {
+        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, mutation) {
+        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
+     */
+    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 subscriptionID = this.IDs.get();
+        const stateSubscriptions = [];
+        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
+     */
+    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;
+        for (const [ID, unitSubscriptions] of this.subscriptions) {
+            for (const [state, subscriptionID] of unitSubscriptions) {
+                const callback = (_a = this.state[state]["emitter"]
+                    .get(state)) === null || _a === void 0 ? void 0 : _a.get(subscriptionID);
+                if (callback) {
+                    unitSubscriptions.push([
+                        name,
+                        this.state[name].subscribe(() => {
+                            void callback(this.state);
+                        }),
+                    ]);
+                    this.subscriptions.set(ID, unitSubscriptions);
+                    break;
+                }
+            }
+        }
+    }
+}
+exports.Galena = Galena;

package/dist/Galena/Scheduler.d.ts

@@ -0,0 +1,51 @@
+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 declare class Scheduler<T extends Task = Task> {
+    private task;
+    private schedule;
+    constructor();
+    /**
+     * 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): void | Promise<void>;
+    /**
+     * Create Schedule
+     *
+     * Schedules the execution of the current task after 5 milliseconds
+     */
+    private createSchedule;
+    /**
+     * Clear Schedule
+     *
+     * Clears the schedule if it exists
+     */
+    private clearSchedule;
+    /**
+     * Execute Tasks
+     *
+     * Clears the schedule if it exists and executes the current task
+     */
+    private executeTasks;
+}

package/dist/Galena/Scheduler.js

@@ -0,0 +1,84 @@
+"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;

package/dist/Galena/State.d.ts

@@ -0,0 +1,228 @@
+import type { Middleware } from "../Middleware/Middleware";
+import { Priority } 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 declare class State<T extends any = any> extends Scheduler {
+    state: T;
+    readonly name: string;
+    readonly initialState: T;
+    private readonly middleware;
+    private readonly emitter;
+    constructor(name: string, initialState: T);
+    /**
+     * Get State
+     *
+     * Returns a readonly snapshot of the current state
+     */
+    getState(): 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;
+     * });
+     * ```
+     */
+    update: (func: (state: T, initialState: T) => void | Promise<void>) => any;
+    /**
+     * 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;
+     * });
+     * ```
+     */
+    backgroundUpdate: (func: (state: T, initialState: T) => void | Promise<void>) => any;
+    /**
+     * 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;
+     * });
+     * ```
+     */
+    priorityUpdate: (func: (state: T, initialState: T) => void | Promise<void>) => any;
+    /**
+     * Reset
+     *
+     * Resets the current state to its initial state
+     */
+    reset: () => any;
+    /**
+     * 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): (...args: Parameters<F>) => any;
+    /**
+     * Schedule Update
+     *
+     * Schedules an update to State subscribers and emits the
+     * `onUpdate` lifecycle hook
+     */
+    private scheduleUpdate;
+    /**
+     * Register Middleware
+     *
+     * Caches a `Middleware` instance and invokes its
+     * lifecycle subscriptions on all state transitions
+     */
+    registerMiddleware(...middleware: Middleware[]): void;
+    /**
+     * 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
+     */
+    subscribe(callback: (nextState: State<T>) => void): string;
+    /**
+     * Unsubscribe
+     *
+     * Given a subscription ID, removes a registered subscription
+     * from the `State` instance
+     */
+    unsubscribe(ID: string): boolean | undefined;
+    /**
+     * Life Cycle Event
+     *
+     * Triggers a life cycle event for each registered middleware
+     */
+    private lifeCycleEvent;
+    /**
+     * 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
+     */
+    static clone<T>(state: T): T;
+}