# Using npm
npm install am-redux-state

# Using yarn
yarn add am-redux-state


Usage
Basic Example

Below is a simple usage example in a React component:

import React from 'react';
import { AM_ReduxState } from 'am-redux-state';

const ExampleComponent: React.FC = () => {
  // Using the hook with full TypeScript support for auto-completion
  const [data, setData, resetData, loading, error, clearLocal, clearRedux] =
    AM_ReduxState<{ name: string }>("data", { name: "mohmed" });

  return (
    <div>
      <h1>AM_ReduxState Usage Example</h1>
      <p>Current Name: {data.name}</p>
      {loading && <p>Loading update...</p>}
      {error && <p style={{ color: 'red' }}>Error: {error}</p>}
      <button onClick={() => setData({ name: "Ahmed" }, true)}>
        Update Name and Save to localStorage
      </button>
      <button onClick={resetData}>
        Reset to Initial Value
      </button>
      <button onClick={clearLocal}>
        Clear localStorage Data
      </button>
      <button onClick={clearRedux}>
        Clear Redux State
      </button>
    </div>
  );
};

export default ExampleComponent;

Advanced Usage

You can further customize the hook behavior by:

    Adjusting the debounceTime parameter.
    Passing an array of custom validation functions.
    Switching to throttle by setting useThrottle to true.

For instance:

const isNotEmpty = (value: { name: string }): boolean => {
  return value.name.trim().length > 0;
};

const [data, setData] = AM_ReduxState<{ name: string }>(
  "userData",
  { name: "mohmed" },
  500,                   // Custom debounce time
  [isNotEmpty],          // Custom validation function(s)
  false                  // Use debounce (set to true to use throttle)
);
/**
 * AM_ReduxState Hook.
 *
 * @template T - The type of the managed value.
 * @param key - A unique key for the state.
 * @param initialValue - The initial state value.
 * @param debounceTime - The debounce/throttle delay in milliseconds (default is 300).
 * @param validate - Optional array of validation functions.
 * @param useThrottle - Whether to use throttle instead of debounce (default is false).
 * @returns {UseReduxStateReturn<T>} An array containing:
 *   1. Current Value: Determined from Redux, localStorage, or the initial value.
 *   2. setValue: Function to update the state value (debounced/throttled).
 *   3. resetValue: Function to reset the state to its initial value.
 *   4. loading: Boolean indicating the loading state during updates.
 *   5. error: Error message if an error occurs.
 *   6. clearLocalStorage: Function to clear the value from localStorage.
 *   7. clearReduxState: Function to clear the value from Redux.
 */

Return Type

export type UseReduxStateReturn<T> = [
  T,
  (newValue: T | ((prevValue: T) => T), saveToLocalStorage?: boolean) => void,
  () => void,
  boolean,
  string | null,
  () => void,
  () => void
];

Validation Example

Custom validation functions can be passed to ensure that the new state meets your criteria:

const isNotEmpty = (value: { name: string }): boolean => {
  return value.name.trim().length > 0;
};

const [data, setData] = AM_ReduxState<{ name: string }>(
  "data",
  { name: "mohmed" },
  300,
  [isNotEmpty]
);

FAQ
Q: What happens if localStorage contains corrupted data?

A: The hook will catch JSON parsing errors, log the error to the console, and remove the corrupted entry from localStorage.
Q: Can I switch between debounce and throttle?

A: Yes. Set the useThrottle parameter to true to use throttle instead of debounce.
Q: Does this library support auto-completion?

A: Absolutely. The library is fully typed with TypeScript, offering rich auto-completion in supported editors.
Contributing

We welcome contributions and suggestions to improve AM_ReduxState. If you have any ideas or bug reports, please open an issue or submit a pull request on the official repository.
Roadmap

    Enhanced error handling: Add more detailed error logging and user notifications.
    Improved performance: Explore optimizations for handling large or complex state objects.
    Extended API: Consider adding additional configuration options and hooks based on community feedback.

License

This project is licensed under the MIT License.
Copyright

© A&M mohmed ahmed. All rights reserved.

    Note:
    AM_ReduxState is an open-source library. Contributions and feedback are greatly appreciated to help improve its functionality and performance.



This README is designed to provide a clear, comprehensive guide for users and contributors alike. Feel free to adjust repository links and other project-specific details as needed.