Params Wizard

A powerful and type-safe utility package for managing URL query parameters in browser applications.

Features

- 🔒 Type-safe parameter handling
- 🔄 URL history management
- 🎯 Parameter validation
- 📦 Transaction support
- 🔌 Middleware system
- 💾 Preset management
- 📝 Complex object serialization
- 🎨 Array parameter support
- 👀 URL change subscriptions

API Reference

| Function/Class | Parameters | Options/Types | Return Value | Description |
| ---------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------------------------- |
| updateQuery | { 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 |

$3

#### URLTransaction

| Method | Parameters | Return | Description |
| ---------- | -------------------------- | ------ | ------------------------- |
| 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 |

#### URLHistory

The URLHistory class implements a singleton pattern to manage browser history consistently.

| Method | Parameters | Return | Description |
| ------------- | ---------------------------------------------- | ------------ | -------------------------- |
| 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 | () => 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, next: () => void) => void | 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`

License

MIT