typed-url-search-params

Zero-dependency | Type-safe | Modular

typed-url-search-params is a lightweight TypeScript library for explicitly declaring and managing URL search parameters. It enables you to split responsibility across different parts of your application by creating multiple instances with their own parameter schemas, ensuring every URL parameter is documented and handled in a type-safe way.

Motivation

In large projects, URL search parameters can be used in an ad-hoc manner, leading to:

• Undocumented usage: Parameters appear and disappear with no central declaration.
• Unexpected behaviors: Implicit parameter handling can cause bugs and maintenance challenges.
• Poor developer experience: Lack of type hints and auto-completion increases the chance of mistakes.

This library solves these issues by enforcing explicit declaration of each supported parameter. With typed-url-search-params, you:

• Document your URL parameters: Every parameter is declared in a schema.
• Maintain separation of concerns: Create dedicated instances for different modules.
• Achieve full type-safety: Enjoy IDE autocompletion and compile-time checks.

Features

• Zero-dependency: No additional packages needed.
• Type-safe: Leverages TypeScript generics for precise parameter types.
• Modular: Multiple instances with separate schemas let different parts of your app manage their own parameters.
• Explicit: Every supported URL parameter is declared explicitly in a schema.

Installation

Install via npm:

1npm install typed-url-search-params

or

1yarn add typed-url-search-params

Usage

A very basic usage example:

1import { TypedURLSearchParams, paramNumber, paramString, withDefault } from 'typed-url-search-params';
2
3// Create an instance with an inlined schema
4const params = new TypedURLSearchParams({
5  page: paramNumber,
6  search: paramString,
7  score: withDefault(paramNumber, 0)
8});
9
10// Retrieve parameters with full type safety and proper defaulting
11const page = params.get("page");    // number | null
12const search = params.get("search"); // string | null
13const score = params.get("score");   // number (0 if not provided)

In the example above we create a new instance of TypedURLSearchParams with a schema that defines three parameters:

• page: A number parameter.
• search: A string parameter.
• score: A number parameter with a default value of 0.

By default, if the parameter is not present in the URL, the value will be null. If you want to provide a default value, you can use the withDefault helper function.

Then we retrieve the parameters using the get method, which returns the parameter value with the correct type. Parameter names are type-checked, so you'll get autocompletion and type hints in your IDE.

You can define any parts of the schema separately, which is a bit more explicit:

1// Define a custom parameter
2const paramScore = withDefault(paramNumber, 0);
3
4// Define a schema for a specific module or section of your app
5const myParamsSchema = {
6  page: paramNumber,    // Returns number | null
7  search: paramString,  // Returns string | null
8  score: paramScore,    // Returns number, defaulting to 0 if absent
9};
10
11// Create an instance using the schema
12const params = new TypedURLSearchParams(myParamsSchema);
13
14// Retrieve parameters with full type safety and proper defaulting
15const page = params.get("page");    // number | null
16const search = params.get("search"); // string | null
17const score = params.get("score");   // number (0 if not provided)

Flexibility showcase

You can define your own custom parameter types and reuse them across different schemas:

1
2// Positive number parameter
3const paramPositiveNumber: ParamDefinition<number> = {
4  parse: (value: string | null) => {
5    const parsed = paramNumber.parse(value);
6    return parsed !== null && parsed > 0 ? parsed : null;
7  },
8}
9
10// Positive number with 0 as default
11const paramPositiveNumberOrZero = withDefault(paramPositiveNumber, 0) 
12
13// String processing example
14const paramStringUpperCase: ParamDefinition<string> = {
15  parse: value => value ? value.toUpperCase() : null,
16};
17
18// One more string processing example
19const paramStringLowerCase: ParamDefinition<string> = {
20  parse: value => value ? value.toLowerCase() : null,
21};
22
23const query = "?score=10&page=2&search=Hello&filter=Foo";
24
25// Now use these custom parameters
26const params = new TypedURLSearchParams({
27  score: paramPositiveNumber,
28  page: paramPositiveNumberOrZero,
29  search: paramStringUpperCase,
30  filter: paramStringLowerCase,
31}, query);
32
33const score = params.get("score");    // 10
34const page = params.get("page");      // 2
35const search = params.get("search");  // HELLO (uppered case)
36const filter = params.get("filter");  // foo (lowered case)
37
38const anotherQuery = = "?score=-15;
39
40// Update the query
41params.updateQuery(anotherQuery);
42
43// Try get same values again
44const score = params.get("score");    // null (-15 is not a positive number)
45const page = params.get("page");      // 0 (value is not present, default is used)
46const search = params.get("search");  // null
47const filter = params.get("filter");  // null
48
49// Expanding an existing schema
50const anotherSchema = {
51  ...myParamsSchema,
52    anotherParam: paramPositiveNumber,
53    someBoolean: paramBoolean,
54}
55

API Reference

TypedURLSearchParams<Schema>

A class to manage URL search parameters based on a provided schema.

Constructor

1new TypedURLSearchParams(schema: Schema, query?: string)

schema: Schema

• Type: An object mapping parameter names (keys) to their definitions (ParamDefinition<T>).

• Description:
  This object defines which URL parameters are supported, how they are parsed, and how they are serialized. Each parameter definition includes:

  • A parse function: Converts the raw string value from the URL into a typed value.
  • An optional defaultValue: Used when the parameter is missing in the URL.

  Example:

  const myParamsSchema = {
    page: paramNumber,                  // Parses to number or null
    search: paramString,                // Parses to string or null
    score: withDefault(paramNumber, 0)  // Parses to number, defaults to 0 if absent
  };
  

query?: string

• Type: string (optional)

• Description:
  A query string representing the URL parameters (e.g., "?page=1&search=hello"). If provided, the TypedURLSearchParams instance will parse this string according to the given schema. If omitted, the library automatically uses window.location.search (if available), simplifying usage in browser environments. This means you can instantiate the class as follows:

  const params = new TypedURLSearchParams(myParamsSchema);
  

  and it will automatically parse the parameters from the current page's URL.

  Or with a custom query string:

  const params = new TypedURLSearchParams(myParamsSchema, myQueryString);
  

Contributing

Coming soon

License

Distributed under the MIT License. See LICENSE for more information.