react-magic-search-params 1.0.1 → 1.1.3

package/README.md

@@ -17,6 +17,507 @@ To install this library, run:
 npm install react-magic-search-params
 ```
 
+<details>
+<summary><strong>Ver versión en español 🇪🇸</strong></summary>
+
+## Índice 📑
+
+1. [Introducción General](#introducción-general)  
+   1.1 [Propósito del Hook](#propósito-del-hook)  
+   1.2 [Contexto de Implementación](#contexto-de-implementación)
+2. [Tipos de Parámetros que Acepta](#tipos-de-parámetros-que-acepta)  
+   2.1 [mandatory (Obligatorios)](#mandatory-obligatorios)  
+   2.2 [optional (Opcionales)](#optional-opcionales)  
+   2.3 [defaultParams](#defaultparams)  
+   2.4 [forceParams](#forceparams)  
+   2.5 [omitParamsByValues](#omitparamsbyvalues)
+   2.6 [arraySerialization](#arraySerialization)
+3. [Recomendación de Uso con Archivo de Constantes](#recomendación-de-uso-con-archivo-de-constantes)
+4. [Funciones Principales](#funciones-principales)  
+   4.1 [getParams](#getparams)  
+   4.2 [updateParams](#updateparams)  
+   4.3 [clearParams](#clearparams)
+
+5. [Características Clave y Beneficios](#características-clave-y-beneficios)
+6. [Ejemplo de Uso & Explicaciones](#ejemplo-de-uso--explicaciones)
+7. [Serialización de Arrays en la URL(nuevo)](#serialización-de-arrays-en-la-url)
+8. [Buenas Prácticas y Consideraciones](#buenas-prácticas-y-consideraciones) ✅
+9. [Pruebas Unitarias con Vitest](#Ejecución-de-pruebas)
+10. [Conclusión](#conclusión) 🎯
+
+---
+
+# Introducción General
+
+<img src="https://github.com/user-attachments/assets/1f437570-6f30-4c10-b27d-b876f5c557bd" alt="Captura de pantalla" width="800px" />
+
+## Propósito del Hook 🎯
+
+El **hook `useMagicSearchParams`** habilita un manejo **avanzado** y **centralizado** de parámetros en la URL.  
+Permite definir y unificar lógica para filtrar, paginar o realizar cualquier otra operación que dependa de parámetros en la cadena de consulta (ej. `?page=1&page_size=10`).
+
+**Antes (sin autocompletado ni tipado)**
+En esta sección se ilustra rápidamente cómo cambiaba el manejo de parámetros antes de usar el hook y cómo se simplifica con `useMagicSearchParams`.
+
+<details>
+<summary><strong>Antes (manejo manual de URLs)❌</strong></summary>
+
+```jsx
+// filepath: /example/BeforeHook.tsx
+
+export const BeforeHookExample = () => {
+  const [searchParams, setSearchParams] = useSearchParams()
+
+  // Extraer valores manualmente (sin tipado ni validación)
+  const page = parseInt(searchParams.get('page') || '1', 10)
+  const pageSize = parseInt(searchParams.get('page_size') || '10', 10)
+  const search = searchParams.get('search') || ''
+
+  const handleChangePage = (newPage: number) => {
+    searchParams.set('page', newPage.toString())
+    setSearchParams(searchParams)
+  }
+
+  return (
+    <div>
+      <p>Página: {page}</p>
+      <p>page_size: {pageSize}</p>
+      <p>search: {search}</p>
+      {/* Botón para cambiar de página */}
+      <button onClick={() => handleChangePage(page + 1)}>Siguiente página</button>
+    </div>
+  )
+}
+```
+
+</details> 
+<details> <summary><strong>Después (con autocompletado y seguridad)✅</strong></summary>
+
+```jsx
+// filepath: /example/AfterHook.tsx
+import { useMagicSearchParams } from "react-magic-search-params";
+import { paramsUsers } from "@/constants/DefaultParamsPage";
+
+export const AfterHookExample = () => {
+  // contexto de Api externa...
+  const { searchParams, getParams, updateParams } = useMagicSearchParams({
+    ...paramsUsers,
+    forceParams: { page_size: paramsUsers.mandatory.page_size }, // se limita a 10
+    omitParamsByValues: ["all", "default"],
+  });
+
+  useEffect(() => {
+    const paramsUser = getParams();
+
+    async function loadUsers() {
+      toast.loading("Cargando...", { id: "loading" });
+
+      console.log({ paramsUser });
+      const { success, message } = await getUsersContext(paramsUser);
+      if (success) {
+        toast.success(message ?? "Usuarios obtenidos", { id: "loading" });
+        setLoading(false);
+      } else {
+        toast.error(message ?? "Error inesperado al obtener los usuarios", {
+          id: "loading",
+        });
+      }
+    }
+    loadUsers();
+  }, [searchParams]);
+
+  // getParams devuelve datos convertidos y tipados con autocompletado
+  const { page, page_size, search } = getParams({ convert: true });
+
+  const handleNextPage = () => {
+    const nextPage = { page: (page ?? 1) + 1 };
+    updateParams({ newParams: nextpage }); // por defecto se mantienen los otros parámetros de consulta
+  };
+
+  return (
+    <div>
+      {/* Nota: normalmente el input será de tipo "no controlado" debido a que normalmente se utilizar una técnica de "debounce" para demorar la actualización */}
+      <input
+        defaultValue={search}
+        placeholder="Buscar por..."
+        onChange={handleSearchChange}
+      />
+      <p>Página actual: {page}</p>
+      <p>Tamaño de página: {page_size}</p>
+      <p>Búsqueda: {search}</p>
+      <button onClick={handleNextPage}>Siguiente página</button>
+    </div>
+  );
+};
+```
+
+</details>
+
+#### Información Adicional 📋
+
+1. **_Tipado Estricto_**
+
+- Al definir “mandatory” y “optional” desde un archivo de constantes, TypeScript infiere las claves disponibles en la URL.
+
+2. **_Control en la URL_**
+
+- “forceParams” refuerza valores fijos (evitando sobrecargas innecesarias de la API).
+  “omitParamsByValues” limpia parámetros como “all” o “default” que no aportan información real.
+
+3. **_Reutilización en Distintas Vistas_**
+
+- Cada vista puede tener su propio `mandatory` y `optional`.
+  Se evita duplicar lógica de extracción y validación de parámetros.
+
+4. **_Orden Uniforme en la URL_**
+
+- **sortParameters** garantiza un orden predecible (primero “page”, luego “page_size”, etc.).
+
+### Contexto de su Implementación
+
+1. **Evita múltiples fuentes de la verdad**: Al separar la lógica en un hook único, no se repite código en cada archivo.
+2. **Asegura un Estándar Común** Todos los parámetros (obligatorios u opcionales) se definen en un mismo lugar
+3. **Controlar la URL**: Evita inyecciones de parámetros no deseados y mantiene un orden consistente (ej. `?page=1&page_size=10` en vez de ?`page_size=10&page=1`).
+
+### Tipos de Parámetros Aceptados
+
+1. **Mandatory**:(Obligatorios)
+
+- Ejemplo típico: Paginación (page, page_size)
+- Siempre deben existir en la URL para que la vista funcione.
+
+2. **Optional**:(Opcionales)
+
+- Ejemplo: Filtros de búsqueda (search, order).
+- No afectan la ruta si no están presentes.
+
+3. **DefaultParams**:(parámetros por defecto)
+
+- Se establecen automáticamente al cargar un componente.
+- Útiles para `filtros por defecto` o configuraciones iniciales.
+- A diferencia de los parámetros agregados en enlaces ej: `sistema/lista?page=1&page_size=10`, estos se cargan según el componente (página) que se este visitando, asegurando que la página visitada siempre tenga parámetros por defecto, aunque el usuario los elimine, esto asegura que las llamadas a una **API** que útiliza los párametros de la URL devuelva los datos correctos.
+
+4. **ForceParams**:(Parámetros forzados)
+
+- Fuerzan valores que no se pueden sobrescribir (ej: page_size=10).
+- Garantizan una máxima seguridad, mientras que mejoran la experiencia del usuario (evitar page_size=1000)
+
+5. **OmitParamsByValues**:(Parámetros omitidos por Valores)
+
+- Lista de valores que, si se detectan, se omiten de la **URL** (ej. 'all', 'default')
+- Simplifica URLS, omitiendo parámetros que no aportan información real
+- Reserva espacio para otros parámetros de consulta por la limitación de los mismos en la url _Dependiendo del Navegador que se utilize._
+
+6. **arraySerialization**:(Serialización de Arrays)
+
+- Permite Serializar arrays en la **URL** con 3 distintos métodos (csv, repeat, brackets)
+- Posibilidad de actualizarlos a través de 2 metodos, toggle (agregar, eliminar) y pasando un array de valores ej tags: ['nuevo1', 'nuevo2']
+- Es accesible a través del metodo `getParams` para obtener sus valores de tipo string ej:`tags=uno,dos,tres` o convertido a su tipo original ej: `tags: ['uno', 'dos','tres']`
+
+## Recomendación de uso de un Archivo de Constantes📁
+
+- Definir los parámetros obligatorios y opcionales en un único archivo (ej. defaultParamsPage.ts)
+- **Beneficios**:
+  - **_Mayor consistencia_**: Todo queda centralizado, lo que significa tener una única fuente de la verdad de los párametros de cada página.
+  - **_Tipado seguro_**: Garantiza autocompletado y reduce errores de escritures
+
+> [!NOTE]
+> De esta forma Typescript Podrá inferir los tipos de los párametros de consulta y sus valores por defecto a manejar.
+
+```typescript
+type UserTagOptions = 'tag1' | 'tag2' | 'react' | 'node' | 'typescript' | 'javascript';
+type OrderUserProps = 'role' | 'date';
+// Puedes especificar los valores para ayudar a que typescript te de más tipado
+export const paramsCrimesDashboard = {
+  mandatory: {
+    days: 7,
+  },
+  optional: {},
+};
+export const paramsUsers = {
+  mandatory: {
+    page: 1,
+    page_size: 10 as const,
+    only_is_active: false,
+  },
+  optional: {
+    order: "", as OrderUserProps
+    search: "",
+    tags: ['tag1', 'tag2'] as Array<UserTagOptions>
+  },
+};
+```
+> [!TIP]
+> Al **declarar explícitamente** los tipos (en lugar de basarse únicamente en la inferencia de tipos), se permite que TypeScript proporcione una comprobación de tipos más **estricta**. Esto garantiza que solo se permitan los valores definidos para cada parámetro, lo que ayuda a evitar la asignación accidental de valores no válidos.
+
+## Funciones Principales ⚙️
+
+### 1. getParams
+
+Obtiene los parámetros tipados y opcionalmente convertidos desde la URL.  
+Útil para recuperar “page”, “order”, “search”, etc., sin lidiar con valores nulos o tipos incorrectos.
+
+> [!NOTE]
+> Por defecto el hook `useSearchParams` de **react-router-dom** devuelve los parámetros en `string`, haunque los hayamos definido con otro tipo ej: `number`, esto lo soluciona el metodo `getParams` gracias a que guarda una referencia de su tipo original.
+
+<details>
+<summary><strong>Ejemplo de uso</strong></summary>
+
+```typescript
+// Obteniendo valores convertidos
+const { page, search } = getParams({ convert: true });
+
+// Ejemplo: mostrar parámetros en consola
+console.log("Página actual:", page); // number
+console.log("Búsqueda:", search); // string | undefined
+```
+
+</details>
+
+### 2. updateParams
+
+Modifica de forma controlada los parámetros en la URL, respetando valores obligatorios;
+puedes reiniciar un valor sin perder el resto (ej. setear `page=1` y mantener `search`).
+
+<details> 
+<summary><strong>Ejemplo de uso</strong></summary>
+
+```typescript
+// Cambiar de página y conservar orden actual
+updateParams({
+  newParams: { page: 2 },
+  keepParams: { order: true },
+});
+
+// Establecer un nuevo filtro y reiniciar la página
+updateParams({ newParams: { page: 1, search: "John" } });
+```
+
+</details>
+
+### 3. clearParams
+
+Reinicia los parámetros de la URL, manteniendo (o no) los obligatorios.
+Permite “limpiar” los filtros y volver al estado inicial.
+
+<details> <summary><strong>Ejemplo de uso</strong></summary>
+
+```typescript
+// Limpia todo y conserva obligatorios
+clearParams();
+
+// Limpia incluso los obligatorios
+clearParams({ keepMandatoryParams: false });
+```
+
+</details>
+
+### Ejemplo de Uso & Explicaciones 🖥️💡
+
+En el siguiente ejemplo, se combinan:
+
+**mandatory**: Necesarios para la paginación.
+**optional**: Parámetros de búsqueda y orden.
+**forceParams**: Parámetros que no deben cambiar (p. ej. “page_size=1”).
+**omitParamsByValues**: Se omiten valores como “all” o “default”.
+
+```jsx
+// filepath: /c:/.../FilterUsers.tsx
+import { useMagicSearchParams } from "@/hooks/UseMagicSearchParams";
+import { paramsUsers } from "@constants/DefaultParamsPage";
+
+export const FilterUsers = (props) => {
+  const { searchParams, updateParams, clearParams, getParams } =
+    useMagicSearchParams({
+      ...paramsUsers,
+      defaultParams: paramsUsers.mandatory,
+      forceParams: { page_size: 1 },
+      omitParamsByValues: ["all", "default"],
+    });
+
+  // Recuperar parámetros convertidos a sus tipos originales
+  const { page, search, order } = getParams({ convert: true });
+
+  // Actualizar: setear página = 1 y cambiar búsqueda
+  const handleChangeSearch = (evt) => {
+    updateParams({ newParams: { page: 1, search: evt.target.value } });
+  };
+
+  // Limpiar todo y conservar mandatorios por defecto
+  const handleReset = () => {
+    clearParams();
+  };
+
+  // ...
+};
+```
+
+**En este componente:**
+
+**_paramsUsers_** define los objetos “mandatory” y “optional”.
+**_forceParams_** evita que “page*size” sea modificado por el usuario.
+\*\*\_omitParamsByValues*** descarta valores que no aporten datos reales (“all”, “default”).
+**_getParams_** devuelve valores tipados (números, booleanos, strings, etc.).
+**_updateParams_** y **_clearParams_\*\* simplifican los flujos de actualización en la URL.
+
+## 7 Serialización de Arrays en la URL 🚀
+
+El hook `useMagicSearchParams` ahora permite gestionar parámetros de tipo array de forma **avanzada** y **flexible**, enviándolos de forma óptima al backend según el formato requerido. Esto se logra mediante la opción `arraySerialization`, que admite tres técnicas:
+
+### Métodos de Serialización 🔄
+
+- **csv**:  
+  Serializa el array en una única cadena separada por comas.  
+  **Ejemplo:**  
+  `tags=tag1,tag2,tag3`  
+  _Ideal cuando el backend espera un solo string._
+
+- **repeat**:  
+  Envía cada elemento del array como un parámetro separado.  
+  **Ejemplo:**  
+  `tags=tag1&tags=tag2&tags=tag3`  
+  _Perfecto para APIs que manejan múltiples entradas con la misma clave._
+
+- **brackets**:  
+  Utiliza la notación con corchetes en la clave para cada elemento.  
+  **Ejemplo:**  
+  `tags[]=tag1&tags[]=tag2&tags[]=tag3`  
+  _Útil para frameworks que esperan este formato (ej. PHP)._
+
+> [!TIP]
+> Al extraer los valores de `tags` con `getParams({ convert: true })` obtendrás:
+>
+> - **String** si no se especifica conversión (ej:csv): `"tags=tag1,tag2,tag3"`
+> - **Array** si se convierte: `tags=['tag1', 'tag2', 'tag3']`  
+>   _Esto mejora la consistencia y tipado en tu aplicación._
+
+### Ventajas y Beneficios 🌟
+
+- **Flexibilidad de Envío**:  
+  Elige el método que mejor se adapte a las necesidades del backend.  
+  ✅ _Mayor compatibilidad con distintos sistemas._
+
+- **Normalización Automática**:  
+  Las claves que llegan en formato `tags[]` se normalizan a `tags` para facilitar su manejo.  
+  ✅ _Más fácil iterar y convertir a tipos originales._
+
+- **Control Total de la URL**:  
+  El hook gestiona la reescritura de la URL de forma consistente, reduciendo errores y manteniendo la legibilidad.  
+  🔒 _Mejora la seguridad y el control de los parámetros._
+
+### Ejemplos de Uso en Código 👨‍💻
+
+```jsx
+import { useMagicSearchParams } from "../src/hooks/useMagicSearchParams";
+import { paramsUsers } from "../src/constants/defaulParamsPage";
+
+export default function App() {
+  const { searchParams, getParams, updateParams, clearParams } = useMagicSearchParams({
+    ...paramsUsers,
+    defaultParams: paramsUsers.mandatory,
+    arraySerialization: 'repeat', // Puedes cambiar a 'csv' o 'brackets' según prefieras.
+    omitParamsByValues: ["all", "default"],
+  });
+
+  // Obtener parámetros convertidos (por ejemplo, tags se obtiene como array)
+  const { tags, page } = getParams({ convert: true });
+
+ const availableTags = ['react', 'node', 'typescript', 'javascript']
+
+  // Ejemplo: Actualizar el array de tags con toggle
+  const handleTagToggle = (newTag: string) => {
+    // si ya existe se elimina, sino se agrega
+    updateParams({ newParams: { tags: newTag } });
+  };
+  // pasar un array de tags, útil para agregar múltiples filtros a la vez
+  const handleTagToggleArray = (newTags: string[]) => {
+    // el hook se encarga de que no existán valores repetidos en el array haciendo
+    // merge con los anteriores
+    updateParams({ newParams: { tags: [...tags, ..newTags] } });
+  };
+  return (
+    <div>
+      <div>
+        <h3 className='text-lg font-semibold mb-3'>Selecciona Tags:</h3>
+          {availableTags.map(tag => {
+            const isActive = Array.isArray(tags) && tags.includes(tag)
+            return (
+              <button
+                key={tag}
+                onClick={() => handleTagToggle(tag)}
+                className={`px-4 py-2 rounded-md border ${
+                  isActive ? 'bg-blue-500 text-white' : 'bg-gray-200 text-gray-700'
+                }`}
+              >
+                {tag}
+              </button>
+            )
+          })}
+      </div>
+      <p>Tags actuales: {JSON.stringify(tags)}</p>
+      {/* Resto del componente */}
+    </div>
+  );
+}
+```
+
+En este ejemplo, al utilizar la serialización **repeat**, la `URL` resultante se verá así:
+
+- **Modo (repeat)**: `?page=1&page_size=10&only_is_active=false&tags=tag1&tags=tag2&tags=tag3`
+- **Modo (csv)**: `?page=1&page_size=10&only_is_active=false&tags=tag1,tag2,tag3`
+- **Modo (brackets)**: `?page=1&page_size=10&only_is_active=false&tags[]=tag1&tags[]=tag2&tags[]=tag3`
+
+### Esta nueva funcionalidad permite:
+
+- Enviar arrays de forma que se ajusten a las expectativas del backend.
+- Gestionar de forma centralizada la conversión y serialización, reduciendo la complejidad en componentes individuales.
+- Mantener la URL limpia y consistente, independientemente del método de serialización elegido.
+- **Dar control total al desarrollador** sobre cómo transformar o enviar los parámetros, permitiendo operaciones personalizadas en función del backend.
+
+### ¿Por Qué Esta Funcionalidad Es Clave? 🎯
+
+- **Enviar arrays al backend de forma adaptable:**
+  Se ajusta a diversos formatos que los servidores pueden esperar.
+- **Reducción de complejidad en componentes:**
+  Centraliza la lógica de serialización, evitando redundancia en el código.
+- **Mejor experiencia para el usuario:**
+  Una URL limpia y consistente facilita la depuración y mejora la usabilidad.
+
+## 8 Buenas Prácticas y Consideraciones ✅
+
+1. **Validar parámetros sensibles en backend**: Aunque el hook protege en frontend, el servidor debe imponer límites.
+2. **Mantener los tipos actualizados**: A medida que cambian los requisitos, actualizar “mandatory” y “optional” para evitar descalces.
+3. **Archivo de constantes por vista**: Permite organizar mejor cada pantalla o sección, manteniendo claridad y orden.
+
+---
+
+## 9 Pruebas Unitarias 🔬
+
+Este proyecto cuenta con pruebas automatizadas para asegurar su robustez y fiabilidad.
+
+### Ejecuta tus pruebas con `Vitest` 🧪
+
+Para validar el funcionamiento de este hook (y de los demás), puedes dirigirte al directorio de tests y ejecutar el siguiente comando en la terminal:
+
+```bash
+npm run test ./test/useMagicSearchParams.test.ts
+```
+
+> [!WARNING]
+> Nota: Asegúrate de tener Vitest configurado en tu proyecto para que estas pruebas se ejecuten correctamente, puedes ver la versión con `npm list`
+
+## 10 Conclusión 🎉
+
+El hook `useMagicSearchParams` aporta:
+
+- **Legibilidad y Mantenibilidad** al centralizar la lógica.
+- **Robustez** en la gestión de parámetros, limitando valores inseguros y permitiendo un flujo coherente.
+
+Se recomienda ajustarlo o expandirlo según las necesidades de cada proyecto, añadiendo, por ejemplo, validaciones avanzadas o conversiones adicionales de tipos.
+
+---
+</details>
+
 ## Table of Contents 📑
 
 1. [General Introduction](#general-introduction)  
@@ -56,7 +557,7 @@ It allows you to define and unify logic to filter, paginate, or perform any othe
 This section quickly illustrates how parameter handling changed before using the hook and how it simplifies with `useMagicSearchParams`.
 
 <details>
-<summary>Before (manual URL handling) ❌</summary>
+<summary><strong>Before (manual URL handling) ❌</strong></summary>
 
 ```jsx
 // filepath: /example/BeforeHook.tsx
