react-state-monad 0.0.1

package/README.md

@@ -0,0 +1,248 @@
+# React State Monad
+
+A set of hooks to manage/transform/filter states with monads in React.
+
+## Description
+
+`react-state-monad` provides a set of monadic state management utilities, specifically designed to work seamlessly with
+React's state hooks. It allows you to manage, transform, and filter states in a functional and declarative way using
+monads like `Maybe` and `Option`.
+
+This library leverages the power of monads to encapsulate state changes, enabling a cleaner, more predictable way to
+handle various state conditions in React.
+
+## Features
+
+- Manage state using monads like `Maybe` and `Option`.
+- Simplify handling of undefined or null values in state.
+- Leverage functional programming patterns in React state management.
+- Support for TypeScript with full type definitions.
+
+## Installation
+
+You can install `react-state-monad` using npm or yarn:
+
+```bash
+npm install react-state-monad
+```
+
+or
+
+```bash
+yarn add react-state-monad
+```
+
+## Usage
+
+Here's an example of how you can use the hooks in your React components:
+
+### `useStateObject<T>`
+
+This hook initializes a StateObject with the provided initial value. It uses React's useState hook to manage the
+internal state and returns a StateObject that represents the current state.
+
+Parameters: `initialState`: The initial value of the state. This value can be of any type, determined by the generic
+type `T`.
+
+Returns a `StateObject` of type `T` representing the initialized state. This `StateObject` is an instance
+of `ValidState`, which
+encapsulates the state value and provides a `setValue` function to update it.
+
+### `useEmptyState<T>`
+
+This hook initializes a `StateObject` with an empty state. It is useful as a fallback when no valid state is available.
+
+Parameters: None.
+
+Returns a `StateObject` of type `T` representing an empty state. This `StateObject` is an instance of `EmptyState`,
+which encapsulates the absence of a state value.
+
+### `useElementState<T>`
+
+This hook allows you to derive and update a specific element in an array within a `StateObject`. It is useful for
+managing state at a granular level within an array.
+
+Parameters:
+
+- `state`: The `StateObject` containing an array.
+- `index`: The index of the element to be derived.
+
+Returns a `StateObject` of type `T` representing the element at the given index. If the index is out of bounds or the
+state is empty, it returns an instance of `EmptyState`. Otherwise, it returns an instance of `ValidState`, which
+encapsulates the element value and provides a `setValue` function to update it.
+
+### `useFieldState<TOriginal, TField>`
+
+This hook derives a field from the state object and creates a new `StateObject` for the field's value. It is useful for
+managing state at a granular level within an object.
+
+Parameters:
+
+- `state`: The `StateObject` containing the original state.
+- `field`: The field name to be derived from the state.
+
+Returns a `StateObject` of type `TField` representing the derived field. This `StateObject` is an instance
+of `ValidState`, which encapsulates the field value and provides a `setValue` function to update it.
+
+For example:
+
+```jsx
+import React from 'react';
+import {useStateObject, useFieldState} from 'react-state-monad';
+
+const MyComponent = () => {
+    const userState = useStateObject({
+        name: 'John Doe',
+        age: 30,
+    });
+
+    const nameState = useFieldState(userState, 'name');
+    const ageState = useFieldState(userState, 'age');
+
+    return (
+        <div>
+            <input
+                type="text"
+                value={nameState.value}
+                onChange={(e) => nameState.value = e.target.value}
+            />
+            <input
+                type="number"
+                value={ageState.value}
+                onChange={(e) => ageState.value = parseInt(e.target.value, 10)}
+            />
+        </div>
+    );
+};
+
+export default MyComponent;
+```
+
+### `useRemapArray<T>`
+
+This hook maps each element in an array within a `StateObject` to a new `StateObject`, allowing for independent updates
+of each element while keeping the overall array state synchronized.
+
+Parameters:
+
+- `state`: The `StateObject` containing an array.
+
+Returns an array of new `StateObject`s, each representing an element in the original array. This allows individual
+updates while keeping the array state synchronized. If the state has no value, it returns an empty array.
+
+### Complete Example
+
+Here's a more complete example demonstrating the usage of `useStateObject`, `useFieldState`, `useElementState`,
+and `useRemapArray` hooks in a React component:
+
+```tsx
+
+const AgeField = (props: { ageState: StateObject<number> }) => <div>
+    <label>Age:</label>
+    <input
+        type="number"
+        value={props.ageState.value}
+        onChange={x => props.ageState.value = parseInt(x.target.value, 10)}
+    />
+</div>;
+
+
+const NameField = (props: { nameState: StateObject<string> }) => {
+    return <div>
+        <label>Name:</label>
+        <input
+            type="text"
+            value={props.nameState.value}
+            onChange={x => props.nameState.value = x.target.value}
+        />
+    </div>;
+}
+
+const HobbyField = (props: { hobbyState: StateObject<string> }) => {
+    return <div>
+        <input
+            type="text"
+            value={props.hobbyState.value}
+            onChange={x => props.hobbyState.value = x.target.value}
+        />
+    </div>;
+}
+
+const HobbiesField = (props: { hobbiesState: StateObject<string[]> }) => {
+
+    const hobbyStates: StateObject<string>[] = useRemapArray(props.hobbiesState);
+
+    const addHobby = () => {
+        // Always use the setter to update arrays, do not modify them directly to ensure React state consistency.
+        // Immutability is key 💗
+        props.hobbiesState.value = [...props.hobbiesState.value, ''];
+    }
+
+    return <div>
+        <label>Hobbies:</label>
+        {
+            hobbyStates.map((hobbyState, index) => <HobbyField key={index} hobbyState={hobbyState}/>)
+        }
+        <button onClick={addHobby}>Add Hobby</button>
+    </div>;
+
+
+};
+
+export const UserProfile = () => {
+
+    type DudeData = {
+        name: string;
+        age: number;
+        hobbies: string[];
+    }
+    // Initialize state with an object containing user details and an array of hobbies
+    const userState: StateObject<DudeData> = useStateObject({
+        name: 'John Doe',
+        age: 30,
+        hobbies: ['Reading', 'Traveling', 'Cooking'],
+    });
+
+    // Derive state for individual fields
+    const nameState: StateObject<string> = useFieldState(userState, 'name');
+    const ageState: StateObject<number> = useFieldState(userState, 'age');
+
+    // Derive state for hobbies array
+    const hobbiesState: StateObject<string[]> = useFieldState(userState, 'hobbies');
+
+
+    return (
+        <div>
+            <h1>User Profile</h1>
+            <NameField nameState={nameState}/>
+            <AgeField ageState={ageState}/>
+            <HobbiesField hobbiesState={hobbiesState}/>
+        </div>
+    );
+};
+```
+
+## Contributing
+
+Contributions are welcome! If you'd like to contribute to this library, please fork the repository and submit a pull
+request.
+
+How to Contribute
+Fork the repository.
+
+* Create a new branch for your feature `git checkout -b feature-name`
+* Commit your changes `git commit -am 'Add new feature'`
+* Push to the branch `git push origin feature-name`
+* Open a pull request. I'll be happy to review it!
+
+## License
+
+This project is licensed under the GPL-3.0 License.
+
+## Author
+
+`Marcos Alvarez`
+
+[<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="38" height="38">](https://github.com/alvmivan)
+[<img src="https://www.linkedin.com/favicon.ico" width="40" height="40">](https://www.linkedin.com/in/marcos-alvarez-40651b150/)
+[<img src="https://ssl.gstatic.com/ui/v1/icons/mail/rfr/gmail.ico" width="40" height="40">](mailto:alvmivan@gmail.com)

package/dist/index.cjs

@@ -0,0 +1,29 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.tsx
+var import_react2 = __toESM(require("react"), 1);
+
+// src/hooks/useStateObject.ts
+var import_react = require("react");

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,5 @@
+// src/index.tsx
+import React from "react";
+
+// src/hooks/useStateObject.ts
+import { useState } from "react";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "react-state-monad",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "A set of hooks to manage/transform/filter states with monads in React",
+  "keywords": [
+    "maybe",
+    "option",
+    "monad",
+    "state",
+    "monads",
+    "react",
+    "functional"
+  ],
+  "scripts": {
+    "validateTypes": "tsc --noEmit",
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "cleanBuild" : "rm -rf dist" 
+  },
+  "dependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.7",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3"
+  },
+  "author": {
+    "name": "Marcos Alvarez",
+    "email": "alvmivan@gmail.com",
+    "url": "https://github.com/alvmivan"
+  },
+  "license": "GPL-3.0",
+  "main": "dist/index.js",     
+  "module": "dist/index.mjs",    
+  "types": "dist/types/index.d.ts"  
+}

