@figliolia/galena 1.0.0

package/dist/Galena/State.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.State = void 0;
+const types_1 = require("../Middleware/types");
+const event_emitter_1 = require("@figliolia/event-emitter");
+const types_2 = require("./types");
+const Scheduler_1 = require("./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!
+ * });
+ * ```
+ */
+class State extends Scheduler_1.Scheduler {
+    constructor(name, initialState) {
+        super();
+        this.middleware = [];
+        this.emitter = new event_emitter_1.EventEmitter();
+        /**
+         * 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;
+         * });
+         * ```
+         */
+        this.update = this.mutation((func) => {
+            return func(this.state, this.initialState);
+        }, types_2.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;
+         * });
+         * ```
+         */
+        this.backgroundUpdate = this.mutation((func) => {
+            return func(this.state, this.initialState);
+        }, types_2.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;
+         * });
+         * ```
+         */
+        this.priorityUpdate = this.mutation((func) => {
+            return func(this.state, this.initialState);
+        }, types_2.Priority.IMMEDIATE);
+        /**
+         * Reset
+         *
+         * Resets the current state to its initial state
+         */
+        this.reset = this.mutation(() => {
+            this.state = State.clone(this.initialState);
+        });
+        this.name = name;
+        this.state = initialState;
+        this.initialState = State.clone(initialState);
+    }
+    /**
+     * Get State
+     *
+     * Returns a readonly snapshot of the current state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * 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");
+     * ```
+     */
+    mutation(func, priority = types_2.Priority.BATCHED) {
+        return (...args) => {
+            this.lifeCycleEvent(types_1.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
+     */
+    scheduleUpdate(priority) {
+        this.lifeCycleEvent(types_1.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
+     */
+    registerMiddleware(...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
+     */
+    subscribe(callback) {
+        return this.emitter.on(this.name, callback);
+    }
+    /**
+     * Unsubscribe
+     *
+     * Given a subscription ID, removes a registered subscription
+     * from the `State` instance
+     */
+    unsubscribe(ID) {
+        return this.emitter.off(this.name, ID);
+    }
+    /**
+     * Life Cycle Event
+     *
+     * Triggers a life cycle event for each registered middleware
+     */
+    lifeCycleEvent(event) {
+        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
+     */
+    static clone(state) {
+        if (Array.isArray(state)) {
+            return [...state];
+        }
+        if (state instanceof Set) {
+            return new Set(state);
+        }
+        if (state instanceof Map) {
+            return new Map(state);
+        }
+        if (state && typeof state === "object") {
+            return Object.assign({}, state);
+        }
+        return state;
+    }
+}
+exports.State = State;

package/dist/Galena/index.d.ts

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

package/dist/Galena/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.State = exports.Galena = void 0;
+var Galena_1 = require("./Galena");
+Object.defineProperty(exports, "Galena", { enumerable: true, get: function () { return Galena_1.Galena; } });
+var State_1 = require("./State");
+Object.defineProperty(exports, "State", { enumerable: true, get: function () { return State_1.State; } });
+__exportStar(require("./types"), exports);

package/dist/Galena/types.d.ts

@@ -0,0 +1,10 @@
+import type { State } from "./State";
+export type MutationEvent<T extends any> = {
+    [key: State<T>["name"]]: State<T>;
+};
+export declare enum Priority {
+    "IMMEDIATE" = 1,
+    "MICROTASK" = 2,
+    "BATCHED" = 3
+}
+export type Task = () => void;

package/dist/Galena/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Priority = void 0;
+var Priority;
+(function (Priority) {
+    Priority[Priority["IMMEDIATE"] = 1] = "IMMEDIATE";
+    Priority[Priority["MICROTASK"] = 2] = "MICROTASK";
+    Priority[Priority["BATCHED"] = 3] = "BATCHED";
+})(Priority = exports.Priority || (exports.Priority = {}));

package/dist/Middleware/Middleware.d.ts

@@ -0,0 +1,54 @@
+import { EventEmitter } from "@figliolia/event-emitter";
+import type { State } from "../Galena/State";
+import type { MiddlewareEvent } from "./types";
+/**
+ * # 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 declare class Middleware<T extends any = any> {
+    static Emitter: EventEmitter<MiddlewareEvent<any>>;
+    constructor();
+    /**
+     * Validate Event
+     *
+     * Asserts that a given method on an extending class prototype
+     * is one of the supported `Galena` lifecycle events
+     */
+    private static validateEvent;
+    /**
+     * On Before Update
+     *
+     * An event emitted each time a `State` mutation is enqueued
+     */
+    onBeforeUpdate(state: State<T>): void;
+    /**
+     * On Update
+     *
+     * An event emitted each time a `State` instance is mutated
+     */
+    onUpdate(state: State<T>): void;
+}

package/dist/Middleware/Middleware.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Middleware = void 0;
+const event_emitter_1 = require("@figliolia/event-emitter");
+const types_1 = require("./types");
+/**
+ * # 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);
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class Middleware {
+    constructor() {
+        const extension = Object.getPrototypeOf(this);
+        const methods = Object.getOwnPropertyNames(extension);
+        methods.forEach((event) => {
+            if (Middleware.validateEvent(event)) {
+                Middleware.Emitter.on(types_1.MiddlewareEvents[event], this[event]);
+            }
+        });
+    }
+    /**
+     * Validate Event
+     *
+     * Asserts that a given method on an extending class prototype
+     * is one of the supported `Galena` lifecycle events
+     */
+    static validateEvent(event) {
+        return event in types_1.MiddlewareEvents;
+    }
+    /* Life Cycle Events */
+    /**
+     * On Before Update
+     *
+     * An event emitted each time a `State` mutation is enqueued
+     */
+    onBeforeUpdate(state) { }
+    /**
+     * On Update
+     *
+     * An event emitted each time a `State` instance is mutated
+     */
+    onUpdate(state) { }
+}
+exports.Middleware = Middleware;
+Middleware.Emitter = new event_emitter_1.EventEmitter();

package/dist/Middleware/index.d.ts

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

package/dist/Middleware/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Middleware = void 0;
+var Middleware_1 = require("./Middleware");
+Object.defineProperty(exports, "Middleware", { enumerable: true, get: function () { return Middleware_1.Middleware; } });
+__exportStar(require("./types"), exports);

package/dist/Middleware/types.d.ts

@@ -0,0 +1,6 @@
+import type { State } from "../Galena/State";
+export declare enum MiddlewareEvents {
+    "onUpdate" = "onUpdate",
+    "onBeforeUpdate" = "onBeforeUpdate"
+}
+export type MiddlewareEvent<T extends any = any> = Record<MiddlewareEvents, State<T>>;

package/dist/Middleware/types.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiddlewareEvents = void 0;
+var MiddlewareEvents;
+(function (MiddlewareEvents) {
+    MiddlewareEvents["onUpdate"] = "onUpdate";
+    MiddlewareEvents["onBeforeUpdate"] = "onBeforeUpdate";
+})(MiddlewareEvents = exports.MiddlewareEvents || (exports.MiddlewareEvents = {}));

package/dist/Middlewares/Logger.d.ts

@@ -0,0 +1,27 @@
+import { State } from "../Galena/State";
+import { Middleware } from "../Middleware/Middleware";
+/**
+ * Logger
+ *
+ * A middleware for Redux-style logging! Each state transition
+ * will log to the console the `State` instance that changed
+ * 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())
+ * ```
+ */
+export declare class Logger extends Middleware {
+    private previousState;
+    onBeforeUpdate(state: State): void;
+    onUpdate(state: State): void;
+    /**
+     * Time
+     *
+     * Returns the time in which a given state transition completed
+     */
+    private get time();
+}

package/dist/Middlewares/Logger.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const State_1 = require("../Galena/State");
+const Middleware_1 = require("../Middleware/Middleware");
+/**
+ * Logger
+ *
+ * A middleware for Redux-style logging! Each state transition
+ * will log to the console the `State` instance that changed
+ * 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())
+ * ```
+ */
+class Logger extends Middleware_1.Middleware {
+    constructor() {
+        super(...arguments);
+        this.previousState = null;
+    }
+    onBeforeUpdate(state) {
+        this.previousState = State_1.State.clone(state.state);
+    }
+    onUpdate(state) {
+        console.log("%cMutation:", "color: rgb(187, 186, 186); font-weight: bold", state.name, "@", this.time);
+        console.log("   %cPrevious State", "color: #26ad65; font-weight: bold", this.previousState);
+        console.log("   %cNext State    ", "color: rgb(17, 118, 249); font-weight: bold", state.getState());
+        this.previousState = null;
+    }
+    /**
+     * Time
+     *
+     * Returns the time in which a given state transition completed
+     */
+    get time() {
+        const date = new Date();
+        const mHours = date.getHours();
+        const hours = mHours > 12 ? mHours - 12 : mHours;
+        const mins = date.getMinutes();
+        const minutes = mins.toString().length === 1 ? `0${mins}` : mins;
+        const secs = date.getSeconds();
+        const seconds = secs.toString().length === 1 ? `0${secs}` : secs;
+        const milliseconds = date.getMilliseconds();
+        return `${hours}:${minutes}:${seconds}:${milliseconds}`;
+    }
+}
+exports.Logger = Logger;

package/dist/Middlewares/Profiler.d.ts

@@ -0,0 +1,22 @@
+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/Middlewares/Profiler.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Profiler = void 0;
+const Middleware_1 = require("../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())
+ * ```
+ */
+class Profiler extends Middleware_1.Middleware {
+    constructor(threshold = 16) {
+        super();
+        this.startTime = null;
+        this.threshold = threshold;
+    }
+    onBeforeUpdate(_) {
+        this.startTime = performance.now();
+    }
+    onUpdate(nextState) {
+        if (this.startTime) {
+            const endTime = performance.now();
+            const diff = endTime - this.startTime;
+            if (diff > this.threshold) {
+                console.warn("Slow state transition detected", nextState);
+                console.warn(`The last transition took ${diff}ms`);
+            }
+        }
+    }
+}
+exports.Profiler = Profiler;

package/dist/Middlewares/index.d.ts

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

package/dist/Middlewares/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Profiler = exports.Logger = void 0;
+var Logger_1 = require("./Logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return Logger_1.Logger; } });
+var Profiler_1 = require("./Profiler");
+Object.defineProperty(exports, "Profiler", { enumerable: true, get: function () { return Profiler_1.Profiler; } });

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Galena"), exports);
+__exportStar(require("./Middleware"), exports);
+__exportStar(require("./Middlewares"), exports);