Unquery 🍫

Build and control query-strings with confidence.

It helps you to parse and stringify query-strings in a predictable way.

Instalation

To install, use:

Yarn:

yarn add --save unquery

Npm:

npm install --save unquery

Usage

Example 1 - Basic Usage

import { Unquery } from 'unquery'

const querySchema = Unquery('?foo=bar&baz=1', {
  foo: Unquery.string(),
  baz: Unquery.number()
})

console.log(querySchema)

{ "foo": "bar", "baz": 1 }

Example 2 - Different types usage

const querySchema = Unquery('?foo=str&bar=123&baz=1,2,3&date=2020-01-01&num=10&unnecessary=false' {
  foo: Unquery.string(),
  bar: Unquery.number(),
  baz: Unquery.array(Unquery.number()),
  date: Unquery.string(),
  num: Unquery.custom(value => Number(value) * 2)
}, { arrayFormat: "comma" })

console.log(querySchema)

{
  "foo": "str",
  "bar": 123,
  "baz": [ 1, 2, 3 ],
  "date": "2020-01-01",
  "num": 20
}

Example 3 - Stringify usage

import { Unquery, stringify } from "unquery"

const querySchema = Unquery('?foo=str&bar=123&baz=1,2,3&date=2020-01-01&unnecessary=false' {
  foo: Unquery.string(),
  bar: Unquery.number(),
  baz: Unquery.array(Unquery.number()),
  date: Unquery.array()
}, { arrayFormat: "comma" })

const stringified = stringify(querySchema, { arrayFormat: 'bracket' })
console.log(stringified)

"?foo=str&bar=123&baz[]=1&baz[]=2&baz[]=3&date[]=2020-01-01"

API

Unquery(input: string, schema: object, config: object)

@param input: string

Input to be parsed.

@param schema: object

Your query-string schema, that's gonna be parsed.

@param config: object

Options to customize the schema that's gonna be generated.

Options

• arrayFormat
  • Description Array format to parse query-string. Use the same format used by query-string.
  • Type string
  • Default none
  • Values Each value will parse the following query-strings into an array:

  "bracket": "foo[]=1&foo[]=2&foo[]=3"
  "index": "foo[0]=1&foo[1]=2&foo[3]=3"
  "comma": "foo=1,2,3"
  "none": "foo=1&foo=2&foo=3"

• skipNull
  • Description Skip null values to be parsed.
  • Type boolean
  • Default false

  Unquery('?value=123', {
    value: Unquery.number(),
    notInQueryValue: Unquery.string()
  }, { skipNull: false })
  
  // { value: 123, notInQueryValue: null }

  Unquery('?value=123', {
    value: Unquery.number(),
    notInQueryValue: Unquery.string()
  }, { skipNull: true })
  
  // { value: 123 }

• skipUnknown
  • Description Skip unknown values to be parsed.
  • Type boolean
  • Default true

  Unquery('?value=foo&unknown=bar', {
    value: Unquery.string()
  }, { skipUnknown: false })
  
  // { value: "foo", unknown: "bar" }

  Unquery('?value=foo&unknown=bar', {
    value: Unquery.string()
  }, { skipUnknown: true })
  
  // { value: "foo" }

Unquery Methods

When you create an Unquery Object, your query will receive some super powers ⚡️!

const query = Unquery(...) // query is an Unquery Object

Global API

• addLocationURL

  • Description Add query-string to URL. This keeps all current search.
  • Type (query: object | string, options: StringifyOptions) => void
  • Default null
  • Example

  import { Unquery, addLocationURL } from 'unquery'
  
  // https://yoursite.com/
  const querySchema = Unquery('?foo=bar&baz=42', {
    foo: Unquery.string(),
    baz: Unquery.number()
  })
  
  addLocationURL(querySchema)
  // https://yoursite.com?foo=bar&baz=42
  
  addLocationURL('date=2020-09-01')
  // https://yoursite.com?foo=bar&baz=42&date=2020-09-01

• replaceLocationURL

  • Description Replace all URL search by the query-string.
  • Type (query: object | string, options: StringifyOptions) => void
  • Default null
  • Example

  import { Unquery, replaceLocationURL } from 'unquery'
  
  // https://yoursite.com/
  const querySchema = Unquery('?foo=bar&baz=42', {
    foo: Unquery.string(),
    baz: Unquery.number()
  })
  
  replaceLocationURL(querySchema)
  // https://yoursite.com?foo=bar&baz=42
  
  replaceLocationURL('date=2020-09-01')
  // https://yoursite.com?date=2020-09-01

• clearLocationURL

  • Description Clear all query-string from URL without reload the page.
  • Type () => void
  • Default null
  • Example

  import { Unquery, clearLocationURL } from 'unquery'
  
  // https://yoursite.com/?foo=bar&baz=42
  const query = Unquery('?foo=bar&baz=42', {
    foo: Unquery.string(),
    baz: Unquery.number()
  })
  
  clearLocationURL()
  // https://yoursite.com/

• stringify

  • Description Stringify an object into a query string.
  • Type (queryObject: UnqueryObject, options: StringifyOptions) => string
  • Default

  {
    // You can set your unqueryOptions by calling setOptions(options)
    arrayFormat: unqueryOptions.arrayFormat // default: 'none'
  }

  • Examples

  import { stringify } from 'unquery'
  
  const stringified = stringify({ startDate: '2020-01-01', viewId: 4 })
  // "startDate=2020-01-01&viewId=4"

• setOptions

  • Description Set default options to use in your entire app.
  • Type (options: UnqueryOptions) => UnqueryOptions
  • Examples

  import { Unquery, stringify, setOptions } from 'unquery'
  
  setOptions({
    arrayFormat: 'comma',
    skipNull: true,
    skipUnknown: false
  })
  
  const query = Unquery('?date=2020-02-01&foo=1,2,3', {
    date: Unquery.string()
  })
  // { date: "2020-02-01", foo: ['1','2','3'] }
  
  const stringified = stringify(Unquery, { arrayFormat: 'index' })
  // 'data=01/02/2020&foo[0]=1&foo[1]=2&foo[2]=3