package/src/hooks/types.ts

@@ -0,0 +1,12 @@
+/**
+ * Helper type that ensures a field is a valid key of an object and that the field's type matches the expected type.
+ *
+ * @template TObject - The object type.
+ * @template TField - The expected type of the field.
+ */
+export type ValidFieldFrom<TObject, TField> = {
+    [Key in keyof TObject]: TObject[Key] extends TField ? Key : never;
+}[keyof TObject];
+
+ 
+

package/src/hooks/useElementState.ts

@@ -0,0 +1,26 @@
+import {StateObject} from "../stateObject";
+import {EmptyState} from "../implementations/emptyState";
+import {ValidState} from "../implementations/validState";
+
+/**
+ * Hook that allows you to derive and update a specific element in an array within a StateObject.
+ *
+ * @template T - The type of the array elements.
+ * @param state - The StateObject containing an array.
+ * @param index - The index of the element to be derived.
+ * @returns A new StateObject representing the element at the given index.
+ */
+export function useElementState<T>(state: StateObject<T[]>, index: number): StateObject<T> {
+    if (!state.hasValue || index < 0 || index >= state.value.length) {
+        return new EmptyState<T>();  // Returns an empty state if the index is out of bounds or state is empty.
+    }
+
+    return new ValidState<T>(
+        state.value[index],
+        (newElement) => {
+            const arrayCopy = [...state.value];
+            arrayCopy[index] = newElement;
+            state.value = arrayCopy;
+        }
+    );
+}