@@ -87,7 +588,8 @@ export const BeforeHookExample = () => {
 ```
 
 </details> 
-</details> <details> <summary>After (with autocomplete and safety) ✅</summary>
+
+</details> <details> <summary><strong>After (with autocomplete and safety) ✅</strong></summary>
 
 ```jsx
 // filepath: /example/AfterHook.tsx
@@ -151,6 +653,9 @@ export const AfterHookExample = () => {
 
 </details>
 
+> [!NOTE]
+> Since this hook utilizes react-router-dom, make sure your application is wrapped in `<BrowserRouter>` or `<RouterProvider>` (the modern version in React Router v6.4+) so that routing works correctly.
+
 #### Additional Information 📋
 
 1. **Strict Typing_**
@@ -183,7 +688,7 @@ export const AfterHookExample = () => {
 - Typical example: Pagination (page, page_size)
 - They must always exist in the URL for the view to work.
 
-2. **Optional**:(Opcionales)
+2. **Optional**:
 
 - Example: Search filters (search, order).
 - They do not affect the **route** if they are not present.
@@ -199,7 +704,7 @@ export const AfterHookExample = () => {
 - Enforce values that cannot be overwritten (e.g. page_size=10).
 - Provides maximum safety while enhancing user experience (avoid page_size=1000).
 
-5. **OmitParamsByValues**:(Parámetros omitidos por Valores)
+5. **OmitParamsByValues**:(Parameters Omitted by values)
 
 - A list of values that, if detected, are omitted from the **URL** (e.g. ‘all’, ‘default’).
 - Simplifies URLs by removing parameters that do not provide real information.
@@ -245,6 +750,8 @@ export const paramsUsers = {
   },
 };
 ```
+> [!TIP]
+> By **explicitly declaring** the types (instead of relying solely on type inference), you enable TypeScript to provide **stricter type checking**. This ensures that only the defined values are allowed for each parameter, helping to avoid accidental assignment of invalid values.
 
 ## 4 Main Functions ⚙️
 
@@ -257,7 +764,7 @@ Useful to pull `“page”, “order”, “search”`, etc. without dealing wit
 > By default, the **react-router-dom** `useSearchParams` hook returns parameters as `string`, even if defined with another type (e.g. `number`). The `getParams` method solves this by keeping a reference to their original type.
 
 <details>
-<summary>Ejemplo de uso</summary>
+<summary>Example of use</summary>
 
 ```typescript
 // Retrieving converted values
@@ -277,7 +784,7 @@ console.log("Search:", search); // string | undefined
 Safely modifies URL parameters, respecting mandatory values; you may reset one value without losing the rest (e.g. set `page=1` while keeping `search`).
 
 <details> 
-<summary>Ejemplo de uso</summary>
+<summary>Example of use</summary>
 
 ```typescript
 // Change page and keep the current order
@@ -296,7 +803,7 @@ updateParams({ newParams: { page: 1, search: "John" } });
 
 Resets the URL parameters, optionally keeping mandatory ones.
 Allows you to “clear” the filters and return to the initial state.
-<details> <summary>Ejemplo de uso</summary>
+<details> <summary>Example of use</summary>
 
 ```typescript
 // Clear everything and keep mandatory parameters

package/dist/index.d.ts

@@ -1 +1 @@
-export { useMagicSearchParams } from './useMagicSearchParams';
+export { useMagicSearchParams, UseMagicSearchParamsOptions } from './useMagicSearchParams';

package/dist/react-magic-search-params.cjs.development.js

@@ -166,9 +166,6 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
         updatedParams[key] = combined;
       }
     });
