LogoLogo
ChangelogGitHubTwitterGitter
v4.x
v4.x
  • Marble.js
  • Getting started
    • Installation
    • Quick setup
  • HTTP
    • Effects
    • Middlewares
    • Routing
    • Errors
    • Output
    • Context
    • Advanced
      • Logging
      • Validation
      • Server Events
      • Streaming
      • Continuous mode
  • Messaging
    • Core concepts
      • Events
      • Effects
    • Microservices
      • AMQP (RabbitMQ)
      • Redis Pub/Sub
    • CQRS
    • WebSockets
  • Testing
    • HTTP routes testing
  • Other
    • How does it glue together?
    • Migration guides
      • Migration from version 3.x
      • Migration from version 2.x
      • Migration from version 1.x
    • API reference
      • @marblejs/core
        • bindTo
        • bindEagerlyTo
        • createEvent
        • createContextToken
        • operator: matchEvent
        • operator: use
        • operator: act
      • @marblejs/http
        • httpListener
        • r.pipe
        • combineRoutes
        • createServer
      • @marblejs/messaging
        • eventBus
        • messagingClient
        • createMicroservice
        • reply
      • @marblejs/websockets
        • webSocketListener
        • operator: broadcast
        • operator: mapToServer
      • @marblejs/middleware-multipart
      • @marblejs/middleware-cors
      • @marblejs/middleware-io
      • @marblejs/middleware-logger
      • @marblejs/middleware-body
      • @marblejs-contrib/middleware-jwt
        • Token signing
      • @marblejs-contrib/middleware-joi
    • Style Guide
    • FAQ
Powered by GitBook
On this page
  1. HTTP

Effects

Effect is the main building block of the whole framework. It is just a function that returns a stream of events. Using its generic interface we can define API endpoints, event handlers or middlewares.

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/http';
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 has 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 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/http';
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/http';
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 }))
  )));

Deprecation warning

HttpRequest

  • url

  • method

  • headers

  • res (HttpResponse)

HttpResponse

Since Marble.js version 3.0, HttpResponse object is accessible via req.res attribute of every HttpRequest.

PreviousQuick setupNextMiddlewares

Last updated 3 years ago

Every Marble.js Effect is eagerly bootstrapped on app startup with its own hot Observable. It means that a function can act as a constructor and a returned stream as a place "where the magic happens". It gives you a set of possibilities in terms of optimization, so e.g. you can inject all required during the app startup only once.

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

With an introduction of Marble.js 4.0, old EffectFactory HTTP route builder does not exist anymore. Please use builder instead.

Every HttpEffect has an access to two most basics objects created by http.Server. HttpRequest is an abstraction over the basic Node.js 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:

body (see section)

params (see chapter)

query (see chapter)

For more details about available API offered in http.IncomingMessage, please visit .

Response object is also an abstraction over basic Node.js 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 chapter.

For more details about the available API offered in http.ServerResponse, please visit .

context readers
bodyParser$
r.pipe
http.IncomingMessage
bodyParser$
routing
routing
official Node.js docummentation
http.ServerResponse
Middlewares
official Node.js docummentation