A utility package for handling URL query parameters in the browser
npm install params-wizardupdateQuery | { key: string, value: QueryValue } | QueryValue = string \| number \| boolean \| null \| undefined \| string[] | void | Updates single URL parameter |
updateQueries | QueryUpdate[] | Same as updateQuery | void | Batch update multiple parameters |
updateQueryString | query: string | Query string format | void | Updates from raw query string |
getParams | None | - | Record | Get all parameters as object |
getParamString | None | - | string | Get full query string |
getTypedParam | key: string, defaultValue: T | T = string \| number \| boolean | T | Get typed parameter value |
updateQueryArray | key: string, values: string[] | - | void | Set array parameter |
getParamArray | key: string | - | string[] | Get array parameter |
clearQuery | keys: string \| string[] | - | void | Clear specific parameter(s) |
clearAllQuery | None | - | void | Clear all parameters |
validateParams | params: Record, rules: ValidationRules | ValidationRules = { pattern?: RegExp; minLength?: number; maxLength?: number; required?: boolean; enum?: string[]; } | boolean | Validate parameters |
serializeObject | obj: Record | - | string | Serialize complex object |
deserializeObject | str: string | Type parameter T | T | Deserialize with type safety |
getParam | key: string | - | string \| null | Get raw parameter value |
update | QueryUpdate | this | Update single parameter |
updates | QueryUpdate[] | this | Batch update parameters |
delete | key: string | this | Delete parameter |
clear | keys: string \| string[] | this | Clear multiple parameters |
clearAll | None | this | Clear all parameters |
commit | None | void | Apply changes |
constructor | None | URLHistory | Returns singleton instance |
push | { data?: any, title?: string, url?: string } | void | Push new state to history |
back | None | void | Go to previous state |
forward | None | void | Go to next state |
typescript
// Example usage
const history = new URLHistory(); // Always returns the same instance
history.push({
data: { view: "list" }, // Custom state data
title: "List View", // Optional page title
url: window.location.href, // Optional URL
});
`
#### URLSubscriber
| Method | Parameters | Return | Description |
| ----------- | ------------------------------------------ | ------------ | ------------------------ |
| subscribe | (params: Record | () => void | Subscribe to URL changes |
#### URLPresets
| Method | Parameters | Return | Description |
| -------- | ---------------------------------------------- | ------ | --------------------- |
| save | name: string, params: Record | void | Save parameter preset |
| apply | name: string | void | Apply saved preset |
| remove | name: string | void | Remove preset |
#### URLMiddlewareManager
| Method | Parameters | Return | Description |
| ------ | ------------------------------------------------------------ | ------ | ----------------------- |
| use | (params: Record | void | Add middleware function |
Installation
`bash
npm install params-wizard
`
API Usage & Explanations
$3
URL query parameters are the parts of a URL after the ? symbol. These operations help you manage these parameters programmatically.
`typescript
// Single parameter update
updateQuery({ key: "page", value: 2 }); // ?page=2
updateQuery({ key: "page", value: null }); // removes page parameter
// Multiple parameter update
updateQueries([
{ key: "page", value: 1 },
{ key: "sort", value: "desc" },
]); // Results in: ?page=1&sort=desc
// Update from query string
updateQueryString("?page=1&sort=desc");
`
$3
Built-in TypeScript support ensures you get the correct data types when retrieving parameters.
`typescript
// Get raw parameter value
getParam("page"); // returns "1" or null
// Get all parameters as object
getParams(); // { page: "1", sort: "desc" }
// Get full query string
getParamString(); // "page=1&sort=desc"
// Get typed parameters (with automatic type conversion)
const page = getTypedParam("page", 1); // returns number: 1
const isActive = getTypedParam("active", false); // returns boolean: true/false
`
$3
Work with arrays in URL parameters seamlessly, with automatic encoding and decoding.
`typescript
// Set array parameters
updateQueryArray("tags", ["react", "typescript"]);
// Results in: ?tags=react,typescript
// Get array parameters
const tags = getParamArray("tags"); // ["react", "typescript"]
`
$3
Batch multiple URL changes together to avoid multiple history entries and improve performance.
`typescript
new URLTransaction()
.update({ key: "page", value: 2 })
.updates([
// bulk updates
{ key: "sort", value: "desc" },
{ key: "filter", value: "active" },
])
.delete("category") // single delete
.clear(["tag", "search"]) // multiple delete
.clearAll() // clear all
.commit(); // apply all changes at once
`
$3
Manage browser history through a singleton instance that ensures consistent history management across your application.
`typescript
const history = new URLHistory(); // Always returns the same instance
// Save state with custom data
history.push({
data: { view: "list" }, // Custom state data
title: "List View", // Optional page title
url: window.location.href, // Optional URL
});
history.back(); // Go to previous state
history.forward(); // Go to next state
`
$3
Listen for URL parameter changes anywhere in your application to sync UI or trigger side effects.
`typescript
// Set up a listener
const unsubscribe = URLSubscriber.subscribe((params) => {
console.log("URL parameters changed to:", params);
// Update UI, trigger API calls, etc.
});
// Clean up when done
unsubscribe();
`
$3
Transform or validate URL parameters before they're applied. Useful for data normalization and validation.
`typescript
// Ensure page number is always positive
URLMiddlewareManager.use((params, next) => {
if (params.page) {
params.page = Math.max(1, parseInt(params.page));
}
next();
});
// Log all URL changes
URLMiddlewareManager.use((params, next) => {
console.log("URL changing to:", params);
next();
});
`
$3
Save and reuse common parameter combinations. Perfect for storing filter configurations or common searches.
`typescript
// Save a common filter configuration
URLPresets.save("activeUsers", {
status: "active",
role: "user",
sort: "newest",
});
// Apply the entire configuration at once
URLPresets.apply("activeUsers");
// Results in: ?status=active&role=user&sort=newest
URLPresets.remove("activeUsers"); // Clean up when done
`
$3
Store and retrieve complex objects in URL parameters with type safety.
`typescript
const filters = {
date: { from: "2023-01-01", to: "2023-12-31" },
categories: ["A", "B", "C"],
active: true,
};
// Save complex object in URL
updateQuery({
key: "filters",
value: serializeObject(filters),
});
// Retrieve and restore object with type safety
const savedFilters = deserializeObject(
getTypedParam("filters", "")
);
`
$3
Validate URL parameters against defined rules to ensure data integrity.
`typescript
const rules = {
username: {
pattern: /^[a-z0-9]+$/i, // Must match pattern
minLength: 3, // Minimum length
maxLength: 20, // Maximum length
required: true, // Must be present
},
role: {
enum: ["admin", "user"], // Must be one of these values
},
};
validateParams(
{
username: "john_doe",
role: "admin",
},
rules
);
`
Real World Example
Here's a practical example of using the URL Parser in a React product listing page:
`typescript
import { updateQueries, getTypedParam, URLTransaction } from "query-nexus";
const ProductListing: React.FC = () => {
// Get initial filters from URL
const initialFilters = {
search: getTypedParam("search", ""),
minPrice: getTypedParam("minPrice", 0),
categories: getParamArray("categories"),
page: getTypedParam("page", 1),
};
// Update URL when filters change
const updateFilters = (newFilters: Partial) => {
new URLTransaction()
.updates(
Object.entries(newFilters).map(([key, value]) => ({
key,
value: value ?? null,
}))
)
.commit();
};
return (
value={initialFilters.search}
onChange={(e) => updateFilters({ search: e.target.value })}
/>
{/ ...other filter controls /}
);
};
`
See the complete example with all features in /examples/ProductListingExample.tsx.
Browser Compatibility
Works in all modern browsers that support:
- URLSearchParams
- window.history
- pushState`