Índice 📑

1. Introducción General
   1.1 Propósito del Hook
   1.2 Contexto de Implementación

2. Tipos de Parámetros que Acepta
   2.1 mandatory (Obligatorios)
   2.2 optional (Opcionales)
   2.3 defaultParams
   2.4 forceParams
   2.5 omitParamsByValues 2.6 arraySerialization

3. Recomendación de Uso con Archivo de Constantes

4. Funciones Principales
   4.1 getParams
   4.2 updateParams
   4.3 clearParams

5. Características Clave y Beneficios

6. Ejemplo de Uso & Explicaciones

7. Serialización de Arrays en la URL(nuevo)

8. Buenas Prácticas y Consideraciones ✅

9. Pruebas Unitarias con Vitest

10. Conclusión 🎯

Introducción General

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.

1// filepath: /example/BeforeHook.tsx
2
3export const BeforeHookExample = () => {
4  const [searchParams, setSearchParams] = useSearchParams()
5
6  // Extraer valores manualmente (sin tipado ni validación)
7  const page = parseInt(searchParams.get('page') || '1', 10)
8  const pageSize = parseInt(searchParams.get('page_size') || '10', 10)
9  const search = searchParams.get('search') || ''
10
11  const handleChangePage = (newPage: number) => {
12    searchParams.set('page', newPage.toString())
13    setSearchParams(searchParams)
14  }
15
16  return (
17    <div>
18      <p>Página: {page}</p>
19      <p>page_size: {pageSize}</p>
20      <p>search: {search}</p>
21      {/* Botón para cambiar de página */}
22      <button onClick={() => handleChangePage(page + 1)}>Siguiente página</button>
23    </div>
24  )
25}

1// filepath: /example/AfterHook.tsx
2import { useMagicSearchParams } from "react-magic-search-params";
3import { paramsUsers } from "@/constants/DefaultParamsPage";
4
5export const AfterHookExample = () => {
6  // contexto de Api externa...
7  const { searchParams, getParams, updateParams } = useMagicSearchParams({
8    ...paramsUsers,
9    forceParams: { page_size: paramsUsers.mandatory.page_size }, // se limita a 10
10    omitParamsByValues: ["all", "default"],
11  });
12
13  useEffect(() => {
14    const paramsUser = getParams();
15
16    async function loadUsers() {
17      toast.loading("Cargando...", { id: "loading" });
18
19      console.log({ paramsUser });
20      const { success, message } = await getUsersContext(paramsUser);
21      if (success) {
22        toast.success(message ?? "Usuarios obtenidos", { id: "loading" });
23        setLoading(false);
24      } else {
25        toast.error(message ?? "Error inesperado al obtener los usuarios", {
26          id: "loading",
27        });
28      }
29    }
30    loadUsers();
31  }, [searchParams]);
32
33  // getParams devuelve datos convertidos y tipados con autocompletado
34  const { page, page_size, search } = getParams({ convert: true });
35
36  const handleNextPage = () => {
37    const nextPage = { page: (page ?? 1) + 1 };
38    updateParams({ newParams: nextpage }); // por defecto se mantienen los otros parámetros de consulta
39  };
40
41  return (
42    <div>
43      {/* 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 */}
44      <input
45        defaultValue={search}
46        placeholder="Buscar por..."
47        onChange={handleSearchChange}
48      />
49      <p>Página actual: {page}</p>
50      <p>Tamaño de página: {page_size}</p>
51      <p>Búsqueda: {search}</p>
52      <button onClick={handleNextPage}>Siguiente página</button>
53    </div>
54  );
55};

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.

1type UserTagOptions = 'tag1' | 'tag2' | 'react' | 'node' | 'typescript' | 'javascript';
2type OrderUserProps = 'role' | 'date';
3// Puedes especificar los valores para ayudar a que typescript te de más tipado
4export const paramsCrimesDashboard = {
5  mandatory: {
6    days: 7,
7  },
8  optional: {},
9};
10export const paramsUsers = {
11  mandatory: {
12    page: 1,
13    page_size: 10 as const,
14    only_is_active: false,
15  },
16  optional: {
17    order: "", as OrderUserProps
18    search: "",
19    tags: ['tag1', 'tag2'] as Array<UserTagOptions>
20  },
21};

