@giveback007/util-lib 2.1.3 → 2.3.1

package/src/state-manager.ts

@@ -0,0 +1,301 @@
+import type {
+    Action, actSubFct, lsOptions, stateSubFct
+} from './@state.types';
+
+import {
+    Dict, KeysOfValueType
+} from '.'
+
+import {
+    wait, equal, objExtract,
+    isType, objKeys, clone
+} from '.';
+
+export class StateManager<
+    State extends {},
+    Act extends Action<any, any> = Action<any, any>,
+    Key extends Extract<keyof State, string> = Extract<keyof State, string>
+> {
+
+    private prevState: State | null = null;
+    private emittedState: State | null = null;
+    private state: State;
+
+    private readonly useLS: lsOptions<Key> | false = false;
+
+    private stateSubDict: Dict<stateSubFct<State>> = {};
+    private actionSubDict: Dict<actSubFct<Act>> = {};
+
+    private stateWasUpdated = true;
+    private keysChanged: { [K in Key]?: true } = {};
+
+    private throttledState: Dict<Partial<State>> = {};
+    private throttlersRunning: Dict<boolean> = {};
+    /**
+     * The local storage takes an id, this id
+     * should be unique in order to ensure that the
+     * storage is unique to the given state object
+     */
+    constructor(
+        initialState: State,
+        useLocalStorage?: lsOptions<Key>
+    ) {
+        let state = {} as State;
+
+        if (useLocalStorage) {
+            const { useKeys, ignoreKeys, id } = useLocalStorage;
+
+            if (useKeys && ignoreKeys) throw Error(
+                '"useKeys" & "ignoreKeys" are mutually '
+                + 'exclusive, only use one or the other.'
+            );
+
+            this.useLS = useLocalStorage;
+            const lsId = this.useLS.id = id + '-utilStateManager';
+
+            state = {
+                ...initialState,
+                ...this.stateFromLS(),
+            };
+
+            addEventListener('storage', (e: StorageEvent) => {
+                if (e.key !== lsId) return;
+
+                let fromLS = this.stateFromLS();
+
+                if (useKeys)
+                    fromLS = objExtract(fromLS, useKeys);
+                else if (ignoreKeys)
+                    ignoreKeys.forEach((key) => delete fromLS[key]);
+
+                if (equal(this.state, { ...this.state, ...fromLS })) return;
+
+                this.setState(fromLS);
+            });
+        } else {
+            state = initialState;
+        }
+
+        this.state = state;
+        this.setState(state);
+    }
+
+    getState = () => this.state;
+
+    setState = async (updateState: Partial<State>) => {
+        // Do this, otherwise you are mutating the value.
+        // (Would make bugs in this case)
+        this.state = { ...this.state, ...updateState };
+
+        this.stateWasUpdated = true;
+        await this.stateChanged();
+        return this.getState();
+    }
+
+    action = <A extends Act = Act>(action: A | A['type']) => {
+        if (isType(action, 'string')) action = { type: action } as A;
+        const state = this.getState();
+
+        for (const k in this.actionSubDict)
+            this.actionSubDict[k]?.(action, state);
+
+        return action;
+    }
+
+    // -- State Set Throttler -- //
+    /**
+     * Aggregates state updates by this method over the course of
+     * `msCycle` time and sets the state only once per `msCycle` time.
+     *
+     * Different `msCycle` timings run on separate loops, therefore can
+     * run multiple `msCycle` at the same time.
+     *
+     * To keep state consistent and to prevent bugs, any key run-ins set
+     * in previous `msCycle`(s) will be overwritten by latest
+     * `throttledSetState()` call.
+     *
+     * Will wait the full designated time in `msCycle` on first run.
+     */
+    throttledSetState = async (
+        msCycle: number,
+        updateState: Partial<State>
+    ) => {
+        if (!this.throttledState[msCycle])
+            this.throttledState[msCycle] = {};
+
+        const tsKeys = objKeys(this.throttledState);
+        for (const k in updateState) {
+            this.throttledState[msCycle][k] = updateState[k];
+
+            tsKeys.forEach((tsKey) => // To keep state consistent
+                this.throttledState[tsKey]![k] = updateState[k]);
+        }
+
+        this.throttledStateSetter(msCycle);
+    }
+
+    private throttledStateSetter = async (msCycle: number) => {
+        if (this.throttlersRunning[msCycle]) return;
+        this.throttlersRunning[msCycle] = true;
+
+        await wait(msCycle);
+        while (this.throttledState[msCycle]) {
+            this.setState(this.throttledState[msCycle]);
+            delete this.throttledState[msCycle];
+            await wait(msCycle);
+        }
+
+        this.throttlersRunning[msCycle] = false;
+    }
+    // -- State Set Throttler -- //
+
+    /**
+     * Will execute the given function on state change. Subscribe to
+     * specific key(s) changes in state by setting keys to the desired
+     * key(s) to sub to. Set `keys: true` to sub to all state changes.
+     */
+    stateSub = <K extends Key = Key>(
+        keys: true | K[] | K,
+        fct: stateSubFct<State>,
+        fireOnInitSub = false
+    ) => {
+        if (isType(keys, 'array') && keys.length === 1)
+            keys = keys[0]!;
+
+        let f = fct;
+
+        if (isType(keys, 'string')) f = (s, prev) => {
+            if (this.keysChanged[keys as K]) return fct(s, prev);
+        }
+
+        else if (isType(keys, 'array')) f = (s, prev) => {
+            for (const k of keys as K[])
+                if (this.keysChanged[k]) return fct(s, prev);
+        }
+
+        if (fireOnInitSub)
+            wait(0).then(() => fct(this.state, this.prevState));
+
+        const id = Math.random();
+        this.stateSubDict[id] = f as any;
+        return { unsubscribe: () => delete this.stateSubDict[id] };
+    }
+
+    /** set `true` if to subscribe to all actions */
+    actionSub = <
+        T extends Act['type'] = Act['type'],
+        A extends Extract<Act, { type: T }> = Extract<Act, { type: T }>
+    >(
+        actions: true | T | T[],
+        fct: actSubFct<A, State>
+    ) => {
+        if (isType(actions, 'array') && actions.length === 1)
+            actions = actions[0]!;
+
+        let f = fct;
+
+        if (isType(actions, 'string')) f = (a, s) => {
+            if (a.type === actions) return fct(a, s);
+        }
+
+        else if (isType(actions, 'array')) f = (a, s) => {
+            for (const act of actions as T['type'][])
+                if (a.type === act) return fct(a, s);
+        }
+
+        const id = Math.random();
+        this.actionSubDict[id] = f as any;
+        return { unsubscribe: () => delete this.actionSubDict[id] };
+    }
+
+    /**
+     * Allows you to toggle any key with a boolean value true/false.
+     */
+    toggle = (key: KeysOfValueType<State, boolean>) =>
+        this.setState({ [key]: (!this.getState()[key]) } as any);
+
+    /**
+     * Erases local storage managed by this instance of StateManager,
+     * & removes all properties/methods on the object. (This way any
+     * attempts of accessing the object should return an error);
+     *
+     * (For debugging purposes):
+     * Object will have this appearance afterwards:
+     * ```js
+     * { type: 'StateManager', destroyed: true }
+     * ```
+     */
+    destroy = () => {
+        if (this.useLS)
+            localStorage.removeItem(this.useLS.id);
+
+        objKeys(this).forEach(k => delete this[k]);
+        (this as any).type = 'StateManager';
+        (this as any).destroyed = true;
+    }
+
+    cloneKey =
+        <K extends Key>(key: K): State[K] => clone(this.state[key]);
+
+    private stateChanged = async () => {
+        // Ensures to run only after all sync code updates the state.
+        await wait(0);
+        if (!this.stateWasUpdated) return false;
+
+        let stateDidNotChange = true;
+
+        objKeys(this.state).forEach((k) => {
+            const em = this.emittedState || {} as Partial<State>;
+
+            if (// only check equality if not already changed.
+                !this.keysChanged[k as Key] && equal(this.state[k], em[k])
+            ) return;
+
+            stateDidNotChange = false;
+            this.keysChanged[k as Key] = true;
+        });
+
+        if (stateDidNotChange)
+            return this.stateWasUpdated = false;
+
+        this.updateLocalStorage();
+
+        // these 3 need to be set before iterating over subs
+        // else prevState wont be accurately emitted
+        this.prevState = this.emittedState;
+        this.emittedState = this.state;
+        this.state = { ...this.state }; // use obj spread (or get bugs)!
+
+        for (const k in this.stateSubDict)
+            this.stateSubDict[k]?.(this.state, this.prevState as State);
+
+        this.keysChanged = {};
+        this.stateWasUpdated = false;
+        return true;
+    }
+
+    private stateFromLS = () => {
+        if (!this.useLS) return;
+
+        const { id } = this.useLS;
+        const strState = localStorage.getItem(id);
+        if (!strState) return {};
+
+        return JSON.parse(strState);
+    }
+
+    private updateLocalStorage = () => {
+        if (!this.useLS) return;
+
+        const { id, ignoreKeys, useKeys } = this.useLS;
+
+        let state = { ...this.state };
+
+        if (ignoreKeys)
+            ignoreKeys.forEach((key) => delete state[key]);
+        else if (useKeys)
+            state = objExtract(state, useKeys);
+
+        localStorage.setItem(id, JSON.stringify(state));
+    }
+}

