Pram

A small library to help reduce boilerplate code when dealing with storing state in a url's query params.

• Installation
• API Documentation
  • Pram
    • Methods
      • getParams()
      • getParam(param)
      • pushParams(params)
      • replaceParams(params)
      • pushParam(key, value)
      • replaceParam(key, value)
      • onChange(callback)
      • onChange(key, callback)
      • when(key, value, callback)
      • when(predicate, callback)
    • Usage with React
      • connectParams(pram, options)

Installation

npm install pram

API Documentation

Pram

You can access all of Pram's utilities from a Pram instance. You must provide a history object when creating the instance. If you use React Router you may be familiar with this concept, but if not here's a little snippet that gives you an idea of how to get up and running:

import createHistory from 'history/createBrowserHistory'
import Pram from 'pram'

const history = createHistory()
const pram = new Pram(history)

Methods

All of these utilities can be accessed from an instance of Pram.

getParams()

() => any

This will return you a parsed object of your current url params, according to the parse function from the qs library. For example, if your current query string is ?name=Daniel&country=UK then this function will return to you { name: 'Daniel', country: 'UK' }.

getParam(param)

(param: string) => any

This will return you the value of param from the current url params. This is the same as calling getParams()[param].

pushParams(params)

(params: {}) => void

This will push the params that you supply into the url. This is a push operation, so will create a new entry in history (the user can hit the back button and this action will be undone). The params object you pass will be encoded using the qs library's stringify function, so refer to those docs for more detailed information.

replaceParams(params)

(params: {}) => void

This is the same as pushParams detailed above, except the new query params will replace the old one, and the back button will not undo the action.

pushParam(key, value)

(key: string, value: any) => void

This will push a specific value onto your query params at the given key. This is a push operation, so will create a new entry in history (the user can hit the back button and this action will be undone). The params object you pass will be encoded using the qs library's stringify function, so refer to those docs for more detailed information.

replaceParam(key, value)

(key: string, value: any) => void

This is the same as pushParam detailed above, except the new query param will replace the old one, and the back button will not undo the action.

onChange(callback)

(callback: (value: any)) => UnregisterCallback

onChange(key, callback)

(key: string, callback: (value: any)) => UnregisterCallback

You can use this to listen for changes in query params. You can either call it with one argument; a callback function - or you can use two arguments; a query param key to filter on and a callback. If you don't provide a filter, your callback will be passed all the params. If you filter, then you will only be passed the value of the key you requested.

An example of listening to all changes:

const pram = new Pram(history)

pram.onChange(params => console.log(params))

// log: { foo: 'bar', name: 'Daniel' }

pram.onChange('name', value => console.log(value))

// log: 'Daniel'

This utility will return you a callback to unregister your callback. For instance; if you are using React and you start listening when a component mounts, then you should remember to always 'unlisten':

class View extends React.Component {
  componentDidMount() {
    this.stopListening = pram.onChange('name', console.log)
  }

  componentWillUnmount() {
    this.stopListening()
  }
}

when(key, value, callback)

(key: string, value: any, callback: (value: any) => void) => UnregisterCallback

when(predicate, callback)

(predicate: (params: {}) => boolean, callback: (params: any) => void) => UnregisterCallback

This can be used when you want a callback to fire every time a condition is met in the query params. Note, unlike onChange, when using when your callback will be fired immediately if the condition is met; not just when query params change.

Example:

const pram = new Pram(history)

// this will check that the param 'name' is exactly equals to 'Daniel'
pram.when('name', 'Daniel', () => console.log('Hi, Daniel!'))

// or use your own custom predicate function
pram.when(params => params.name === 'Daniel', () => console.log('Hi, Daniel!'))

Usage with React

React specific methods require a second import from the react submodule, as well as the peer dependency of react itself.

e.g. import { connectParams } from 'pram/react'

connectParams(pram, options)

(pram: Pram, options?: { propName?: string }) => (Component: React.ComponentType) => React.ComponentType

This is higher-order function that returns a higher-order component. Think of it like the connect function from redux, or a function that creates something similar to withRouter from react-router.

You call it with an instance of Pram and some options if you want, and it will return you something that you can compose with other HOCs to enhance your component. In this case, it will provide your component the current query params as a prop, which by default is named 'params'.

Options:

propName default: 'params'

This is the name of the prop that your component will be given.

Example:

import createHistory from 'history/createBrowserHistory'
import Pram from 'pram'
import { connectParams } from 'pram/react'

const history = createHistory()
const pram = new Pram(history)
const withParams = connectParams(pram)

const View = (props) => (
  <div>
    Hello {props.params.name}!
  </div>
)

export default withParams(View)