[!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.

1// Obteniendo valores convertidos
2const { page, search } = getParams({ convert: true });
3
4// Ejemplo: mostrar parámetros en consola
5console.log("Página actual:", page); // number
6console.log("Búsqueda:", search); // string | undefined

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).

1// Cambiar de página y conservar orden actual
2updateParams({
3  newParams: { page: 2 },
4  keepParams: { order: true },
5});
6
7// Establecer un nuevo filtro y reiniciar la página
8updateParams({ newParams: { page: 1, search: "John" } });

3. clearParams

Reinicia los parámetros de la URL, manteniendo (o no) los obligatorios. Permite “limpiar” los filtros y volver al estado inicial.

1// Limpia todo y conserva obligatorios
2clearParams();
3
4// Limpia incluso los obligatorios
5clearParams({ keepMandatoryParams: false });

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”.

1// filepath: /c:/.../FilterUsers.tsx
2import { useMagicSearchParams } from "@/hooks/UseMagicSearchParams";
3import { paramsUsers } from "@constants/DefaultParamsPage";
4
5export const FilterUsers = (props) => {
6  const { searchParams, updateParams, clearParams, getParams } =
7    useMagicSearchParams({
8      ...paramsUsers,
9      defaultParams: paramsUsers.mandatory,
10      forceParams: { page_size: 1 },
11      omitParamsByValues: ["all", "default"],
12    });
13
14  // Recuperar parámetros convertidos a sus tipos originales
15  const { page, search, order } = getParams({ convert: true });
16
17  // Actualizar: setear página = 1 y cambiar búsqueda
18  const handleChangeSearch = (evt) => {
19    updateParams({ newParams: { page: 1, search: evt.target.value } });
20  };
21
22  // Limpiar todo y conservar mandatorios por defecto
23  const handleReset = () => {
24    clearParams();
25  };
26
27  // ...
28};

En este componente:

paramsUsers define los objetos “mandatory” y “optional”. forceParams evita que “pagesize” 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 👨‍💻

1import { useMagicSearchParams } from "../src/hooks/useMagicSearchParams";
2import { paramsUsers } from "../src/constants/defaulParamsPage";
3
4export default function App() {
5  const { searchParams, getParams, updateParams, clearParams } = useMagicSearchParams({
6    ...paramsUsers,
7    defaultParams: paramsUsers.mandatory,
8    arraySerialization: 'repeat', // Puedes cambiar a 'csv' o 'brackets' según prefieras.
9    omitParamsByValues: ["all", "default"],
10  });
11
12  // Obtener parámetros convertidos (por ejemplo, tags se obtiene como array)
13  const { tags, page } = getParams({ convert: true });
14
15 const availableTags = ['react', 'node', 'typescript', 'javascript']
16
17  // Ejemplo: Actualizar el array de tags con toggle
18  const handleTagToggle = (newTag: string) => {
19    // si ya existe se elimina, sino se agrega
20    updateParams({ newParams: { tags: newTag } });
21  };
22  // pasar un array de tags, útil para agregar múltiples filtros a la vez
23  const handleTagToggleArray = (newTags: string[]) => {
24    // el hook se encarga de que no existán valores repetidos en el array haciendo
25    // merge con los anteriores
26    updateParams({ newParams: { tags: [...tags, ..newTags] } });
27  };
28  return (
29    <div>
30      <div>
31        <h3 className='text-lg font-semibold mb-3'>Selecciona Tags:</h3>
32          {availableTags.map(tag => {
33            const isActive = Array.isArray(tags) && tags.includes(tag)
34            return (
35              <button
36                key={tag}
37                onClick={() => handleTagToggle(tag)}
38                className={`px-4 py-2 rounded-md border ${
39                  isActive ? 'bg-blue-500 text-white' : 'bg-gray-200 text-gray-700'
40                }`}
41              >
42                {tag}
43              </button>
44            )
45          })}
46      </div>
47      <p>Tags actuales: {JSON.stringify(tags)}</p>
48      {/* Resto del componente */}
49    </div>
50  );
51}

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:

