superagent-declare
Summary
Go from this:
const request = ; request ;
to this:
const superagent = ;const request = ;request ; ;
Overview
Superagent-declare provides a declarative and uncurried API for the fantastic superagent module.
Why? The primary driver for writing this module is to be able to store a declarative representation of all the request parameters without having to define them as lines of javascript code. As an example, you are able to store these request parameters in a configuration file. Furthermore, the request parameters declared in the data structure can be specified in any order.
Installation
The usual:
npm install superagent-declarative superagent
Superagent-declare does not itself include superagent as a dependency. Although it does for dev-dependencies (primarily for unit testing). So you will need to install both alongside one another in your module/app.
Usage
The interface to superagent-declare is very simple. Use the following pattern:
const superagent = ;const request = ;request ; ; // or without calling request.use(): ;
The request
call above will return an instance of superagent with the given methods invoked, but can then be further mutated. In other words, you
do not need to define all the options for your request using superagent-declare, you can programmatically augment the
resulting object. i.e. based on example in summary:
;
Use of superagent and declare APIs can be intermixed - you are not locked into the declare API. i.e.
const superagent = ;const request = ;request ; ; // and can also call this way in same codebase superagent ;
Superagent-declare API Syntax
This section outlines how the superagent API translates into a declarative JS data structure that can be passed to superagent-declare.
The following definitions are used throughout:
- method = superagent method name (e.g. send() or field())
- argument = an argument or parameter passed to a method (e.g. '/upload' in post('/upload') )
The object literal passed to superagent-declare has these forms.
Call a method with no arguments or a single argument
method: []
Call method once with no argumentsmethod: 'argument'
Call method once with one argumentmethod: {'key': argument}
Call method once with one argumentmethod: [ [ [1, 2, 3] ] ]
Call method once with one argument being an array
;
Call a method with two or more arguments
method: [ 'arg1', 'arg2', ... ]
Call method once with two or more argumentsmethod: [ 'arg1', ['arg2 element 0', 'arg2 element 1'], ... ]
Call method once with two or more arguments
;
Call a method multiple times with one or multiple arguments
method: [ ['call1 arg1', 'call1 arg2'], ['call2 arg1', 'call2 arg2'], ... ]
Call method two or more times with sub-array arguments
;
Examples
Following are many examples and patterns that show how to use the declarative API.
request ;//-------------------------------------------------------------------------------request ;//-------------------------------------------------------------------------------request ;//-------------------------------------------------------------------------------request ;//-------------------------------------------------------------------------------request ;//-------------------------------------------------------------------------------request ;//-------------------------------------------------------------------------------request; ;
Contributions
Contributions are most welcome.
Licence
Copyright (c) 2018 Damien Clark
Licensed under the Apache License, Version 2.0
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Acknowledgements / Attribution
Many thanks to the team who created and maintain the superagent project.