@crosspath/yambus v0.2.1
Yambus
This package generates functions for accessing application routes (e.g.
create_account_path
) and performing requests to the application (e.g.
create_account
).
See gem Railbus for integration with Rails framework.
Installation
$ yarn add @crosspath/yambus
Recommended step: add adapter for generating requests. Do one of these commands:
$ yarn add @crosspath/yambus-axios
$ yarn add @crosspath/yambus-fetch
Package yambus-axios
uses axios
library that supports latest browser
versions and IE9+. Package yambus-fetch
uses native function fetch
that
isn't available in IE but you may use it with Edge, Chrome, Firefox, Safari,
Opera.
Also you may write adapter for any other library or function.
Package yambus-axios
contains very short code that you may use as base
for writing your adapter.
Usage
Assume you have an object for defining application routes:
{
// Route names will be used for names of generated functions as
// `${route_name}` for requests and `${route_name}_path` for getting path.
route_name: {
// HTTP verbs: 'get', 'post', 'put', 'patch', 'delete', 'head'.
// Lower case!
verb: 'get',
// ':url' is a placeholder for a value, and any ':value' too.
path: '/string/representation/of/your/:url',
// Array of strings and objects. Each object has form `{a: 'name'}`,
// it contains name of placeholder for a value.
parts: ['/string/representation/of/your/', {a: 'url'}],
// Array of strings. Each string is name of placeholder for a value.
required: ['url'],
// The same `route_name`
name: 'route_name'
}, ...
}
This object should be generated, not written by hand.
Now you may use your routes for generating functions with Yambus:
// Example file name: routes.js
import yambus from '@crosspath/yambus'
// Import adapter for doing requests via Axios.
// Axios is not required but used for demonstration purpose.
// You may use `yambus-fetch` package or any other library for HTTP requests.
import { request } from '@crosspath/yambus-axios'
const routes = { /* your application routes */ }
const route_functions = yambus.generate_route_functions(
routes,
(route, args) => request(route, yambus.build_request_options(route, args))
)
export default route_functions
Import this file and call its functions:
import Routes from 'routes'
// Get path with positional arguments:
console.log(Routes.route_name_path('test-value'))
// Or with object:
console.log(Routes.route_name_path({url: 'test-value'}))
// Result:
// => /string/representation/of/your/test-value
How does it work? When you use positional arguments (first case above), values
are passed to elements of parts
in this route, one-by-one in the same order.
And when you use {object}
(second case), values passed to the named elements
of parts
using placeholders like {a: 'url'}
.
Also you may call requests to the application:
// Send request with positional arguments:
Routes.route_name('test-value').then(resp => console.log(resp.data))
// Or with object:
Routes.route_name({url: 'test-value'}).then(resp => console.log(resp.data))
These functions return Promise
. See adapters' README for more info about
value of resp
variable.
Functions' arguments
Here String or Number, ...
represents values used in paths, e.g.
:id
, :category_id
(zero, one or more params); that's positional arguments
for generating paths (first case).
And ...path_params
means object with values for paths, e.g.
{id: 123, category_id: 56}
(zero, one or more params); that's passing object
with values for generating paths (second case).
data
here means request body (payload), it can be {object}
, FormData
and
so on, its allowed types depend on library or function for doing requests.
// Request actions with `get` & `delete` verbs.
({format: String, ...path_params, ...url_options})
// Or:
(String or Number, ..., {format: String, ...url_options})
// Request actions with `post`, `put`, and `patch` verbs.
({format: String, ...path_params, ...url_options}, data)
// Or:
(String or Number, ..., {format: String, ...url_options}, data)
// Get path for any action (does not include query string starting with '?').
({format: String, ...path_params})
// Or:
(String or Number, ..., {format: String})
format
is optional. If passed it will be appended to the path as
/your/url.json
for {format: 'json'}
.
All arguments are optional. But if you need to pass data and leave path params
empty, then you should pass explicit first argument {}
. For example,
const fd = new FormData()
fd.append('attachment', input.files[0]) // Assume `input` is `<input/>` node.
Routes.attach_file({}, fd) // Instead of `Routes.attach_file(fd)`.
Available exported functions
build_request_options(route, args) -> {path, url_options, data}
Purpose: parse arguments and apply values to path's placeholders.
Arguments:
route
, object{verb, path, parts, required, name}
, it's your app routeargs
, array ofString | Number | Object
, contains passed arguments to path & request functions
Returns:
path
, string, URLurl_options
, Object, contains passed arguments to path & request functions (except request body)data
, null or Object, request body
generate_route_functions(routes, request_function) -> {...}
Purpose: create functions for getting application paths and performing requests.
Arguments:
routes
, Object, collection of your app routesrequest_function
, function(route, args) => Promise
, function for doing requests. Paramsroute
&args
are the same as inbuild_request_options
.
Returns:
- key-value Object, where key is function's name and value is function
has_blob(obj, level = 0) -> boolean
Purpose: check whether this object contains Blob
(attached File
). If it has
Blob
then this object should be send with FormData
.
Arguments:
obj
, Object, data for request bodylevel
, Number, how deep in the data we are now. Recursion stops onlevel >= 1000
.
Returns:
- true if
obj
is object and containsBlob
- false, otherwise
build_form_data(obj) -> FormData
Purpose: wrapper for creating FormData
object. obj
should not be FormData
.
Arguments:
obj
, Object, data for request body
Returns:
FormData
object
Contributing
Bug reports and pull requests are welcome on GitHub at github.com/crosspath/yambus.
Please do not change version number in pull requests.
License
This package is available as open source under the terms of the MIT License.