react-magic-search-params 1.2.0 → 2.1.2

package/src/useMagicSearchParams.ts

@@ -1,526 +0,0 @@
-import { useSearchParams } from 'react-router-dom'
-import { useMemo, useEffect, useRef, useCallback } from 'react'
-
-
-// Custom hook with advanced techniques to handle search parameters for any pagination
-
-type CommonParams = {
-  page?: number
-  page_size?: number
-}
-/*
-Maps all properties of M (mandatory) as required
-and all properties of O (optional) as optional. 
-*/
-type MergeParams<M, O> = {
-  [K in keyof M]: M[K]
-} & {
-  [K in keyof O]?: O[K]
-}
-/**
- * Interface for the configuration object that the hook receives 
- */
-export interface UseMagicSearchParamsOptions<
-  M extends Record<string, unknown>,
-  O extends Record<string, unknown>
-> {
-  mandatory: M 
-  optional?: O
-  defaultParams?: Partial<MergeParams<M, O>>
-  forceParams?: Partial<MergeParams<M, O>> // transform all to partial to avoid errors
-  arraySerialization?: 'csv' | 'repeat' | 'brackets' // technical to serialize arrays in the URL
-  omitParamsByValues?: Array<'all' | 'default' | 'unknown' | 'none' | 'void '> 
-}
-
-/** 
-Generic hook to handle search parameters in the URL
-@param mandatory - Mandatory parameters (e.g., page=1, page_size=10, etc.)
-@param optional - Optional parameters (e.g., order, search, etc.)
-@param defaultParams - Default parameters sent in the URL on initialization
-@param forceParams - Parameters forced into the URL regardless of user input
-@param omitParamsByValues - Parameters omitted if they have specific values 
-*/
-export const useMagicSearchParams = <
-  M extends Record<string, unknown> & CommonParams,
-  O extends Record<string, unknown>,
->({
-  mandatory = {} as M,
-  optional = {} as O,
-  defaultParams = {} as Partial<MergeParams<M, O>>,
-  arraySerialization = 'csv',
-  forceParams = {} as  {} as Partial<MergeParams<M, O>>,
-  omitParamsByValues = [] as Array<'all' | 'default' | 'unknown' | 'none' | 'void '>
-}: UseMagicSearchParamsOptions<M, O>)=> {
-
-  const [searchParams, setSearchParams] = useSearchParams() 
-    // Ref to store subscriptions: { paramName: [callback1, callback2, ...] }
-  const subscriptionsRef = useRef<Record<string, Array<() => unknown>>>({}); 
-  const previousParamsRef = useRef<Record<string, unknown>>({})
-
-  const TOTAL_PARAMS_PAGE: MergeParams<M, O> = useMemo(() => {
-    return { ...mandatory, ...optional };
-  }, [mandatory, optional]);
-
-  const PARAM_ORDER = useMemo(() => {
-    return Array.from(Object.keys(TOTAL_PARAMS_PAGE))
-  }, [TOTAL_PARAMS_PAGE])
-
-  // we get the keys that are arrays according to TOTAL_PARAMS_PAGE since these require special treatment in the URL due to serialization mode
-  const ARRAY_KEYS = useMemo(() => {
-    return Object.keys(TOTAL_PARAMS_PAGE).filter(
-      (key) => Array.isArray(TOTAL_PARAMS_PAGE[key])
-    );
-  }, [TOTAL_PARAMS_PAGE])
-
-  const appendArrayValues = (
-    finallyParams: Record<string, unknown>,
-    newParams: Record<string, string | string[] | unknown>
-  ): Record<string, unknown> => {
- 
-    // Note: We cannot modify the object of the final parameters directly, as immutability must be maintained
-    const updatedParams = { ...finallyParams };
-  
-    if (ARRAY_KEYS.length === 0) return updatedParams;
-  
-    ARRAY_KEYS.forEach((key) => {
-      // We use the current values directly from searchParams (source of truth)
-      // This avoids depending on finallyParams in which the arrays have been omitted
-      let currentValues = []; 
-      switch (arraySerialization) {
-        case 'csv': {
-          const raw = searchParams.get(key) || '';
-          // For csv we expect "value1,value2,..." (no prefix)
-          currentValues = raw.split(',')
-            .map((v) => v.trim())
-            .filter(Boolean) as Array<string>
-          break;
-        }
-        case 'repeat': {
-          // Here we get all ocurrences of key
-          const urlParams = searchParams.getAll(key) as Array<string>
-          currentValues = urlParams.length > 0 ? urlParams : []
-
-          break;
-        }
-        case 'brackets': {
-           // Build URLSearchParams from current parameters (to ensure no serialized values are taken previously)
-            const urlParams = searchParams.getAll(`${key}[]`) as Array<string>
-            currentValues = urlParams.length > 0 ? urlParams : []
-
-            break;
-        }
-        default: {
-          // Mode by default works as csv
-          const raw = searchParams.get(key) ?? '';
-          currentValues = raw.split(',')
-            .map((v) => v.trim())
-            .filter(Boolean);
-          }
-        break; 
-      }
-      // Update array values with new ones
-    
-      if (newParams[key] !== undefined) {
-        const incoming = newParams[key];
-        let combined: string[] = []
-        if (typeof incoming === 'string') {
-          // If it is a string, it is toggled (add/remove)
-          combined = currentValues.includes(incoming)
-            ? currentValues.filter((v) => v !== incoming)
-            : [...currentValues, incoming];
-        } else if (Array.isArray(incoming)) {
-          // if an array is passed, repeated values are merged into a single value
-          // Note: Set is used to remove duplicates
-          combined = Array.from(new Set([ ...incoming]));
-
-        } else {
-       
-          combined = currentValues;
-        }
-
-        updatedParams[key] = combined
-
-      }
-    });
-    return updatedParams
-  };
-
-  const transformParamsToURLSearch = (params: Record<string, unknown>): URLSearchParams => {
-    console.log({PARAMS_RECIBIDOS_TRANSFORM: params})
-
-    const newParam: URLSearchParams = new URLSearchParams()
-
-    const paramsKeys = Object.keys(params)
-
-    for (const key of paramsKeys) {
-      if (Array.isArray(TOTAL_PARAMS_PAGE[key])) {
-        const arrayValue = params[key] as unknown[]
-        console.log({arrayValue})
-        switch (arraySerialization) {
-          case 'csv': {
-            const csvValue = arrayValue.join(',')
-            // set ensure that the previous value is replaced
-            newParam.set(key, csvValue)
-            break
-          } case 'repeat': {
-      
-            for (const item of arrayValue) {
-
-              // add new value to the key, instead of replacing it
-              newParam.append(key, item as string)
-   
-            }
-            break
-          } case 'brackets': {
-            for (const item of arrayValue) {
-              newParam.append(`${key}[]`, item as string)
-            }
-            break
-          } default: {
-            const csvValue = arrayValue.join(',')
-            newParam.set(key, csvValue)
-          }
-        }
-      } else {
-        newParam.set(key, params[key] as string)
-      }
-    }
-    return newParam
-  }
-  // @ts-ignore
-  const hasForcedParamsValues = ({ paramsForced, compareParams }) => {
-
-    // Iterates over the forced parameters and verifies that they exist in the URL and match their values
-    // Ej: { page: 1, page_size: 10 } === { page: 1, page_size: 10 } => true
-    const allParamsMatch = Object.entries(paramsForced).every(
-      ([key, value]) => compareParams[key] === value
-    );
-
-    return allParamsMatch;
-  };
-  
-  useEffect(() => {
-
-    const keysDefaultParams: string[] = Object.keys(defaultParams)
-    const keysForceParams: string[] = Object.keys(forceParams)
-    if(keysDefaultParams.length === 0 && keysForceParams.length === 0) return
-  
-
-    function handleStartingParams() {
-
-      const defaultParamsString  = transformParamsToURLSearch(defaultParams).toString()
-      const paramsUrl = getParams()
-      const paramsUrlString = transformParamsToURLSearch(paramsUrl).toString()
-      const forceParamsString = transformParamsToURLSearch(forceParams).toString()
-
-      console.log({defaultParamsString})
-
-      const isForcedParams: boolean = hasForcedParamsValues({ paramsForced: forceParams, compareParams: paramsUrl })
-
-      if (!isForcedParams) {
-
-        // In this case, the forced parameters take precedence over the default parameters and the parameters of the current URL (which could have been modified by the user, e.g., page_size=1000)
-
-        updateParams({ newParams: {
-          ...defaultParams,
-          ...forceParams
-        }})
-        return
-      }
-      // In this way it will be validated that the forced parameters keys and values are in the current URL
-      const isIncludesForcedParams = hasForcedParamsValues({ paramsForced: forceParamsString, compareParams: defaultParams })
-
-      if (keysDefaultParams.length > 0 && isIncludesForcedParams) {
-        if (defaultParamsString === paramsUrlString) return // this means that the URL already has the default parameters
-        updateParams({ newParams: defaultParams })
-      }
-
-    }
-    handleStartingParams()
-
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
-
-  /**
-   * Convert a string value to its original type (number, boolean, array) according to TOTAL_PARAMS_PAGE
-   * @param value - Chain obtained from the URL
-   * @param key - Key of the parameter
-   */
-  const convertOriginalType = (value: string, key: string) => {
-    // Given that the parameters of a URL are recieved as strings, they are converted to their original type
-    if (typeof TOTAL_PARAMS_PAGE[key] === 'number') {
-      return parseInt(value)
-    } else if (typeof TOTAL_PARAMS_PAGE[key] === 'boolean') {
-      return value === 'true'
-    } else if (Array.isArray(TOTAL_PARAMS_PAGE[key])) {
-      // The result will be a valid array represented in the URL ej: tags=tag1,tag2,tag3 to ['tag1', 'tag2', 'tag3'], useful to combine the values of the arrays with the new ones
- 
-      if (arraySerialization === 'csv') {
-        return searchParams.getAll(key).join('').split(',')
-      } else if (arraySerialization === 'repeat') {
-    
-        console.log({SEARCH_PARAMS: searchParams.getAll(key)})
-        return searchParams.getAll(key)
-      } else if (arraySerialization === 'brackets') {
-        return searchParams.getAll(`${key}[]`)
-      }
-     
-     
-    }
-    // Note: dates are not converted as it is better to handle them directly in the component that receives them, using a library like < date-fns >
-    return value
-  }
-  
-    /**
-   * 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, ...)
-   */
-    const getStringUrl = (key: string, paramsUrl: Record<string, unknown>) => {
-      const isKeyArray = Array.isArray(TOTAL_PARAMS_PAGE[key])
-      if (isKeyArray) {
-
-        if (arraySerialization === 'brackets') {
-
-          const arrayUrl = searchParams.getAll(`${key}[]`)
-          const encodedQueryArray = transformParamsToURLSearch({ [key]: arrayUrl }).toString()
-          // in this way the array of the URL is decoded to its original form ej: tags[]=tag1&tags[]=tag2&tags[]=tag3
-          const unencodeQuery = decodeURIComponent(encodedQueryArray)
-          return unencodeQuery
-        } else if (arraySerialization === 'csv') {
-          const arrayValue = searchParams.getAll(key)
-          const encodedQueryArray = transformParamsToURLSearch({ [key]: arrayValue }).toString()
-          const unencodeQuery = decodeURIComponent(encodedQueryArray)
-          return unencodeQuery
-        }
-        const arrayValue = searchParams.getAll(key)
-        const stringResult = transformParamsToURLSearch({ [key]: arrayValue }).toString()
-        return stringResult
-      } else {
-   
-        return paramsUrl[key] as string
-      }
-     }
-     const getParamsObj = (searchParams: URLSearchParams): Record<string, string | string[]> => {
-      const paramsObj: Record<string, string | string[]> = {};
-      // @ts-ignore
-      for (const [key, value] of searchParams.entries()) {
-        if (key.endsWith('[]')) {
-          const bareKey = key.replace('[]', '');
-          if (paramsObj[bareKey]) {
-            (paramsObj[bareKey] as string[]).push(value);
-          } else {
-            paramsObj[bareKey] = [value];
-          }
-        } else {
-          // If the key already exists, it is a repeated parameter
-          if (paramsObj[key]) {
-            if (Array.isArray(paramsObj[key])) {
-              (paramsObj[key] as string[]).push(value);
-            } else {
-              paramsObj[key] = [paramsObj[key] as string, value];
-            }
-          } else {
-            paramsObj[key] = value;
-          }
-        }
-      }
-      return paramsObj;
-     }
-    // Optimization: While the parameters are not updated, the current parameters of the URL are not recalculated
-    const CURRENT_PARAMS_URL: Record<string, unknown> = useMemo(() => {
-
-      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
-     */
-    const getParams = ({ convert = true } = {}): MergeParams<M, O> => {
-      // All the paramteres are extracted from the URL and converted into an object
-
-      const params = Object.keys(CURRENT_PARAMS_URL).reduce((acc, key) => {
-        if (Object.prototype.hasOwnProperty.call(TOTAL_PARAMS_PAGE, key)) {
-          const realKey = arraySerialization === 'brackets' ? key.replace('[]', '') : key
-          // @ts-ignore
-          acc[realKey] = convert === true
-            ? convertOriginalType(CURRENT_PARAMS_URL[key] as string, key)
-            :  getStringUrl(key, CURRENT_PARAMS_URL)
-        }
-        return acc
-      }, {})
-  
-      return params as MergeParams<M, O>
-    }
-  type keys = keyof MergeParams<M, O>
-  // Note: in this way the return of the getParam function is typed dynamically, thus having autocomplete in the IDE (eg: value.split(','))
-  type TagReturn<T extends boolean> = T extends true ? string[] : string;
-  /**
-    * 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
-   */
-
-  const getParam = <T extends boolean>(key: keys, options?: { convert: T }): TagReturn<T>  => {
-
-    const keyStr = String(key)
-    // @ts-ignore
-    const value = options?.convert === true ? convertOriginalType(searchParams.get(keyStr), keyStr) : getStringUrl(keyStr,  CURRENT_PARAMS_URL)
-    return value as TagReturn<T> 
-  }
-  
-  type OptionalParamsFiltered = Partial<O>
-
-  const calculateOmittedParameters = (newParams: Record<string, unknown | unknown[]>, keepParams: Record<string, boolean>) => {
-    // Calculate the ommited parameters, that is, the parameters that have not been sent in the request
-    const params = getParams()
-    // hasOw
-    // Note: it will be necessary to omit the parameters that are arrays because the idea is not to replace them but to add or remove some values
-    const newParamsWithoutArray = Object.entries(newParams).filter(([key,]) => !Array.isArray(TOTAL_PARAMS_PAGE[key]))
-    const result = Object.assign({
-      ...params,
-      ...Object.fromEntries(newParamsWithoutArray),
-      ...forceParams // the forced parameters will always be sent and will maintain their value
-    })
-    const paramsFiltered: OptionalParamsFiltered = Object.keys(result).reduce((acc, key) => {
-      // for default no parameters are omitted unless specified in the keepParams object
-      if (Object.prototype.hasOwnProperty.call(keepParams, key) && keepParams[key] === false) {
-        return acc
-      // Note: They array of parameters omitted by values (e.g., ['all', 'default']) are omitted since they are usually a default value that is not desired to be sent
-      } else if (!!result[key] !== false && !omitParamsByValues.includes(result[key])) {
-        // @ts-ignore
-        acc[key] = result[key]
-      }
-
-      return acc
-    }, {})
-
-    return {
-      ...mandatory,
-      ...paramsFiltered
-    } 
-  }
-    // @ts-ignore
-  const sortParameters = (paramsFiltered) => {
-    // sort the parameters according to the structure so that it persists with each change in the URL, eg: localhost:3000/?page=1&page_size=10
-    // Note: this visibly improves the user experience
-    const orderedParams = PARAM_ORDER.reduce((acc, key) => {
-      if (Object.prototype.hasOwnProperty.call(paramsFiltered, key)) {
-          // @ts-ignore
-        acc[key] = paramsFiltered[key]
-      }
-
-      return acc
-    }, {})
-    return orderedParams
-  }
-
-  const mandatoryParameters = () => {
-    // Note: in case there are arrays in the URL, they are converted to their original form ej: tags=['tag1', 'tag2'] otherwise the parameters are extracted without converting to optimize performance
-    const isNecessaryConvert: boolean = ARRAY_KEYS.length > 0 ? true : false
-    const totalParametros: Record<string, unknown>  = getParams({ convert: isNecessaryConvert })
-
-    const paramsUrlFound: Record<string, boolean> = Object.keys(totalParametros).reduce(
-      (acc, key) => {
-        if (Object.prototype.hasOwnProperty.call(mandatory, key)) {
-          // @ts-ignore
-          acc[key] = totalParametros[key]
-        }
-        return acc
-      },
-      {}
-    )
-
-    return paramsUrlFound
-  }
-  /**
-   clears the parameters of the URL, keeping the mandatory parameters
-   * @param keepMandatoryParams - If true, the mandatory parameters are kept in the URL
-   */
-
-  const clearParams = ({ keepMandatoryParams = true } = {}): void => {
-    // for default, the mandatory parameters are not cleared since the current pagination would be lost
-    const paramsTransformed = transformParamsToURLSearch(
-      {
-        ...mandatory,
-     
-         ...(keepMandatoryParams && {
-          ...mandatoryParameters()
-        }),
-        ...forceParams 
-      }
-    )
-    setSearchParams(paramsTransformed) 
-  }
-
-  // transforms the keys to boolean to know which parameters to keep
-  type KeepParamsTransformedValuesBoolean = Partial<Record<keyof typeof TOTAL_PARAMS_PAGE, boolean>>
-  type NewParams = Partial<typeof TOTAL_PARAMS_PAGE> 
-  type KeepParams = KeepParamsTransformedValuesBoolean
-  /**
-   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
-   */
-  const updateParams = ({ newParams = {} as NewParams, keepParams = {} as KeepParams } = {}) => {
-
-    if (
-      Object.keys(newParams).length === 0 &&
-      Object.keys(keepParams).length === 0
-    ) {
-      clearParams()
-      return
-    }
-    // @ts-ignore
-    const finallyParamters = calculateOmittedParameters(newParams, keepParams)
-
-    const convertedArrayValues = appendArrayValues(finallyParamters, newParams)
-
-    const paramsSorted = sortParameters(convertedArrayValues)
-
-    setSearchParams(transformParamsToURLSearch(paramsSorted))
-
-  }
-
-  /**
-   * @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
-   */
-    const onChange = useCallback( (paramName: keys, callbacks: Array<() => void>) => {
-      const paramNameStr = String(paramName)
-      // replace the previous callbacks with the new ones so as not to accumulate callbacks
-      subscriptionsRef.current[paramNameStr] = callbacks;
-    }, [])
-  
-    // each time searchParams changes, we notify the subscribers
-    useEffect(() => {
-
-      for (const [key, value] of Object.entries(subscriptionsRef.current)) {
-
-        const newValue = CURRENT_PARAMS_URL[key] ?? null 
-        const oldValue = previousParamsRef.current[key] ?? null
-        if (newValue !== oldValue) {
-          
-          for (const callback of value) {
-            callback()
-
-          }
-        }
-        // once the callback is executed, the previous value is updated to ensure that the next time the value changes, the callback is executed
-        previousParamsRef.current[key] = newValue
-      }
-
-    }, [CURRENT_PARAMS_URL])
-  return {
-    searchParams,
-    updateParams,
-    clearParams,
-    getParams,
-    getParam,
-    onChange
-  }
-}
-