Skip to content
Eugene Lazutkin edited this page Nov 26, 2019 · 22 revisions

I/O

io is used on browser to communicate with servers. It is a thin wrapper over XMLHttpRequest AKA XHR, and fetch(), based on promises (special fast implementation of promises is provided with heya-async). With its modular design it can use other transports (JSON-P and <script> come included), and I/O orchestration services (an application-level cache, a bundle service, and track for I/O requests), as well as flexible I/O mocking facilities.

It has three main purposes:

  1. Provide a convenient flexible helper to code I/O requests.
  2. Provide a way to customize an I/O handling to account for peculiarities of a given server environment including URL rewriting, handling custom error envelopes, implementing application-specific retries, and so on.
  3. Provide a solid foundation to orchestrate I/O (see bundle).

As such the following simple API is provided:

  • io.get() — GET a resource.
  • io.post() — make a POST call.
  • io.put() — make a PUT call.
  • io.patch() — make a PATCH call.
  • io.remove(), io.del() and io['delete']() — make a DELETE call.
  • io.head() — make a HEAD call.
  • io.options() — make an OPTIONS call.

All of them are built on top of:

  • io() — make any call using XHR.

io exposes various parameters to customize its behavior including join points suitable for AOP and functional replacement techniques.

See the main API, and How to include for more details.

The following services come bundled with io and work transparently with the above API:

  • bundle — bundles several calls together, sends them as a bundle, perform I/O locally on a server, which sends the results back, unbundles them, and returns transparently to subscribers.
  • cache — an application-level flexible cache, which is completely controlled by an application.
  • track — tracks I/O reusing duplicated requests, waiting for a request in flight, instead of issuing another request, and so on.
  • mock — allows to intercept and process I/O requests on a client by returning constants or calculated values, redirecting, and so on. A must for writing tests!
  • bust — helps to generate a randomized query value to bust browser's cache.
  • retry — retries unreliable services.

Following simple transports are there as well:

  • jsonp — make a JSON-P call.
  • load — include a Javascript with <script>.
  • fetch — use fetch() to handle HTTP calls.

Useful utilities:

  • url — forms a URL, while sanitizing parameters.

Don't forget to check out code snippets in the cookbooks:

Clone this wiki locally