-    console.log({
-      updatedParams: updatedParams
-    });
     return updatedParams;
   };
   var transformParamsToURLSearch = function transformParamsToURLSearch(params) {
@@ -222,9 +219,6 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
         newParam.set(key, params[key]);
       }
     }
-    console.log({
-      FINAL: newParam.toString()
-    });
     return newParam;
   };
   // @ts-ignore
@@ -367,6 +361,11 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
   var CURRENT_PARAMS_URL = react.useMemo(function () {
     return arraySerialization === 'brackets' ? getParamsObj(searchParams) : Object.fromEntries(searchParams.entries());
   }, [searchParams, arraySerialization]);
+  /**
+    * Gets the current parameters from the URL and converts them to their original type if desired
+   * @param convert - If true, converts from string to the inferred type (number, boolean, ...)
+   * @returns - Returns the current parameters of the URL
+   */
   var getParams = function getParams(_temp) {
     var _ref4 = _temp === void 0 ? {} : _temp,
       _ref4$convert = _ref4.convert,
@@ -382,6 +381,12 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
     }, {});
     return params;
   };
+  /**
+    * Gets the value of a parameter from the URL and converts it to its original type if desired
+   * @param key - Key of the parameter
+   * @param options - Options to convert the value to its original type, default is true
+   * @returns - Returns the value of the parameter
+   */
   var getParam = function getParam(key, options) {
     var keyStr = String(key);
     // @ts-ignore
@@ -439,6 +444,10 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
     }, {});
     return paramsUrlFound;
   };
