@figliolia/galena 2.3.5 → 3.0.1

package/dist/mjs/Middleware/types.js

@@ -1,5 +0,0 @@
-export var MiddlewareEvents;
-(function (MiddlewareEvents) {
-    MiddlewareEvents["onUpdate"] = "onUpdate";
-    MiddlewareEvents["onBeforeUpdate"] = "onBeforeUpdate";
-})(MiddlewareEvents || (MiddlewareEvents = {}));

package/dist/mjs/Middlewares/Logger.js

@@ -1,44 +0,0 @@
-import { State } from "../Galena/State.js";
-import { Middleware } from "../Middleware/Middleware.js";
-/**
- * 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 class Logger extends Middleware {
-    previousState = null;
-    onBeforeUpdate(state) {
-        this.previousState = 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}`;
-    }
-}

package/dist/mjs/Middlewares/Profiler.js

@@ -1,35 +0,0 @@
-import { Middleware } from "../Middleware/Middleware.js";
-/**
- * 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 {
-    threshold;
-    startTime = null;
-    constructor(threshold = 16) {
-        super();
-        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(`A slow state transition was detected on ${nextState.name}`, nextState.getState());
-                console.warn(`The last transition took ${diff}ms`);
-            }
-        }
-    }
-}

package/dist/mjs/Middlewares/index.js

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

package/dist/mjs/index.js

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

package/dist/mjs/package.json

@@ -1,4 +0,0 @@
-{
-  "type": "module",
-  "exports": "./index.js"
-}

package/dist/types/Galena/Galena.d.ts

@@ -1,160 +0,0 @@
-import { State } from "./State";
-import type { Middleware } from "../Middleware/Middleware";
-import { Guards } from "./Guards";
-import type { Subscription } 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 declare class Galena<T extends Record<string, State<any>> = Record<string, State<any>>> extends Guards {
-    readonly state: T;
-    private readonly middleware;
-    private readonly IDs;
-    private readonly subscriptions;
-    constructor(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<S extends Record<string, any>, M extends typeof State<S>>(name: string, initialState: S, Model?: M): InstanceType<M>;
-    /**
-     * Get State
-     *
-     * Returns a mutable state instance
-     */
-    getState(): Readonly<T>;
-    /**
-     * Get
-     *
-     * Returns a unit of `State` by name
-     */
-    get<K extends Extract<keyof T, string>>(name: K): T[K];
-    /**
-     * Mutable
-     *
-     * Returns a mutable state instance
-     */
-    private get mutable();
-    /**
-     * Update
-     *
-     * Runs a mutation on the specified unit of state
-     */
-    update<K extends Extract<keyof T, string>>(name: K, mutation: Parameters<T[K]["update"]>["0"]): any;
-    /**
-     * Background Update
-     *
-     * Runs a higher priority mutation on the specified unit of
-     * state
-     */
-    backgroundUpdate<K extends Extract<keyof T, string>>(name: K, mutation: Parameters<T[K]["backgroundUpdate"]>["0"]): any;
-    /**
-     * Priority Update
-     *
-     * Runs an immediate priority mutation on the specified unit
-     * of state
-     */
-    priorityUpdate<K extends Extract<keyof T, string>>(name: K, mutation: Parameters<T[K]["priorityUpdate"]>["0"]): any;
-    /**
-     * 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<K extends Extract<keyof T, string>>(name: K, callback: Parameters<T[K]["subscribe"]>["0"]): string;
-    /**
-     * Unsubscribe
-     *
-     * Given a subscription ID returned from the `subscribe` method,
-     * this method removes and cleans up the corresponding subscription
-     */
-    unsubscribe<K extends Extract<keyof T, string>>(name: K, ID: string): boolean | undefined;
-    /**
-     * 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: Subscription<T>): string;
-    /**
-     * Unsubscribe
-     *
-     * Given a subscription ID returned from the `subscribeAll()` method,
-     * this method removes and cleans up the corresponding subscription
-     */
-    unsubscribeAll(ID: string): void;
-    /**
-     * 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;
-}

package/dist/types/Galena/Guards.d.ts

@@ -1,29 +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 declare 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): void;
-    /**
-     * 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): void;
-}

package/dist/types/Galena/Scheduler.d.ts

@@ -1,51 +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 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/types/Galena/State.d.ts

@@ -1,235 +0,0 @@
-import type { Middleware } from "../Middleware/Middleware";
-import { Scheduler } from "./Scheduler";
-import type { 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 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 "@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): (...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: Subscription<T>): string;
-    /**
-     * Unsubscribe
-     *
-     * Given a subscription ID, removes a registered subscription
-     * from the `State` instance
-     */
-    unsubscribe(ID: string): boolean | undefined;
-    /**
-     * Clear All Subscriptions
-     *
-     * Removes all open subscriptions to the `State` instance
-     */
-    clearAllSubscriptions(): void;
-    /**
-     * 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;
-}

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

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

package/dist/types/Galena/types.d.ts

@@ -1,13 +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 declare 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/dist/types/Middleware/Middleware.d.ts

@@ -1,43 +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 declare class Middleware<T extends any = any> {
-    /**
-     * 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/types/Middleware/index.d.ts

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

package/dist/types/Middleware/types.d.ts

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

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

@@ -1,27 +0,0 @@
-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();
-}