params-wizard v1.0.2

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

Classes

URLTransaction

URLHistory

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

// 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

URLPresets

URLMiddlewareManager

Installation

npm install params-wizard

API Usage & Explanations

Basic Query Operations

URL query parameters are the parts of a URL after the ? symbol. These operations help you manage these parameters programmatically.

// 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");

Parameter Retrieval & Type Safety

Built-in TypeScript support ensures you get the correct data types when retrieving parameters.

// 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<number>("page", 1); // returns number: 1
const isActive = getTypedParam<boolean>("active", false); // returns boolean: true/false

Array Parameter Handling

Work with arrays in URL parameters seamlessly, with automatic encoding and decoding.

// Set array parameters
updateQueryArray("tags", ["react", "typescript"]);
// Results in: ?tags=react,typescript

// Get array parameters
const tags = getParamArray("tags"); // ["react", "typescript"]

Transaction Pattern

Batch multiple URL changes together to avoid multiple history entries and improve performance.

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

URL History Management

Manage browser history through a singleton instance that ensures consistent history management across your application.

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

Change Subscriptions

Listen for URL parameter changes anywhere in your application to sync UI or trigger side effects.

// 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();

Middleware System

Transform or validate URL parameters before they're applied. Useful for data normalization and validation.

// 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();
});

Parameter Presets

Save and reuse common parameter combinations. Perfect for storing filter configurations or common searches.

// 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

Complex Object Serialization

Store and retrieve complex objects in URL parameters with type safety.

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<typeof filters>(
  getTypedParam("filters", "")
);

Parameter Validation

Validate URL parameters against defined rules to ensure data integrity.

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:

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<typeof initialFilters>) => {
    new URLTransaction()
      .updates(
        Object.entries(newFilters).map(([key, value]) => ({
          key,
          value: value ?? null,
        }))
      )
      .commit();
  };

  return (
    <div>
      <input
        value={initialFilters.search}
        onChange={(e) => updateFilters({ search: e.target.value })}
      />
      {/* ...other filter controls */}
    </div>
  );
};

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