package/src/hooks/useEmptyState.ts

@@ -0,0 +1,13 @@
+import {StateObject} from "../stateObject";
+import {EmptyState} from "../implementations/emptyState";
+
+/**
+ * Hook that initializes a StateObject with an empty state.
+ * This is useful as a fallback when no valid state is available.
+ *
+ * @template T - The type of the value that could be held by the state.
+ * @returns A StateObject representing an empty state.
+ */
+export function useEmptyState<T>(): StateObject<T> {
+    return new EmptyState<T>();  // Returns a new EmptyState object.
+}

package/src/hooks/useFieldState.ts

@@ -0,0 +1,21 @@
+import {StateObject} from "../stateObject";
+import {ValidFieldFrom} from "./types";
+
+/**
+ * Hook that derives a field from the state object and creates a new StateObject for the field's value.
+ *
+ * @template TOriginal - The type of the original state object.
+ * @template TField - The type of the field value to be derived.
+ * @param state - The StateObject containing the original state.
+ * @param field - The field name to be derived from the state.
+ * @returns A new StateObject for the derived field.
+ */
+export function useFieldState<TOriginal, TField>(
+    state: StateObject<TOriginal>,
+    field: ValidFieldFrom<TOriginal, TField>
+): StateObject<TField> {
+    return state.map(
+        (original) => original[field] as TField,  // Extracts the field value.
+        (newField, original) => ({...original, [field]: newField} as TOriginal)  // Updates the field with the new value.
+    );
+}

package/src/hooks/useRemapArray.ts

