Building your own Effect

Effect :: Observable<T> -> Observable<U>

Marble.js HttpEffect is a more specialized form of Effect for processing HTTP requests. Its responsibility is to map every incoming request to response object.

HttpEffect :: Observable<HttpRequest> -> Observable<HttpEffectResponse>

import { HttpEffect, HttpEffectResponse, HttpRequest } from '@marblejs/core';
import { Observable } from 'rxjs/operators';
import { mapTo } from 'rxjs/operators';
​
const hello$ = (req$: Observable<HttpRequest>): Observable<HttpEffectResponse> =>
  req$.pipe(
    mapTo({ body: 'Hello, world!' }),
  );
​
// same as 
​
const hello$: HttpEffect = req$ =>
  req$.pipe(
    mapTo({ body: 'Hello, world!' }),
  );

The Effect above responds to incoming request with "Hello, world!" message. In case of HTTP protocol each incoming request have to be mapped to an object with body, status or headers attributes. If the status code or headers are not defined, then the API by default responds with 200 OK status and Content-Type: application/json header.

In order to route our first HttpEffect, we have to define the path and HTTP method that the incoming request should be matched to. The simplest implementation of an HTTP API endpoint can look like this.

import { r } from '@marblejs/core';
import { mapTo } from 'rxjs/operators';
​
const hello$ = r.pipe(
  r.matchPath('/'),
  r.matchType('GET'),
  r.useEffect(req$ => req$.pipe(
    mapTo({ body: 'Hello, world!' }),
  )$));

Let's define a little bit more complex endpoint.

import { r } from '@marblejs/core';
import { map, mergeMap } from 'rxjs/operators';
import { User, createUser } from './user.helper';
​
const postUser$ = r.pipe(
  r.matchPath('/user'),
  r.matchType('POST'),
  r.useEffect(req$ => req$.pipe(
    map(req => req.body as User),
    mergeMap(createUser),
    map(body => ({ body }))
  )));

The example above will match every POST request that matches to /user url. Using previously parsed body (see bodyParser$ middleware) we can flat map it to other stream and its result map again to HttpEffectResponse object as an action confirmation.

HttpRequest

Every HttpEffect has an access to two most basics objects created by http.Server. HttpRequest is an abstraction over the basic Node.js http.IncomingMessage object. It may be used to access response status, headers and data, but in most scenarios you don't have to deal with all available APIs offered by IncomingMessage class. The most common properties available in request object are:

• url

• method

• headers

• body (see bodyParser$ section)

• params (see routing chapter)

• query (see routing chapter)

• res (HttpResponse)

HttpResponse

Response object is also an abstraction over basic Node.js http.ServerResponse object. Besides the default API, the response object exposes an res.send method, which can be a handy wrapper over Marble.js responding mechanism. For more information about the res.send method, visit Middlewares chapter.