A lightweight, framework-agnostic package designed to help manage query parameters for filters, pagination, and other browser state data.
npm install @smart-gate/query-paramsA lightweight, framework-agnostic package designed to help manage query parameters for filters, pagination, and other
browser state data. Seamlessly preserve complex data structures in your browser's path queries, enhancing user
experience (UX) by maintaining their preferences even as they navigate back and forth.
Managing query parameters can be challenging, especially with complex data structures. @smart-gate/query-params
simplifies this process with an easy-to-use API that works across frameworks. It offers a structured way to persist user
preferences and selections in the browser, providing a smoother user experience.
- Simplifies Query Management: Handle even the most complex data structures effortlessly.
- Framework-Agnostic: Compatible with any JavaScript framework or library.
- Enhances User Experience: Preserves user preferences and inputs.
Install the package via npm:
``sh`
npm install @smart-gate/query-params
With @smart-gate/query-params, transforming and managing complex objects in the browser's query string issetQueryParams(objectToPreserve)
straightforward. The function enables easy setup.
Example Input Object:
`js`
const userPreferences = {
name: 'John',
age: 17,
alive: true,
location: {
planet: 'Earth'
},
hobbies: ['football', 'swimming', 'sky-diving', ['soccer'], { canWork: false, prefersToDie: true }],
emotions: [
{ state: 'anger', cause: 'threat' },
{ state: 'disgust', cause: 'life' }
]
};
Transformed Query Object:
`js`
const queryParams = {
name: 'John',
'age()': 17,
'alive!!': true,
'location.planet': 'Earth',
'hobbies[0]': 'football',
'hobbies[1]': 'swimming',
'hobbies[2]': 'sky-diving',
'hobbies[3][0]': 'soccer',
'hobbies[4].canWork!!': false,
'hobbies[4].prefersToDie!!': true,
'emotions[0].state': 'anger',
'emotions[0].cause': 'threat',
'emotions[1].state': 'disgust',
'emotions[1].cause': 'life'
};
Using this structure, you can save complex objects to the browser’s query string without limitations and retrieve the
original object with getQueryParams().
@smart-gate/query-params is versatile and works with any framework. Here’s an example of how to use it in a Vue.js
component.
Below is a Vue.js component that demonstrates how to use @smart-gate/query-params to manage filter data in the
browser's query string.
` Filter Informationvue
`
or you can simply use setQueryParamsByKey and getQueryParamsByKey function to update individual properties.
@smart-gate/query-params provides a set of utility functions to serialize and deserialize complex objects for use in query parameters. Below are the core functions available in this package:
- Description: Retrieves all query parameters from the current URL as a deserialized object. This is useful when you need to load stored user preferences or filter criteria on page load.
- Returns: {object} - An object representing the URL's query parameters, with nested structures restored if applicable.
Example:
`js`
const params = getQueryParams();
console.log(params);
// Output: { name: 'John', age: 17, location: { planet: 'Earth' }, ... }
- Description: Serializes an object and updates the browser's URL with the resulting query string. This allows you to save complex data in the URL for persistence.
- Parameters: data - {object} The object to be serialized and added to the query parameters.void
- Returns:
Example:
`js`
const userPreferences = { name: 'John', age: 17, location: { planet: 'Earth' } };
setQueryParams(userPreferences);
// URL is updated with ?name=John&age=17&location.planet=Earth
- Description: Retrieves a single query parameter value based on a provided key. If the key refers to a nested structure, this function will locate and return the specific nested value.
- Parameters: property - {string} The name of the query parameter to retrieve.unknown
- Returns: - The value associated with the specified query parameter.
Example:
`js`
const age = getQueryParamsByKey('age');
console.log(age);
// Output: 17
- Description: Updates a specific query parameter in the current URL without affecting others. Useful for updating a single property in the query string.
- Parameters:
- key - {string} The name of the query parameter to set.value
- - {unknown} The value to associate with the key.void
- Returns:
Example:
`js`
setQueryParamsByKey('hobbies[0]', 'football');
// URL is updated with ?hobbies[0]=football
- ### removeQueryParams()
- Description: Clears all queries parameter in the current URL. Useful for resetting your filter or pagination etc.
- Returns: void
Example:
`js`
setQueryParamsByKey('hobbies[0]', 'football');
// URL is updated with ?hobbies[0]=football
- Description: Converts a nested object into a flat object with keys representing the path to each value, suitable for use as query parameters.
- Parameters: deserialized - {object} The nested object to serialize.{object}
- Returns: - The flattened object with path-based keys.
Example:
`js`
const data = { user: { name: 'Alice', age: 30 } };
const serialized = serializeObjectKey(data);
console.log(serialized);
// Output: { 'user.name': 'Alice', 'user.age': 30 }
- Description: Reconstructs a flat object with path-based keys into a nested object.
- Parameters: serialized - {object} The flattened object to unserialize.{object}
- Returns: - The nested object.
Example:
`js``
const serialized = { 'user.name': 'Alice', 'user.age': 30 };
const data = deserializeObjectKey(serialized);
console.log(data);
// Output: { user: { name: 'Alice', age: 30 } }