nr-usestate: A Simple State Management Utility

This repository contains a simple state management utility implemented in JavaScript (with corresponding TypeScript definition files) that is similar to React's useState hook. It can be used for managing state in small, self-contained applications or pure JavaScript environments.

Features

• Simple State Storage: Store any JavaScript value (numbers, strings, objects, etc.).
• Value Updates: Update the state with a direct value or a function based on the previous state.
• Side Effect Management (useEffect): Run a specified function when the state changes or when useEffect is registered. Crucially, useEffect callbacks are executed immediately upon registration with the current state.
• Access Methods: Easy access to the state via the value property, toString(), and valueOf() methods.
• Lightweight and Standalone: Has no external dependencies.
• TypeScript Support: Includes a type definition file (.d.ts) for TypeScript projects.
• Flexibility: Choose between class-based or functional approaches.

Project Structure

node-usestate/
├── index.js          # Main JavaScript utility file (Class-based or Functional)
├── index.d.ts        # TypeScript definition file for the utility
├── examples/
│   └── index.js      # Example usage demonstrating the utility
└── README.md         # This file

Usage Example (examples/index.js):

// examples/index.js
import { useState } from "../index.js";
const counter = new useState(0);

console.log("Initial value:", counter.value);

counter.useEffect((currentCount) => {
  console.log("useEffect triggered (Counter):", currentCount);
});

counter.set(5);

counter.set((prev) => prev + 1);

console.log("Current value:", counter.value);

const greeting = new useState("Hello");

greeting.useEffect((currentText) => {
  console.log(
    "useEffect triggered (Greeting):",
    currentText.toUpperCase() + "!"
  );
});

greeting.set("World");

2. Functional Approach (If you prefer, configure your index.js file this way)

export function useState(initialState) {
  let state = initialState;
  const _effects = [];

  const stateObject = {
    useEffect: function (callback) {
      _effects.push(callback);
      callback(state);
    },
    // ...
  };
  return stateObject;
}

Usage Example (examples/index.js):

// examples/index.js
import { useState } from "../index.js";

const counter = useState(0);

console.log("Initial value:", counter.value);

counter.useEffect((currentCount) => {
  console.log("useEffect triggered (Counter):", currentCount);
});

counter.set(5);

counter.set((prev) => prev + 1);

console.log("Current value:", counter.value);

API Reference

Both approaches (class-based and functional) essentially expose the same API:

useState<T>(initialState: T)

• Parameters:
  • initialState: T: The initial value of the state. T can be any JavaScript type.
• Returns: An object to manage the state.

Properties and Methods of the Returned Object:

• value: T (getter)
  • Returns the current value of the state. It's a read-only property.
• set(newValue: T | ((_state: T) => T)): this
  • Updates the state's value.
  • Parameters:
    • newValue: The new value for the state, OR a function that receives the current state and returns the new state.
  • Returns: The current useState object for chaining.
• useEffect(callback: (_state: T) => any): void
  • Registers a callback function to be invoked whenever the state is updated.
  • Important: It is also triggered once immediately upon registration with the current state value.
  • Parameters:
    • callback: A function that receives the new state as an argument.
• toString(): string
  • Returns the string representation of the state.
• valueOf(): T
  • Returns the primitive value of the state (useful if the state is an object).

TypeScript Support

The index.d.ts file is included to provide proper type checking and autocompletion when using this utility in your TypeScript projects.

import { useState } from "node-usestate";

const count = new useState<number>(0);
count.useEffect((c) => {
  console.log("Counter changed:", c);
});

const user = useState<{ name: string; age: number }>({
  name: "Alice",
  age: 30,
});
user.set((prev) => ({ ...prev, age: prev.age + 1 }));

Contributing

Contributions and bug fixes are welcome! Feel free to open a pull request or an issue.