application/x-www-form-urlencoded adapter for Integreat

Adapter that lets Integreat send and receive content in application/x-www-form-urlencoded encoding.

Getting started

Prerequisits

Requires node v18 and Integreat v1.0.

Installing and using

Install from npm:

npm install integreat-adapter-form

Example of use:

import Integreat from 'integreat'
import httpTransporter from 'integreat-transporter-http'
import formAdapter from 'integreat-adapter-form'
import defs from './config.js'

const great = Integreat.create(defs, {
  transporters: { http: httpTransporter },
  adapters: { form: formAdapter },
})

// ... and then dispatch actions as usual

Example service configuration:

{
  id: 'store',
  transporter: 'http',
  adapters: ['form'],
  options: {
    includeHeaders: true
  },
  endpoints: [
    { options: { uri: 'https://api.com/formDataEndpoint' } }
  ]
}

Data in payload and response will be application/x-www-form-urlencoded encoded as described in the W3C Forms specification when sending to a service, and decoded back to JS data coming from a service.

Arrays are serialized to several keys postfixed with brackets '[]'. When normalizing keys postfixed with brackets, the brackets are removed and the value of all keys with the same name, are joined into one array in the order they appear.

Available options:

• setStructureInKeys: When this is true, we'll serialize key and values so that the structure of value is set in the key, with the leaf values as values. { data: [{ id: 'ent1 }] } will for instance be serialized to the key data[0][id] and the value 'ent1'. Default behavior (or when setStructureInKeys is false) is to use the first level as key (data in this case, and JSON stringify the rest as value.

Form transformer

The package also includes a transformer, that works exactly like the adapter, except it is intended for use in mutation pipelines with { $transform: 'form' }. You may use it like this:

Example of use:

import integreat from 'integreat'
import httpTransporter from 'integreat-transporter-http'
import formTransformer from 'integreat-adapter-form/transformer.js'
import defs from './config.js'

const great = Integreat.create(defs, {
  transporters: { http: httpTransporter },
  transformers: { form: formTransformer },
})

// In a mutation pipeline:

const mutation = ['response.data', { $transform: 'form' }]

Running the tests

The tests can be run with npm test.

Contributing

Please read CONTRIBUTING for details on our code of conduct, and the process for submitting pull requests.

License

This project is licensed under the ISC License - see the LICENSE file for details.