@f/brackets

Bracket notation for form input names

Stats

StarsIssuesVersionUpdatedCreatedSize
@f/brackets
001.0.06 years ago6 years agoMinified + gzip package size for @f/brackets in KB

Readme

brackets

Build status Git tag NPM version Code style

Bracket notation for form input names

Installation

$ npm install @f/brackets

Usage

Mostly this is useful for serializing form data to JSON. There is a W3C spec to which this kind of sort of complies, but the spec seems to have been abandoned for reasons unknown. The square notation is essentially a replacement for '.' in dotted paths. You specify name[first], name[last], and it will set the corresponding properties:

brackets({}, 'name[first]', 'micro-js') // -> {name: {first: 'micro-js'}}

But it does a little more than dot notation, because it also lets you deal with lists, by using empty square brackets:

brackets({}, 'colors[]', 'red')                   // -> {colors: ['red']}
brackets({colors: ['red']}, 'colors[]', 'green'), // -> {colors: ['red', 'green']}

If you'd like to set nested properties in lists, you can do that too, by just adding more bracketed properties after the []:

var tmp = brackets({}, 'groups[][name]', 'friends') // -> {groups: [{name: 'friends'}]}
brackets(tmp, 'groups[][id]', 1)                    // -> {groups: [{name: 'friends', id: 1}]}

Here's where things get a little messy though. You may be wondering, how does it know I didn't want to append to that list on the second set? The answer is that it checks to see if the deeper property you're trying to set exists already, and only then does it append a new item:

brackets({}, 'groups[][name]', 'friends')                         // -> {groups: [{name: 'friends'}]}
brackets({groups: [{name: 'friends'}]}, 'groups[][id]', 1)        // -> {groups: [{name: 'friends', id: 1}]}
brackets({groups: [{name: 'friends'}]}, 'groups[][name]', 'work') // -> {groups: [{name: 'friends'}, {name: 'work'}]}

Example

var reduce = require('@f/reduce')
var brackets = require('@f/brackets')
var controls = require('@f/form-controls')
var serializable = require('@f/is-serializable')

function serialize (form) {
  return reduce(function (acc, ctrl) {
    return serializable(ctrl)
      ? brackets(acc, ctrl.name, ctrl.value)
      : acc
  }, {}, controls(form))
}

API

brackets(obj, path, value)

  • obj - The object you want to set path to value within
  • path - The path using square bracket notation you want to set value at
  • value - The value you want to set at path

Returns: obj. This function is mutative, you will not receive a fresh copy of obj.

License

MIT

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.