package/src/time.ts

@@ -1,6 +1,14 @@
 import { Temporal } from '@js-temporal/polyfill';
 import { AnyDate, isType, MsTime, num, str, TimeArr, TimeObj } from '.';
 
+/** A promise that waits `ms` amount of milliseconds to execute */
+export const wait = (ms: number): Promise<void> =>
+    new Promise((res) => setTimeout(() => res(), ms));
+
+/** Resolves after a given msEpoch passes. `msEpoch - Date.now()` */
+export const waitUntil = (msEpoch: number): Promise<void> =>
+    new Promise(res => setTimeout(res, msEpoch - Date.now()))
+
 export const msTime: MsTime = {
     s: 1000,
     m: 60000,
@@ -9,8 +17,6 @@ export const msTime: MsTime = {
     w: 604800000,
 }
 
-export const weekTuple = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const;
-
 /**
  * Converts Date to time of day.
  * Good for use in logging.
@@ -56,6 +62,7 @@ export const time = {
         min: (n: num) => Date.now() + n * msTime.m,
     },
 
+    /** Convert ms into: */
     msTo: {
         /** fnc(n)  -> from ms to num of seconds */
         sec: (ms: num) => ms / msTime.s,
@@ -97,13 +104,17 @@ export const humanizedTime = (date: AnyDate) => {
     }
 }
 
-// Intl.supportedValuesOf('timeZone');
 /** A Date substitute, to make working with time easier and more versatile */
 export function getTime(
-    t: TimeArr | num | str,
+    t?: Temporal.ZonedDateTime | TimeArr | num | str | 'now',
+    /** For a list of available timeZone values run:
+     * `Intl.supportedValuesOf('timeZone');` */
     timeZone?: str
 ) {
-    timeZone = timeZone || Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (t === undefined || t === 'now') t = Date.now();
+    if (!timeZone) timeZone = t instanceof Temporal.ZonedDateTime ?
+        t.timeZoneId : Intl.DateTimeFormat().resolvedOptions().timeZone;
+
     let zonedTemporal: Temporal.ZonedDateTime;
     let date: Date;
     let isoStr: str;
@@ -114,6 +125,8 @@ export function getTime(
         zonedTemporal = Temporal.ZonedDateTime.from(isoStr + `[${timeZone}]`);
     } else if (isType(t, 'string')) {
         zonedTemporal = Temporal.ZonedDateTime.from(t + `[${timeZone}]`)
+    } else if (t instanceof Temporal.ZonedDateTime) {
+        zonedTemporal = t.withTimeZone(timeZone)
     } else {
         zonedTemporal = Temporal.ZonedDateTime.from({
             year: t[0],
@@ -134,10 +147,39 @@ export function getTime(
         date,
         tzOffsetMin: zonedTemporal.offsetNanoseconds / 60_000_000_000,
         localISO: zonedTemporal.toJSON(),
-        timeObj: timeObj(zonedTemporal),
+        obj: timeObj(zonedTemporal),
         isoStr: isoStr! || date.toISOString(),
         timeZone: timeZone,
         epochMs: zonedTemporal.epochMilliseconds,
+        startOf: {
+            day: () => getTime(zonedTemporal.startOfDay(), timeZone),
+
+            month: () => {
+                const zT = zonedTemporal;
+                return getTime([zT.year, zT.month, 1, 0, 0, 0, 0], timeZone)
+            },
+
+            year: () => {
+                const zT = zonedTemporal;
+                return getTime([zT.year, 1, 1, 0, 0, 0, 0], timeZone)
+            }
+        },
+        endOf: {
+            day: () => {
+                const zT = zonedTemporal;
+                return getTime([zT.year, zT.month, zT.day, 23, 59, 59, 999], timeZone)
+            },
+
+            month: () => {
+                const zT = zonedTemporal;
+                return getTime([zT.year, zT.month, zT.daysInMonth, 23, 59, 59, 999], timeZone)
+            },
+
+            year: () => {
+                const zT = zonedTemporal;
+                return getTime([zT.year, 12, 31, 23, 59, 59, 999], timeZone)
+            }
+        }
     }
 }
 
@@ -149,7 +191,7 @@ export const timeObj = (dt: Date | Temporal.ZonedDateTime): TimeObj => dt instan
     min: dt.getMinutes(),
     sec: dt.getSeconds(),
     ms: dt.getMilliseconds(),
-    wDay: weekTuple[dt.getDay()]!
+    wDay: (['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const)[dt.getDay()]!
 }) : ({
     y: dt.year,
     m: dt.month,
@@ -158,7 +200,7 @@ export const timeObj = (dt: Date | Temporal.ZonedDateTime): TimeObj => dt instan
     min: dt.minute,
     sec: dt.second,
     ms: dt.millisecond,
-    wDay: weekTuple[dt.dayOfWeek - 1]!
+    wDay: (['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] as const)[dt.dayOfWeek - 1]!
 });
 
 export function parseDate(d: AnyDate) {