🔍 filters-query-params

Type-safe URL query parameter management for React, Next.js, and vanilla TypeScript with Zod validation.

✨ Features

• 🛡️ Type-safe with Zod schema validation
• 🔄 Smart type coercion (string → number/boolean/date)
• 🧹 Data cleaning (drop empty values, trim strings, strip unknown keys)
• 📦 Multiple array formats (repeat, comma, JSON)
• 📅 Date handling with ISO encoding/decoding
• ⚡ Debouncing with 300ms default delay
• ⚛️ React hooks for Next.js (App/Pages Router) and React Router
• 🚀 SSR-ready with server-side helpers
• 📝 ESM + CJS with full TypeScript definitions

📦 Installation

npm install filters-query-params zod

🚀 Quick Start

1. Define Your Schema

import { z } from "zod";

const filtersSchema = z.object({
  search: z.string().optional(),
  category: z.string().optional(),
  priceMin: z.number().int().min(0).optional(),
  priceMax: z.number().int().min(0).optional(),
  inStock: z.boolean().optional(),
  tags: z.array(z.string()).optional(),
  createdAfter: z.date().optional(),
});

2. Core Usage

Parse Query Strings

import { parseQuery } from "filters-query-params";

const filters = parseQuery(filtersSchema, "?search=laptop&priceMin=100", {
  coerceTypes: true, // Convert strings to proper types
  dropEmpty: true, // Remove empty values
  arrayFormat: "repeat", // Handle ?tags=a&tags=b
});
// Result: { search: "laptop", priceMin: 100 }

Build URLs

import { buildUrl, buildQuery } from "filters-query-params";

const url = buildUrl(
  "/products",
  filtersSchema,
  {
    search: "laptop",
    tags: ["gaming", "portable"],
  },
  { arrayFormat: "repeat" }
);
// Result: "/products?search=laptop&tags=gaming&tags=portable"

const queryParams = buildQuery(filtersSchema, { search: "laptop" });
// Result: URLSearchParams object

3. React Hooks

Next.js App Router

"use client";
import { useNextAppFilters } from "filters-query-params";

export default function ProductsPage() {
  const { filters, setFilters, reset, isLoading } =
    useNextAppFilters(filtersSchema);

  return (
    <div>
      <input
        value={filters.search || ""}
        onChange={(e) => setFilters({ search: e.target.value })}
        placeholder="Search..."
      />
      <button onClick={() => setFilters({ inStock: true })}>
        In Stock Only
      </button>
      <button onClick={() => reset()}>Clear All</button>
    </div>
  );
}

Next.js Pages Router

import { useNextPagesFilters } from "filters-query-params";

export default function ProductsPage() {
  const { filters, setFilters, reset } = useNextPagesFilters(filtersSchema);
  // Same usage as App Router
}

React Router

import { useReactRouterFilters } from "filters-query-params";

export function ProductsPage() {
  const { filters, setFilters, reset } = useReactRouterFilters(filtersSchema);
  // Same usage as Next.js
}

4. Utility Functions

import { cleanObject, mergeFilters, resetFilters } from "filters-query-params";

// Clean data
const clean = cleanObject(
  { name: " John ", age: "", active: true },
  { trimStrings: true, dropEmpty: true }
);
// Result: { name: "John", active: true }

// Merge filters
const merged = mergeFilters({ search: "old" }, { category: "new" });
// Result: { search: "old", category: "new" }

// Reset to defaults
const reset = resetFilters(filtersSchema, { category: "electronics" });
// Result: { category: "electronics" }

5. Server-Side Rendering

import { getFiltersFromUrl, getFiltersFromSearch } from "filters-query-params";

// From full URL
const filters = getFiltersFromUrl(filtersSchema, req.url, {
  coerceTypes: true,
});

// From search params only
const filters2 = getFiltersFromSearch(filtersSchema, "?search=laptop&page=1");

📖 API Reference

Core Functions

