@cleanweb/react 1.0.5 → 1.0.7

package/build/base/merged-state.d.ts

@@ -0,0 +1,15 @@
+declare class MergedState<TState extends object> {
+    static useRefresh<TState extends object>(this: MergedState<TState>): void;
+    reservedKeys: string[];
+    valueKeys: string[];
+    private _initialValues_;
+    private _values_;
+    private setState;
+    private _setters_;
+    get put(): { [Key in keyof TState]: (value: TState[Key]) => void; };
+    get initialState(): TState;
+    constructor(initialState: TState);
+    putMany: (newValues: Partial<TState>) => void;
+}
+export declare const useMergedState: <TState extends object>(initialState: TState) => MergedState<TState> & TState;
+export {};

package/build/base/merged-state.js

@@ -0,0 +1,76 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMergedState = void 0;
+var react_1 = require("react");
+var MergedState = /** @class */ (function () {
+    function MergedState(initialState) {
+        var _this = this;
+        this._initialValues_ = {};
+        this._values_ = {};
+        this._setters_ = {};
+        this.putMany = function (newValues) {
+            _this.setState(__assign(__assign({}, _this._values_), newValues));
+        };
+        this.reservedKeys = Object.keys(this);
+        this.valueKeys = [];
+        this._initialValues_ = __assign({}, initialState);
+        this._values_ = __assign({}, initialState);
+        Object.keys(initialState).forEach(function (key) {
+            if (_this.reservedKeys.includes(key)) {
+                throw new Error("The name \"".concat(key, "\" is reserved by CleanState and cannot be used to index state variables. Please use a different key."));
+            }
+            _this.valueKeys.push(key);
+            _this._setters_[key] = function (value) {
+                var _a;
+                // this._values_[key] = value;
+                _this.setState(__assign(__assign({}, _this._values_), (_a = {}, _a[key] = value, _a)));
+            };
+            var self = _this;
+            Object.defineProperty(_this, key, {
+                get: function () {
+                    return self._values_[key];
+                },
+                set: function (value) {
+                    self._setters_[key](value);
+                },
+                enumerable: true,
+            });
+        });
+    }
+    MergedState.useRefresh = function () {
+        var _a;
+        _a = (0, react_1.useState)(this.initialState), this._values_ = _a[0], this.setState = _a[1];
+    };
+    Object.defineProperty(MergedState.prototype, "put", {
+        get: function () {
+            return __assign({}, this._setters_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(MergedState.prototype, "initialState", {
+        get: function () {
+            return __assign({}, this._initialValues_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return MergedState;
+}());
+var useMergedState = function (initialState) {
+    var cleanState = (0, react_1.useMemo)(function () { return new MergedState(initialState); }, []);
+    MergedState.useRefresh.call(cleanState);
+    return cleanState;
+};
+exports.useMergedState = useMergedState;

package/build/base/methods.d.ts

@@ -1,6 +1,6 @@
-import type { CleanState } from './state';
+import type { TCleanState } from './state';
 export declare class ComponentMethods<TState extends object, TProps extends object> {
-    state: CleanState<TState>;
+    state: TCleanState<TState>;
     props: TProps;
 }
 type ComponentMethodsConstructor = typeof ComponentMethods<any, any>;

package/build/base/state.d.ts

@@ -1,22 +1,20 @@
-type TUseStateArray<TState extends object> = [
-    val: TState[keyof TState],
-    setter: (val: TState[keyof TState]) => void
-];
-type TUseStateResponses<TState extends object> = {
-    [Key in keyof TState]: TUseStateArray<TState>;
-};
-declare class _CleanState_<TState extends object> {
+declare class CleanStateBase<TState extends object> {
+    reservedKeys: string[];
+    valueKeys: string[];
     private _values_;
+    private _initialValues_;
     private _setters_;
-    put: { [Key in keyof TState]: (value: TState[Key]) => void; };
-    constructor(stateAndSetters: TUseStateResponses<TState>);
+    constructor(initialState: TState);
+    static update: <TState_1 extends object>(this: CleanStateBase<TState_1>) => void;
+    get put(): { [Key in keyof TState]: (value: TState[Key]) => void; };
+    get initialState(): TState;
     putMany: (newValues: Partial<TState>) => void;
 }
-type TCleanStateInstance<TState extends object> = TState & _CleanState_<TState>;
-declare const _CleanState: new <TState extends object>(...args: ConstructorParameters<typeof _CleanState_>) => TCleanStateInstance<TState>;
-export type CleanState<TState extends object> = InstanceType<typeof _CleanState<TState>>;
+type TCleanStateInstance<TState extends object> = TState & CleanStateBase<TState>;
+export type TCleanState<TState extends object> = TCleanStateInstance<TState>;
 type Func = (...params: any[]) => any;
-type UseCleanState = <TStateObjOrFactory extends ((props?: TProps) => object) | object, TProps extends object = object>(_initialState: TStateObjOrFactory, props?: TStateObjOrFactory extends Func ? TProps : undefined) => CleanState<TStateObjOrFactory extends Func ? ReturnType<TStateObjOrFactory> : TStateObjOrFactory>;
+type UseCleanState = <TState extends object, TProps extends object = object>(_initialState: ((props?: TProps) => TState) | TState, // TStateObjOrFactory,
+props?: typeof _initialState extends Func ? TProps : undefined) => TCleanState<TState>;
 export declare const useCleanState: UseCleanState;
 /**
  * Returns a value that is false before the component has been mounted,

package/build/base/state.js

@@ -1,27 +1,44 @@
 "use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useMountState = exports.useCleanState = void 0;
 var react_1 = require("react");
-var _CleanState_ = /** @class */ (function () {
-    function _CleanState_(stateAndSetters) {
+var CleanStateBase = /** @class */ (function () {
+    function CleanStateBase(initialState) {
         var _this = this;
         this._values_ = {};
         this._setters_ = {};
-        this.put = this._setters_;
         this.putMany = function (newValues) {
             Object.entries(newValues).forEach(function (_a) {
                 var key = _a[0], value = _a[1];
                 _this.put[key](value);
             });
         };
-        /** Must be extracted before the loop begins to avoid including keys from the consumers state object. */
-        var reservedKeys = Object.keys(this);
-        Object.entries(stateAndSetters).forEach(function (_a) {
-            var key = _a[0], responseFromUseState = _a[1];
-            if (reservedKeys.includes(key))
+        this.reservedKeys = Object.keys(this);
+        /**
+         * The keys from the initial state object.
+         * By capturing and storing the value once, we ensure that any potential changes to the object,
+         * or irregularities in the order of keys returned by Object.keys,
+         * will not affect the order of subsequent useState calls.
+         * Only keys provided on the initial call will be recognized,
+         * since CleanState is instantiated only once with useMemo,
+         * and they will always be processed in a consistent order during rerenders.
+         */
+        this.valueKeys = Object.keys(initialState);
+        this._initialValues_ = __assign({}, initialState);
+        this.valueKeys.forEach(function (key) {
+            if (_this.reservedKeys.includes(key))
                 throw new Error("The name \"".concat(key, "\" is reserved by CleanState and cannot be used to index state variables. Please use a different key."));
-            _this._values_[key] = responseFromUseState[0], _this._setters_[key] = responseFromUseState[1];
-            // this.put[key] = this._setters_[key];
             var self = _this;
             Object.defineProperty(_this, key, {
                 get: function () {
@@ -34,36 +51,52 @@ var _CleanState_ = /** @class */ (function () {
             });
         });
     }
-    return _CleanState_;
+    Object.defineProperty(CleanStateBase.prototype, "put", {
+        get: function () {
+            return __assign({}, this._setters_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(CleanStateBase.prototype, "initialState", {
+        get: function () {
+            return __assign({}, this._initialValues_);
+        },
+        enumerable: false,
+        configurable: true
+    });
+    CleanStateBase.update = function update() {
+        var _this = this;
+        if (!(this instanceof CleanState))
+            throw new Error('CleanState.update must be called with `this` value set to a CleanState instance. Did you forget to use `.call` or `.apply`? Example: CleanState.update.call(cleanState);');
+        /**
+         * Linters complain about the use of a React hook within a loop because:
+         * > By following this rule, you ensure that Hooks are called in the same order each time a component renders.
+         * > That’s what allows React to correctly preserve the state of Hooks between multiple useState and useEffect calls.
+         * To resolve this, we're calling `useState` via an alias `retrieveState`.
+         * Bypassing this rule is safe here because `useCleanState` is a special case,
+         * and it guarantees that the same useState calls will be made on every render in the exact same order.
+         * Therefore, it is safe to silence the linters, and required for this implementation to work smoothly.
+         */
+        var retrieveState = react_1.useState;
+        this.valueKeys.forEach(function (key) {
+            var _a;
+            _a = retrieveState(_this.initialState[key]), _this._values_[key] = _a[0], _this._setters_[key] = _a[1];
+        });
+        /* Object.entries<TUseStateArray<TState>>(stateAndSetters).forEach(([key, responseFromUseState]) => {
+            [this._values_[key], this._setters_[key]] = responseFromUseState;
+        }); */
+        // return this;
+    };
+    return CleanStateBase;
 }());
 ;
-var _CleanState = _CleanState_;
-/**
- * Linters complain about the use of a React hook within a loop because:
- * > By following this rule, you ensure that Hooks are called in the same order each time a component renders.
- * > That’s what allows React to correctly preserve the state of Hooks between multiple useState and useEffect calls.
- * To resolve this, we're calling `useState` via an alias `retrieveState`.
- * Bypassing this rule is safe here because `useCleanState` is a special case,
- * and it guarantees that the same useState calls will be made on every render in the exact same order.
- * Therefore, it is safe to silence the linters, and required for this implementation to work smoothly.
- */
-var retrieveState = react_1.useState;
+var CleanState = CleanStateBase;
 var useCleanState = function (_initialState, props) {
-    var initialState = typeof _initialState === 'function' ? _initialState(props) : _initialState;
-    var stateKeys = Object.keys(initialState);
-    var initialCount = (0, react_1.useState)(stateKeys.length)[0];
-    if (stateKeys.length !== initialCount) {
-        throw new Error('The keys in your state object must be consistent throughout your components lifetime. Look up "rules of hooks" for more context.');
-    }
-    var stateAndSetters = {};
-    for (var _i = 0, stateKeys_1 = stateKeys; _i < stateKeys_1.length; _i++) {
-        var key = stateKeys_1[_i];
-        stateAndSetters[key] = retrieveState(initialState[key]);
-    }
-    // @todo Refactor to return consistent state instance each render.
-    // Though useState gives us persistent references for values and setters,
-    // so keeping the CleanState wrapper persistent may be unnecessary.
-    return new _CleanState(stateAndSetters);
+    var initialState = typeof _initialState === 'function' ? (0, react_1.useMemo)(function () { return _initialState(props); }, []) : _initialState;
+    var cleanState = (0, react_1.useMemo)(function () { return new CleanState(initialState); }, []);
+    CleanState.update.call(cleanState);
+    return cleanState;
 };
 exports.useCleanState = useCleanState;
 /**

package/build/classy/class.d.ts

@@ -5,6 +5,12 @@ type Obj = Record<string, any>;
 type IComponentConstructor = ComponentInstanceConstructor<any, any, any> & typeof ClassComponent<any, any, any>;
 export declare class ClassComponent<TState extends Obj, TProps extends Obj, THooks extends Obj> extends ComponentInstance<TState, TProps, THooks> {
     Render: FunctionComponent<TProps>;
+    /**
+     * Use this to let React know whenever you would like all of your instance's state to be reset.
+     * When the value is changed, React will reset all state variables to their initial value the next time your component re-renders.
+     * @see https://react.dev/learn/you-might-not-need-an-effect#resetting-all-state-when-a-prop-changes
+     */
+    instanceId?: string;
     static FC: <IComponentType extends IComponentConstructor>(this: IComponentType, _Component?: IComponentType) => (props: InstanceType<IComponentType>["props"]) => JSX.Element;
 }
 export {};

package/build/classy/class.js

@@ -43,10 +43,10 @@ var ClassComponent = /** @class */ (function (_super) {
         if (!Component.getInitialState || !isClassComponentType)
             throw new Error('Attempted to initialize ClassComponent with invalid Class type. Either pass a class that extends ClassComponent to FC (e.g `export FC(MyComponent);`), or ensure it is called as a method on a ClassComponent constructor type (e.g `export MyComponent.FC()`).');
         var Wrapper = function (props) {
-            var Render = (0, instance_1.useInstance)(Component, props).Render;
+            var _a = (0, instance_1.useInstance)(Component, props), Render = _a.Render, instanceId = _a.instanceId;
             // Add calling component name to Render function name in stack traces.
             (0, react_1.useMemo)(function () { return setFunctionName(Render, "".concat(Component.name, ".Render")); }, []);
-            return (0, jsx_runtime_1.jsx)(Render, {});
+            return (0, jsx_runtime_1.jsx)(Render, {}, instanceId);
         };
         // Include calling component name in wrapper function name on stack traces.
         var wrapperName = "ClassComponent".concat(Wrapper.name, " > ").concat(Component.name);

package/build/classy/instance.d.ts

@@ -1,13 +1,51 @@
 import type { ComponentLogicConstructor } from './logic';
 import { ComponentLogic } from './logic';
 type Obj = Record<string, any>;
-type AsyncAllowedEffectCallback = () => IVoidFunction | Promise<IVoidFunction>;
+type AsyncAllowedEffectCallback = () => Awaitable<IVoidFunction>;
 export declare const noOp: () => void;
 export declare class ComponentInstance<TState extends Obj = {}, TProps extends Obj = {}, THooks extends Obj = {}> extends ComponentLogic<TState, TProps, THooks> {
+    /**
+     * Runs only _before_ first render, i.e before the component instance is mounted.
+     * Useful for logic that is involved in determining what to render.
+     *
+     * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+     * and prompt React to immediately rerender the component with the updated state value(s).
+     *
+     * Ignored on subsequent rerenders.
+     */
     beforeMount: IVoidFunction;
+    /**
+     * Runs only **_after_** first render, i.e after the component instance is mounted.
+     *
+     * Should usually only be used for logic that does not directly take part in determining what to render, like
+     * synchronize your component with some external system.
+     *
+     * Ignored on subsequent rerenders.
+     *
+     * Returns a cleanup function.
+     */
     onMount: AsyncAllowedEffectCallback;
+    /**
+     * Runs _before_ every render cycle, including the first.
+     * Useful for logic that is involved in determining what to render.
+     *
+     * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+     * and prompt React to immediately rerender the component with the updated state value(s).
+     */
     beforeRender: IVoidFunction;
+    /**
+     * Runs **_after_** every render cycle, including the first.
+     *
+     * Should usually only be used for logic that does not directly take part in determining what to render, like
+     * synchronize your component with some external system.
+     *
+     * Returns a cleanup function.
+     */
     onRender: AsyncAllowedEffectCallback;
+    /**
+     * Runs when the component is unmounted.
+     * It is called _after_ the cleanup function returned by onMount.
+     */
     cleanUp: IVoidFunction;
 }
 type ComponentClassBaseType<TState extends Obj = {}, TProps extends Obj = {}, THooks extends Obj = {}> = ComponentLogicConstructor<TState, TProps, THooks> & Constructor<ComponentInstance<TState, TProps, THooks>>;

package/build/classy/instance.js

@@ -25,10 +25,48 @@ var ComponentInstance = /** @class */ (function (_super) {
     __extends(ComponentInstance, _super);
     function ComponentInstance() {
         var _this = _super !== null && _super.apply(this, arguments) || this;
+        /**
+         * Runs only _before_ first render, i.e before the component instance is mounted.
+         * Useful for logic that is involved in determining what to render.
+         *
+         * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+         * and prompt React to immediately rerender the component with the updated state value(s).
+         *
+         * Ignored on subsequent rerenders.
+         */
         _this.beforeMount = function () { };
+        /**
+         * Runs only **_after_** first render, i.e after the component instance is mounted.
+         *
+         * Should usually only be used for logic that does not directly take part in determining what to render, like
+         * synchronize your component with some external system.
+         *
+         * Ignored on subsequent rerenders.
+         *
+         * Returns a cleanup function.
+         */
         _this.onMount = function () { return exports.noOp; };
+        /**
+         * Runs _before_ every render cycle, including the first.
+         * Useful for logic that is involved in determining what to render.
+         *
+         * Updating local state from in here will abort the render cycle early, before changes are committed to the DOM,
+         * and prompt React to immediately rerender the component with the updated state value(s).
+         */
         _this.beforeRender = function () { };
+        /**
+         * Runs **_after_** every render cycle, including the first.
+         *
+         * Should usually only be used for logic that does not directly take part in determining what to render, like
+         * synchronize your component with some external system.
+         *
+         * Returns a cleanup function.
+         */
         _this.onRender = function () { return exports.noOp; };
+        /**
+         * Runs when the component is unmounted.
+         * It is called _after_ the cleanup function returned by onMount.
+         */
         _this.cleanUp = function () { };
         return _this;
     }
@@ -48,6 +86,7 @@ var useMountCallbacks = function (instance) {
             var doCleanUp = function (runMountCleaners) {
                 var _a;
                 runMountCleaners === null || runMountCleaners === void 0 ? void 0 : runMountCleaners();
+                // onDismount? willUnmount?
                 (_a = instance.cleanUp) === null || _a === void 0 ? void 0 : _a.call(instance);
             };
             if (typeof mountHandlerCleanUp === 'function') {
@@ -62,7 +101,7 @@ var useMountCallbacks = function (instance) {
 exports.useMountCallbacks = useMountCallbacks;
 var useInstance = function (Component, props) {
     var _a;
-    // useCustomHooks.
+    // useHooks.
     var instance = (0, logic_1.useLogic)(Component, props);
     // beforeMount, onMount, cleanUp.
     (0, exports.useMountCallbacks)(instance);

package/build/classy/logic.d.ts

@@ -1,9 +1,9 @@
-import type { CleanState } from '../base/state';
+import type { TCleanState } from '../base/state';
 export declare class ComponentLogic<TState extends object, TProps extends object, THooks extends object> {
-    state: CleanState<TState>;
+    state: TCleanState<TState>;
     props: TProps;
     hooks: THooks;
-    useCustomHooks?: () => THooks;
+    useHooks?: () => THooks;
 }
 export interface ComponentLogicConstructor<TState extends object, TProps extends object, THooks extends object> extends Constructor<ComponentLogic<TState, TProps, THooks>> {
     getInitialState: (props?: TProps) => TState;

package/build/classy/logic.js

@@ -24,7 +24,7 @@ var useLogic = function (Methods, props) {
     }, []);
     methods.state = state;
     methods.props = props;
-    methods.hooks = ((_a = methods.useCustomHooks) === null || _a === void 0 ? void 0 : _a.call(methods)) || {};
+    methods.hooks = ((_a = methods.useHooks) === null || _a === void 0 ? void 0 : _a.call(methods)) || {};
     return methods;
 };
 exports.useLogic = useLogic;

package/build/globals.d.ts

@@ -8,6 +8,8 @@ type Optional<
 		: BaseType | undefined
 )
 
+type Awaitable<Type> = Type | Promise<Type>;
+
 type Constructor<
 	TInstance extends any = any,
 	TParams extends any[] = never[]

package/build/index.js

@@ -15,3 +15,25 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./classy"), exports);
+// PS: Document component inheritance pattern with lifecycle callback arrays and namespaces.
+// Due to react's remounting behaviour, components must externally track when some logic has run, if it really really must only ever run once per mounted instance. Tricky to get right for components that may have multiple instance rendered simultaneously at different parts of a page.
+// useCleanState => useState, separate call for each key
+// useMergedState => useState, same call for all keys
+// useMethods => useCallback
+// useLogic => useCallback + all other hook calls.
+// useInstance => useLogic + lifecycle methods.
+/*
+- Write usage doc
+- Push to git and publish to site
+    - Follow-up personal post on class component inheritance can be published on GH Pages from profile repo.
+- Publish to NPM
+- Finalize package and repo names, then post to Twitter.
+*/
+/*
+withFetchApi(baseUrl); To mimic axios.get and axios.post type calls.
+@cleanweb/mem-store - Release global-store package here.
+Use mem-store to cache requests in createApi(); Use md5 hashed url as key.
+@todo Add simple persistence layer with indexed db.
+@cleanweb/subscribable - To publish changes in the data to subscribers.
+@cleanweb/reactive-data - To combine all 4.
+*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleanweb/react",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "A suite of helpers for writing cleaner React function components.",
   "engines": {
     "node": ">=18"
@@ -20,6 +20,7 @@
     "./base": "./build/base/index.js",
     "./classy": "./build/classy/index.js",
     "./state": "./build/base/state.js",
+    "./state/merged": "./build/base/merged-state.js",
     "./methods": "./build/base/methods.js",
     "./logic": "./build/classy/logic.js",
     "./instance": "./build/classy/instance.js",