+  /**
+   clears the parameters of the URL, keeping the mandatory parameters
+   * @param keepMandatoryParams - If true, the mandatory parameters are kept in the URL
+   */
   var clearParams = function clearParams(_temp2) {
     var _ref6 = _temp2 === void 0 ? {} : _temp2,
       _ref6$keepMandatoryPa = _ref6.keepMandatoryParams,
@@ -447,6 +456,11 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
     var paramsTransformed = transformParamsToURLSearch(_extends({}, mandatory, keepMandatoryParams && _extends({}, mandatoryParameters()), forceParams));
     setSearchParams(paramsTransformed);
   };
+  /**
+   Merges the new parameters with the current ones, omits the parameters that are not sent and sorts them according to the structure
+   * @param newParams - New parameters to be sent in the URL
+   * @param keepParams - Parameters to keep in the URL, default is true
+   */
   var updateParams = function updateParams(_temp3) {
     var _ref7 = _temp3 === void 0 ? {} : _temp3,
       _ref7$newParams = _ref7.newParams,
@@ -463,7 +477,11 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
     var paramsSorted = sortParameters(convertedArrayValues);
     setSearchParams(transformParamsToURLSearch(paramsSorted));
   };
-  // only for the keys of the parameters to subscribe to changes in the URL to trigger the callback
+  /**
+   * @param paramName - Name of the parameter to subscribe to
+   * @param callbacks - Callbacks to be executed when the parameter changes
+   * @returns - Returns the function to unsubscribe
+   */
   var onChange = react.useCallback(function (paramName, callbacks) {
     var paramNameStr = String(paramName);
     // replace the previous callbacks with the new ones so as not to accumulate callbacks
@@ -481,7 +499,6 @@ var useMagicSearchParams = function useMagicSearchParams(_ref) {
       if (newValue !== oldValue) {
         for (var _iterator4 = _createForOfIteratorHelperLoose(value), _step4; !(_step4 = _iterator4()).done;) {
           var callback = _step4.value;
-          console.log(value);
           callback();
         }
       }