| Function | Purpose | Example | | ---------------------------------------------- | ---------------------------------- | -------------------------------------- | | parseQuery(schema, input, options?) | Parse query string to typed object | parseQuery(schema, "?q=test") | | buildQuery(schema, filters, options?) | Build URLSearchParams from object | buildQuery(schema, { q: "test" }) | | buildUrl(baseUrl, schema, filters, options?) | Build complete URL with params | buildUrl("/search", schema, filters) | | cleanObject(obj, options?) | Clean object (trim, drop empty) | cleanObject({ name: " John " }) | | mergeFilters(current, next, options?) | Merge filter objects | mergeFilters(old, new) | | resetFilters(schema, defaults?) | Reset to default values | resetFilters(schema, { page: 1 }) |

React Hooks

| Hook | Framework | Purpose | | ----------------------------------------- | -------------------- | ---------------------------- | | useNextAppFilters(schema, options?) | Next.js App Router | Manage filters with URL sync | | useNextPagesFilters(schema, options?) | Next.js Pages Router | Manage filters with URL sync | | useReactRouterFilters(schema, options?) | React Router | Manage filters with URL sync |

Debouncing Functions

| Function | Purpose | Example | | ------------------------------------------- | ------------------------ | ----------------------------------- | | debounce(fn, delay?) | Debounce any function | debounce(searchFn, 300) | | createDebouncedParseQuery(schema, delay?) | Debounced query parsing | createDebouncedParseQuery(schema) | | createDebouncedBuildUrl(schema, delay?) | Debounced URL building | createDebouncedBuildUrl(schema) | | createDebouncedBuildQuery(schema, delay?) | Debounced query building | createDebouncedBuildQuery(schema) |

SSR Helpers

| Function | Purpose | Example | | ------------------------------------------------ | ---------------------------------- | ----------------------------------------- | | getFiltersFromUrl(schema, url, options?) | Extract filters from full URL | getFiltersFromUrl(schema, req.url) | | getFiltersFromSearch(schema, search, options?) | Extract filters from search params | getFiltersFromSearch(schema, "?q=test") |

⚙️ Configuration

Array Formats

| Format | URL Example | Use Case | | ---------- | ----------------- | ------------------------ | | "repeat" | ?tags=a&tags=b | Most compatible, default | | "comma" | ?tags=a,b | Shorter URLs | | "json" | ?tags=["a","b"] | Complex data structures |

Options

ParseOptions & BuildOptions

{
  stripUnknown?: boolean;     // Remove unknown keys
  trimStrings?: boolean;      // Trim whitespace
  dropEmpty?: boolean;        // Remove empty values
  coerceTypes?: boolean;      // Convert string types (parse only)
  arrayFormat?: ArrayFormat;  // Array serialization format
  arrayKeyFormat?: Record<string, ArrayFormat>; // Per-key formats
  encodeDate?: boolean;       // Encode dates as ISO strings (build only)
}

� Advanced Usage

Debouncing

import { debounce, createDebouncedParseQuery } from "filters-query-params";

// Debounce any function
const debouncedSearch = debounce(async (query: string) => {
  return fetch(`/api/search?q=${query}`);
}, 300);

// Debounced query parsing
const debouncedParseQuery = createDebouncedParseQuery(filtersSchema, 300);
debouncedParseQuery("?search=laptop");
debouncedParseQuery("?search=macbook"); // Only this executes after 300ms

// Cancel or flush immediately
debouncedParseQuery.cancel();
const immediate = debouncedParseQuery.flush("?search=immediate");

Date Handling

const url = buildUrl(
  "/events",
  schema,
  {
    startDate: new Date("2024-01-01"),
    endDate: new Date("2024-12-31"),
  },
  { encodeDate: true }
);

// Parses dates back from ISO strings
const filters = parseQuery(schema, url, { coerceTypes: true });
console.log(filters.startDate instanceof Date); // true

Data Cleaning

const filters = parseQuery(schema, "?search=  hello  &category=&priceMin=0", {
  trimStrings: true, // "  hello  " → "hello"
  dropEmpty: true, // Remove category=""
  coerceTypes: true, // "0" → 0
});
// Result: { search: "hello", priceMin: 0 }

Mixed Array Formats

const { filters } = useNextAppFilters(schema, {
  build: {
    arrayFormat: "repeat", // default for most arrays
    arrayKeyFormat: {
      tags: "comma", // use comma for tags specifically
      categories: "json", // use JSON for categories
    },
  },
});

� Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE for details.

Copyright © 2025 Nauman Majeed