// src/hooks/useSearchParam.ts
import { useRouter } from 'next/router';
import { useCallback } from 'react';

/**
 * Custom hook to safely access, update, or remove a single URL search parameter
 * in Next.js Pages Router applications.
 * 
 * Features:
 * - SSR-safe (returns undefined during server render)
 * - Preserves all other query parameters
 * - Shallow routing (no page reload/data refetch)
 * - Type-safe value handling
 * - Prevents unnecessary history entries
 * 
 * @param param - Name of the query parameter to manage
 * @returns [
 *   currentValue: string | string[] | undefined,
 *   { 
 *     update: (newValue: string | string[] | null | undefined) => void,
 *     remove: () => void 
 *   }
 * ]
 * 
 * @example
 * // Read value
 * const [success] = useSearchParam('success');
 * 
 * @example
 * // Update value
 * const [, { update }] = useSearchParam('theme');
 * update('dark');
 * 
 * @example
 * // Remove parameter
 * const [, { remove }] = useSearchParam('success');
 * remove();
 */
export function useSearchParam(param: string): [
    string | string[] | undefined,
    {
        update: (newValue: string | string[] | null | undefined) => void;
        remove: () => void;
    }
] {
    const router = useRouter();

    // Get current value (SSR-safe)
    const currentValue = router.query[param];

    // Update parameter value while preserving other params
    const updateParam = useCallback(
        (newValue: string | string[] | null | undefined) => {
            // Skip if router isn't ready or value hasn't changed
            if (!router.isReady) return;

            const currentQuery = { ...router.query };

            if (newValue == null || newValue === '') {
                delete currentQuery[param];
            } else {
                currentQuery[param] = newValue;
            }

            router.replace(
                {
                    pathname: router.pathname,
                    query: currentQuery,
                },
                undefined,
                { shallow: true, scroll: false }
            );
        },
        [router, param]
    );

    // Remove parameter helper
    const removeParam = useCallback(() => {
        updateParam(null);
    }, [updateParam]);

    return [
        currentValue,
        {
            update: updateParam,
            remove: removeParam,
        },
    ];
}