1npm 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.

[!TIP] Puede encontrar ejemplos prácticos de cómo implementar este Hook en *proyectos grandes, en el archivo de ejemplo.

Si encontraste esta libreriá útil, porfavor dale una ⭐️ al GitHub!

1// filepath: /example/BeforeHook.tsx
2
3export const BeforeHookExample = () => {
4  const [searchParams, setSearchParams] = useSearchParams()
5
6  // Manually extract values (no typing or validation)
7  const page = parseInt(searchParams.get('page') || '1', 10)
8  const pageSize = parseInt(searchParams.get('page_size') || '10', 10)
9  const search = searchParams.get('search') || ''
10
11  const handleChangePage = (newPage: number) => {
12    searchParams.set('page', newPage.toString())
13    setSearchParams(searchParams)
14  }
15
16  return (
17    <div>
18      <p>Page: {page}</p>
19      <p>page_size: {pageSize}</p>
20      <p>search: {search}</p>
21      {/* Button to move to the next page */}
22      <button onClick={() => handleChangePage(page + 1)}>Next page</button>
23    </div>
24  )
25}

1// filepath: /example/AfterHook.tsx
2import { useMagicSearchParams } from "react-magic-search-params";
3import { paramsUsers } from "@/constants/DefaultParamsPage";
4
5export const AfterHookExample = () => {
6  // context of an external API...
7  const { searchParams, getParams, updateParams } = useMagicSearchParams({
8    ...paramsUsers,
9    forceParams: { page_size: paramsUsers.mandatory.page_size }, // limited to 10
10    omitParamsByValues: ["all", "default"],
11  });
12
13  useEffect(() => {
14    const paramsUser = getParams();
15
16    async function loadUsers() {
17      toast.loading("Loading...", { id: "loading" });
18
19      console.log({ paramsUser });
20      const { success, message } = await getUsersContext(paramsUser);
21      if (success) {
22        toast.success(message ?? "Users retrieved", { id: "loading" });
23        setLoading(false);
24      } else {
25        toast.error(message ?? "Unexpected error retrieving the users", {
26          id: "loading",
27        });
28      }
29    }
30    loadUsers();
31  }, [searchParams]);
32
33  // getParams returns typed and converted data with autocomplete
34  const { page, page_size, search } = getParams({ convert: true });
35
36  const tags = getParam("tags", { convert: false })
37
38  const handleNextPage = () => {
39    const nextPage = { page: (page ?? 1) + 1 };
40    updateParams({ newParams: nextPage }); // by default, the rest of the query parameters are preserved
41  };
42
43  return (
44    <div>
45      {/* Note: typically this input will be “uncontrolled,” as you often use a “debounce” approach to delay updates */}
46      <input
47        defaultValue={search}
48        placeholder="Search by..."
49        onChange={handleSearchChange}
50      />
51      <p>Current page: {page}</p>
52      <p>Page size: {page_size}</p>
53      <p>Search: {search}</p>
54      <button onClick={handleNextPage}>Next page</button>
55    </div>
56  );
57};

1// Retrieving converted values
2const { page, search } = getParams({ convert: true });
3const tags = getParam("tags")
4// tags = [tag1, tag2]
5
6// Example: displaying parameters in console
7console.log("Current page:", page); // number
8console.log("Search:", search); // string | undefined

1// Change page and keep the current order
2updateParams({
3  newParams: { page: 2 },
4  keepParams: { order: true },
5});
6
7// Set a new filter and reset the page
8updateParams({ newParams: { page: 1, search: "John" } });

1// Clear everything and keep mandatory parameters
2clearParams();
3
4// Clear everything, including mandatory parameters
5clearParams({ keepMandatoryParams: false });