@@ -0,0 +1,33 @@
+import {StateObject} from "../stateObject";
+import {ValidState} from "../implementations/validState";
+
+/**
+ * Hook that maps each element in an array within a StateObject to a new StateObject,
+ * allowing for independent updates of each element while keeping the overall array state synchronized.
+ *
+ * @template T - The type of the array elements.
+ * @param state - The StateObject containing an array.
+ * @returns An array of new StateObjects, each representing an element in the original array,
+ *          allowing individual updates while keeping the array state synchronized.
+ */
+export function useRemapArray<T>(state: StateObject<T[]>): StateObject<T>[] {
+    if (!state.hasValue) return []  // Returns an empty array if the state has no value.
+
+    const count = state.value.length
+    const result: StateObject<T>[] = []
+
+    for (let i = 0; i < count; i++) {
+        result.push(
+            new ValidState<T>(
+                state.value[i],  // The current value of the element at index i.
+                (newElement) => {  // Setter to update the element at index i in the array.
+                    const arrayCopy = [...state.value];  // Create a copy of the original array.
+                    arrayCopy[i] = newElement;  // Replace the element at index i with the new element.
+                    state.value = arrayCopy;  // Update the state with the new array, triggering a re-render.
+                }
+            )
+        )
+    }
+
+    return result  // Return the array of StateObjects representing each element.
+}

package/src/hooks/useStateObject.ts

@@ -0,0 +1,15 @@
+import {StateObject} from "../stateObject";
+import {useState} from "react";
+import {ValidState} from "../implementations/validState";
+
+/**
+ * Hook that initializes a StateObject with the given initial value.
+ *
+ * @template T - The type of the value to be stored in the state.
+ * @param initialState - The initial value of the state.
+ * @returns A StateObject representing the initialized state.
+ */
+export function useStateObject<T>(initialState: T): StateObject<T> {
+    const [state, setState] = useState<T>(initialState);
+    return new ValidState<T>(state, setState);  // Returns a new ValidState object with the initial state value.
+}

package/src/implementations/emptyState.ts

@@ -0,0 +1,43 @@
+import {StateObject} from "../stateObject";
+
+/**
+ * Represents a state that holds no value and is considered "empty".
+ * This is used as a fallback or default when there is no valid state.
+ * you should NEVER use this class directly, use the `StateObject` interface instead.
+ * and create instances by using the hooks
+ * @template T - The type of the value that could be held by the state.
+ */
+export class EmptyState<T> implements StateObject<T> {
+    // No value stored, returns an error when accessed.
+    get value(): T {
+        throw new Error("Not implemented");
+    }
+
+    get hasValue(): boolean {
+        return false;
+    }
+
+    orElse(orElse: T): T {
+        return orElse;  // Returns the fallback value when the state is empty.
+    }
+
+    do() {
+        // No operation for empty state.
+    }
+
+    filter(): StateObject<T> {
+        return this;  // The empty state remains unchanged when filtered.
+    }
+
+    set value(_: T) {
+        // No operation for setting a value in the empty state.
+    }
+
+    flatMap<U>(): StateObject<U> {
+        return new EmptyState<U>();  // Returns an empty state when flatMapped.
+    }
+
+    map<U>(): StateObject<U> {
+        return new EmptyState<U>();  // Returns an empty state when mapped.
+    }
+}

package/src/implementations/validState.ts

