Add queryParamsStore

[techniq]

• Support simple types (numbers, strings, booleans)
• Support objects
• Support arrays
  • Return array even if single item
  • Arrays of simple types
  • Arrays of objects
• Handle datatype changing when only a single vs multiple selected (ex. select with a single vs multiple values)
• Provide better errors when config not found (at least include param name)
• Support updating single param with queryParamsStore
  • Either support property and only update those with keys passed (require null / undefined to remove) or expose function from store to set
• Support specifying pushState (browser back) vs replaceState
• Attempt to guess paramType based on default value and/or current params set?
  • Might be confusing when breaks in certain conditions
• Consider supporting Number and [Number] along with 'number' and 'number[]' (etc)?
  • Support both formats?
  • What about json (JSON), object (Object)?
  • What about date vs datetime?
    • Maybe Date is bound to datetime and date is handled by passing in an implementation object with encode/decode (see below)
  • Support a custom format in the future (UTC date vs local date, etc)
    • Maybe passing in an implementation object with encode/decode (see below)
• Consider supporting explicit object with {encode: ..., decode: ....}?
• Differentiate between null and undefined
  • Should only undefined delete the value (null is persisted)? Example: active/inactive/all toggles

Useful links

• https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
• Svelte
  • https://stackoverflow.com/questions/57181704/svelte-components-store-load-state-into-from-url-hash-parameters
• React
  • https://github.com/pbeshai/use-query-params
    • https://github.com/pbeshai/serialize-query-params
  • https://github.com/rudyhuynh/use-url-search-params
  • Using React Hooks to sync your component state and the URL Query string
  • The Easiest Way to Use Query Parameters in React
• Libraries
  • https://github.com/sindresorhus/query-string (6.3k)
  • https://github.com/ljharb/qs (10.2k - 27.9k)
  • https://github.com/lukeed/qss (757b)

[techniq]

Array design

URLSearchParams

URLSearchParams can use params.get(...) to get a single value (ex. ?departmentId=1 returns 1) and params.getAll(...) to get an array of values (ex. ?departmentId=1&departmentId=2 returns [1,2]).

There are a few problems with this when used as is:

• There is no way to identify if a single value is the only value in an array, or a standalone value: For example, should ?departmentId=1 result in 1 or [1]
• It can get rather verbose with multiple values (ex. ?departmentId=1&departmentId=2&departmentId=3...)

Bracket key notation

To address the first point (identify single value array), many libraries will add a bracket suffix to the key name to identify when a single value (use params.get()) vs an array (use params.getAll()) should be used. For example, ?departmentId[]=1 will produce [1]. Multiple values are notated the same (ex. ?departmentId[]=1&departmentId[]=2). Many popular libraries use this approach (or at least support it):

• https://github.com/sindresorhus/query-string#arrayformat
• https://github.com/ljharb/qs#parsing-arrays
• https://www.php.net/manual/en/function.parse-str.php

There are a few problems with this:

• It makes the keys even more verbose ([] suffix)
• Technically [ and ] should be encoded as %5B and %5D` respectively, which makes it even more verbose and unreadable (although I see some examples where this is not done)
• Still very verbose for multiple values

Custom notation

We could put all the values on the same parameter ?departmentId=[1,2,3] but brackets and commas should be encoded as ?departmentId=%5B1%2C2%2C3%5D (by either encodeURIComponent or URLSearchParams.toString()).

We could use a custom notation such as ?departmentId=(1_2_3) to use characters that do not need to be encoded.

With encodeURIComponent it doesn't encode any of the following: -_.!~*'()...

encodeURIComponent(`-_.!~*'()`)
=> "-_.!~*'()"

but URLSearchParams.toString() only ignores -_.* (and more importantly does encode())

var params = new URLSearchParams();
params.set('test', `-_.!~*'()`)
params.toString()
=> "test=-_.%21%7E*%27%28%29"

There are a lot of RFCs to read through to get a clear picture of what truly should be encoded and what shouldn't.

• RFC3986 (general URL syntax)
• RFC7230, section 2.7.1 (HTTP/S URL syntax)
• RFC1738 (Uniform Resource Locators (URL)) although it is now considered obsolete

This stack overflow provides a good summery of the various RFCs and reserved / unreserved characters.

• Characters allowed in GET parameter
• Different output from encodeURIComponent vs URLSearchParams
• Are square brackets permitted in URLs?
• Which characters make a URL invalid?
• Reminder: Encode square brackets in plan URLs by 20 October 2019

There is the jsurl that provides a custom encoding for URL-friendly JSON (shorter, more readable) but hasn't been active in 4+ years. It uses ().

Declare type

Popular react hook use-query-params flips this around and has you define the params types, for example, as individual params

  const [id, setId] = useQueryParam('id', NumberParam);
  const [name, setName] = useQueryParam('name', StringParam);

// something like: ?x=123&q=foo&filters=a&filters=b&filters=c in the URL
const [query, setQuery] = useQueryParams({
  id: NumberParam,
  name: StringParam,
  filters: withDefault(ArrayParam, []),
});

This can be a little verbose, especially to import all the param types (which are objects with encode/decode functions) and defining default values is non-intuitive. I prefer the default values being passed directly.

const params = queryParamsStore({
  id: 1,
  name: 'Sean',
  filters: [1,2,3]
})

If we have default values, we can use the type of the value to know when we have an array vs a single value, but if an array value can ever be null (no default value passed, or later set to null) then we would need to pass the param type. This could be done as a second parameter that matches the shape of the values:

const params = queryParamsStore({
  id: 1,
  name: 'Sean',
  filters: [1,2,3]
}, {
  id: Number, // or 'number'
  name: String, // or 'string'
  filters: Array // or 'array' or 'number[]' or `string[]`
})

I would like to use Typescript to define the type of the parameters, but since it is erased at runtime, this is not possible.

We might also want to use something like zod or yup for the shape/schema of the query string instead of string types (number[]) although I'm back and forth on this. Example:

const params = queryParamsStore({
  id: 1,
  name: 'Sean',
  filters: [1,2,3]
}, {
  id: z.number(),
  name: z.string(),
  filters: z.number().array()
})

or even graphql to define the type but I think this would be blending too many unreleased pieces. An example definition might look like:

const params = queryParamsStore({
  id: 1,
  name: 'Sean',
  filters: [1,2,3]
}, {
  id: graphql.GraphQLInt,
  name: graphql.GraphQLString,
  filters: graphql.GraphQLInt(graphql.GraphQLInt)
})

I think of all the ideas I prefer:

const params = queryParamsStore({
  id: 1,
  name: 'Sean',
  filters: [1,2,3]
}, {
  id: 'number'
  name: 'string'
  filters: 'number[]'
})

even though thought they are strings, we can use Typescript string literal types to define and limit what is available. For example, probably have the following:

• number
  • See NumberParam
• number[]
  • See ArrayParam and DelimitedNumericArrayParam
• string
  • See StringParam
• string[]
  • See ArrayParam and DelimitedArrayParam
• boolean
  • See BooleanParam
• Date or maybe date and datetime. Might also need localdate, utcdate, etc
  • See DateParam
• json
  • See JsonParam
• maybe object to produce foo=key1-value1_key2-value2...
  • See ObjectParam and NumericObjectParam

We would then need to determine the encoded value for each, which I think we would align closely with use-query-params. We could even use serialize-query-params's serialize and params (but map to our string definitions for simplicity). It has a peer dependency on query-string which we may not want though.