Giter VIP home page Giter VIP logo

flyd-ajax's Introduction

flyd-ajax

A simple ajax library (using XMLHttpRequest) that returns flyd streams.

  • Small size
  • FRP with flyd
  • Supports mock requests for unit tests
  • Supports error/progress/abort

Many of the options, terminology, and response objects are directly from the normal XMLHttpRequest API. See the MDN Articles on that topic for details around how to work with response and progress objects.

Example GET request

// Calling request(...) immediately makes the request
const response = request({
  method: 'GET'
, url: 'http://spacejam.com'
, path: '/'
, query: 'x=y' // data to send; must be text, FormData, or an object (objects get JSON.stringify-ed)
, headers: {'Content-Type': 'application/json'} // any number of header key/vals
, withCredentials: true // whether to send cookies
})

// The response object has four keys: .load, .error, .progress, and .abort
// Each of these keys holds a stream of request objects for the corresponding event
// Most of the time you will just use .load stream

const resp$ = request.load // flyd stream of request objects when the response is loaded
flyd.map(r => console.log('Response!', r.body, r.status), resp$)

Example POST request

request({
  method: 'post'
, path: '/users'
, send: {name: 'Finn Mertens', email: '[email protected]'} // Can be an Object, String, or FormData
})

// If you leave out url, it will post to the path on the current domain

// If you pass in Object into the .send property, it will convert it to a JSON string by default

Returned streams

The request function immediately returns an object with a set of streams:

// object that gets returned by the request function:
{
  load      // stream of a request object when the request is completed
, error     // stream of event object when the request cannot be completed due to some error
, progress  // stream of event object on progress events in the request
, abort     // stream of event object on aborted request event
}

Most of the time you will only need the .load stream -- error and progress are useful for file transfers.

Each of the above streams will emit the exact corresponding event or request objects as described here: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest

The .load stream will have a .body property, which will contain a parsed JS object of JSON data, if the response's had 'json' in its content type. Otherwise it will be a String.

You can map over any of these streams to work with the responses and events. Example usage:

let getPosts = request({ method: 'GET' , path: '/posts' })
flyd.map(req => console.log('Completed request!', req.body), getPosts.load)
flyd.map(ev => console.log('Error event!', ev), getPosts.error)
flyd.map(ev => console.log('Progress event!', ev), getPosts.progress)

Configuration

One easy way to pre-configure ajax requests is to simply define your own module that wraps the request function.

import request from 'flyd-ajax'
import R from 'ramda'
import flyd from 'flyd'

const apiRequest = (method, path, data) =>
  request({
    method
  , path
  , url: api_url
  , send: data
  , headers: {'Content-Type': 'application/json', 'X-CSRF-Token': 'xyz'}
  }).load

// Stream of post responses, could be failure or success
const response$ = apiRequest('post', '/users' {name: 'Finn Mertens'})

// Stream of user data
const createdUser$ = R.compose(
  flyd.map(r => r.body)
, flyd.filter(R.propEq('status', 200))
)(response$) 

// Stream of error messages from creating a user
const errorMessage$  = R.compose(
  flyd.map(r => r.body.error)
, flyd.filter(r => r.status !== 200)
)(response$)

Development

Test

Tests use zuul and assert

npm run test

Build

Develop the .es6 files and transpile them to .js with:

npm run build

Mocking requests for tests

flyd-ajax comes with a built-in utility for mocking ajax requests for frontend unit testing. The require path is flyd-ajax/mock

Example:

import assert from 'assert'
import request from 'flyd-ajax'
import mockRequest from 'flyd-ajax/mock'

suite('test an ajax call')

test('it handles some ajax', () => {
  mockRequest.setup() // This overwrites XMLHttpRequest

  const status = 201
  body = 'hi'
  mockRequest.handle('get', 'http://localhost:420/test', {status, body}) // mock a response from the server for a specific endpoint

  // Make the request as you normally would
  const resp = request({method: 'get', url: 'http://localhost:420', path: '/test'})
 
  // The request will be made synchronously and the response is immediately available
  assert.deepEqual(resp.load().body, {status, body})

  // Restore XMLHttpRequest
  mock.teardown()
})

Mock API:

  • setup() -- Overwrite window.XMLHttpRequest
  • teardown() -- Restore window.XMLHttpRequest
  • handle(method, url, responseObject) -- Catch and handle requests to this endpoint

The responseObject can have these properties:

  • body -- mock response body
  • headers -- mock response headers
  • status -- mock response status code

flyd-ajax's People

Contributors

jayrbolton avatar

Stargazers

Doug Brown avatar Yutaka Houlette avatar

Watchers

James Cloos avatar  avatar

Forkers

commitchange

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.