@@ -0,0 +1,60 @@
+import {EmptyState} from "./emptyState";
+import {StateObject} from "../stateObject";
+
+/**
+ * Represents a state that holds a valid value of type T.
+ * you should NEVER use this class directly, use the `StateObject` interface instead.
+ * and create instances by using the hooks
+ * @template T - The type of the value stored in the state.
+ */
+export class ValidState<T> implements StateObject<T> {
+    private readonly state: T;
+    private readonly setter: (state: T) => void;
+
+    constructor(state: T, setter: (state: T) => void) {
+        this.state = state;
+        this.setter = setter;
+    }
+
+    get value(): T {
+        return this.state;
+    }
+
+    do(action: (t: T) => void) {
+        action(this.state);  // Performs the given action on the state value.
+    }
+
+    orElse() {
+        return this.state;  // Returns the state value as it is valid.
+    }
+
+    set value(newState: T) {
+        this.setter(newState);  // Sets a new value for the state.
+    }
+
+    map<U>(
+        mappingFunction: (t: T) => U,
+        inverseMappingFunction: (u: U, t: T) => T
+    ): StateObject<U> {
+        const derivedState = mappingFunction(this.state);
+        const derivedSetter = (newState: U) => {
+            this.setter(inverseMappingFunction(newState, this.state));  // Updates the state with the inverse mapping.
+        };
+
+        return new ValidState<U>(derivedState, derivedSetter);  // Returns a new state object with the transformed value.
+    }
+
+    flatMap<U>(
+        mappingFunction: (t: T) => StateObject<U>
+    ): StateObject<U> {
+        return mappingFunction(this.state);  // Applies the mapping function and returns the result.
+    }
+
+    get hasValue(): boolean {
+        return true;
+    }
+
+    filter(predicate: (t: T) => boolean): StateObject<T> {
+        return predicate(this.state) ? (this as StateObject<T>) : new EmptyState<T>();  // Filters the state based on the predicate.
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import {StateObject} from "./stateObject";
+
+// an empty index just to make tsc happy

package/src/stateObject.ts

@@ -0,0 +1,71 @@
+/**
+ * Represents a state object that holds a value of type T, allowing various state operations.
+ * This is the main interface for managing state, with operations like `map`, `filter`, and `flatMap`.
+ * initialize with useStateObject<T>(initialState: T) hook
+ * @template T - The type of the value stored in the state object.
+ */
+export type StateObject<T> = {
+    /**
+     * The current value of the state.
+     */
+    get value(): T;
+
+    /**
+     * Returns true if the state has a valid value, false otherwise.
+     */
+    get hasValue(): boolean;
+
+    /**
+     * Performs an action on the current state value.
+     *
+     * @param action - A function that accepts the current state value and performs some operation.
+     */
+    do(action: (t: T) => void): void;
+
+    /**
+     * Sets a new value for the state.
+     *
+     * @param newState - The new state value to set.
+     */
+    set value(newState: T);
+
+    /**
+     * Transforms the current state into another state object by applying a mapping function.
+     *
+     * @template U - The type of the new state value.
+     * @param mappingFunction - A function that transforms the current state value into a new value.
+     * @param inverseMappingFunction - A function that transforms a new value back to the original state type.
+     * @returns A new StateObject with the transformed value.
+     */
+    map<U>(
+        mappingFunction: (t: T) => U,
+        inverseMappingFunction: (u: U, t: T) => T
+    ): StateObject<U>;
+
+    /**
+     * Filters the state based on a predicate, returning an empty state if the predicate is not satisfied.
+     *
+     * @param predicate - A function that tests the current state value.
+     * @returns A new StateObject with the original value or an empty state.
+     */
+    filter(predicate: (t: T) => boolean): StateObject<T>;
+
+    /**
+     * Returns the current state value if it exists; otherwise, returns the provided alternative value.
+     *
+     * @param orElse - The value to return if the state does not have a valid value.
+     * @returns The current state value or the provided fallback value.
+     */
+    orElse(orElse: T): T;
+
+    /**
+     * Transforms the current state into another state object by applying a mapping function that returns a new state.
+     *
+     * @template U - The type of the new state value.
+     * @param mappingFunction - A function that transforms the current state value into another state object.
+     * @returns A new StateObject based on the result of the mapping function.
+     */
+    flatMap<U>(
+        mappingFunction: (t: T) => StateObject<U>
+    ): StateObject<U>;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "esnext",                    // Usar un target moderno compatible
+    "module": "esnext",                    // Usar módulos ES
+    "moduleResolution": "node",            // Resolución de módulos tipo Node
+    "declaration": true,                   // Generar los archivos .d.ts
+    "declarationDir": "./dist/types",      // El directorio de las declaraciones de tipo
+    "outDir": "./dist",                    // El directorio de salida para el bundle
+    "strict": true,                        // Habilitar el modo estricto
+    "esModuleInterop": true,               // Interoperabilidad con módulos ES
+    "skipLibCheck": true,                  // Omitir la comprobación de bibliotecas
+    "forceConsistentCasingInFileNames": true // Forzar la consistencia de las mayúsculas/minúsculas en los nombres de archivo
+  },
+  "include": [
+    "src/**/*"                             // Incluir los archivos fuente de la carpeta src
+  ],
+  "exclude": [
+    "node_modules"                         // Excluir node_modules
+  ]
+}