enonic-fp

Enonic FP

Functional programming helpers for Enonic XP. This library provides fp-ts wrappers around the Enonic-interfaces provided by enonic-types and the official standard libraries.

Code generation

We recommend using this library together with its sister library: enonic-ts-codegen. enonic-ts-codegen will create TypeScript interfaces for your content-types. Those interfaces will be very useful together with this library.

Requirements

1. Enonic 7 setup with Webpack
2. Individual Enonic client libraries installed (this library only contains wrappers around the interfaces)

Motivation

Most functions in this library wraps the result in an IOEither<EnonicError, A>.

This gives us two things:

1. It forces the developer to handle the error case using fold
2. It allows us to pipe the results from one operation into the next using chain (or map). Chain expects another IOEither<EnonicError, A> to be returned, and when the first left<EnonicError> is returned, the pipe will short circuit to the error case in fold.

This style of programming encourages us to write re-usable functions that we can compose together using pipe.

Usage

Get content by key service

In this example we have a service that returns an article by the key as json. Or if something goes wrong, we return an Internal Server Error instead.

import {fold} from "fp-ts/IOEither";
import {pipe} from "fp-ts/pipeable";
import {Request, Response} from "enonic-types/controller";
import {get as getContent} from "enonic-fp/content";
import {Article} from "../../site/content-types/article/article"; // 1
import {internalServerError, ok} from "enonic-fp/controller";

export function get(req: Request): Response { // 2
  const program = pipe( // 3
    getContent<Article>(req.params.key!), // 4
    fold( // 5
      internalServerError, // 6
      ok // 7
    )
  );

  return program(); // 8
}

1. We import an interface Article { ... } generated by enonic-ts-codegen.
2. We use the imported Request and Response to control the shape of our controller.
3. We use the pipe function from fp-ts to pipe the result of one function into the next one.
4. We use the get function from content – here renamed getContent so it won't collide with the get function in the controller – to return some content where the type is IOEither<EnonicError, Content<Article>>.
5. The last thing we usually do in a controller is to unpack the IOEither. This is done with fold(handleError, handleSuccess). We create two functions (handleError, and handleSuccess), that both return IO<Response>.
6. We create the Response object for the error case
7. We create the Response object for the success case
8. We have so far constructed a constant program of type IO<Response>, but we have not yet performed a single side effect. It's time to perform those side effects, so we run the IO by calling it, and return the Response we get back.

Delete content by key and publish

In this example we delete come content by key. We are first doing this on the draft branch. And then we publish it to the master branch.

We will return a http error based on the type of error that happened (trough a lookup in the errorsKeyToStatus map). Or we return a http status 204, indicating success.

import {chain, fold} from "fp-ts/IOEither";
import {pipe} from "fp-ts/pipeable";
import {Request, Response} from "enonic-types/controller";
import {publish, remove} from "enonic-fp/content";
import {run} from "enonic-fp/context";
import {errorResponse, noContent} from "enonic-fp/controller";

function del(req: Request): Response {
  const program = pipe(
    runOnBranchDraft(
      remove(req.params.key!) // 1
    ),
    chain(() => publish(req.params.key!)),  // 2
    fold( // 3
      errorResponse(req),
      noContent // 4
    )
  );

  return program();
}

export {del as delete}; // 5

const runOnBranchDraft = run({ branch: 'draft' });

1. We call the remove function with the key to delete some content. We want to do this on the draft branch, so we wrap the call in runInDraftContext (which I have copied in from the enonic-wizardry package for this example). Remove returns IOEither<EnonicError, void>. If the content didn't exist, it will return a EnonicError with errorKey="NotFoundError", that can be handled in the fold.
2. We want to publish our change from the draft branch to the master branch. So we call another function that we have copied in from enonic-wizardry, called publishContentByKey.
3. To create our Response we call fold, where we handle the error and success cases, and return IO<Response>.
4. Since this is a delete operation we return a 204 on the success case, which means "no content".
5. Since delete is a keyword in JavaScript and TypeScript, we have to do this hack to return the delete function.

Multiple queries, and http request

In this example we do 3 queries. First we look up an article by key, then we search for comments related to that article based on the articles key. And then we get a list of open positions in the company, that we want to display on the web page.

The first two are queries in Enonic, and the last one is over http. We do a sequenceT taking the 3 Either<Error, T> as input, and getting an Either with the results in a tuple (Either<Error, [Content, QueryResponse, any]>).

We then map over the tuple, and create an object with all the data, that can be returned to the user.

In the fold we either return the an error, with the correct http status (404, 500 or 502), or we return the result with the http status 200.

import {sequenceT} from "fp-ts/Apply";
import {Json} from "fp-ts/Either";
import {chain, fold, ioEither, IOEither, map} from "fp-ts/IOEither";
import {pipe} from "fp-ts/pipeable";
import {Request, Response} from "enonic-types/controller";
import {Content, QueryResponse} from "enonic-types/content";
import {EnonicError} from "enonic-fp/errors";
import {get as getContent, query} from "enonic-fp/content";
import {bodyAsJson, request} from "enonic-fp/http";
import {Article} from "../../site/content-types/article/article";
import {Comment} from "../../site/content-types/comment/comment";
import {errorResponse, ok} from "enonic-fp/controller";
import {tupled} from "fp-ts/function";

export function get(req: Request): Response {
  const articleId = req.params.key!;

  return pipe(
    sequenceT(ioEither)(
      getContent<Article>(articleId),
      getCommentsByArticleKey(articleId),
      getOpenPositionsOverHttp()
    ),
    map(tupled(createResponse)),
    fold(
      errorResponse(req, 'errors'),
      ok
    )
  )();
}

function getCommentsByArticleKey(articleId: string): IOEither<EnonicError, QueryResponse<Comment>> {
  return query<Comment>({
    contentTypes: ["com.example:comment"],
    count: 100,
    query: `data.articleId = '${articleId}'`
  });
}

function getOpenPositionsOverHttp(): IOEither<EnonicError, Json> {
  return pipe(
    request("https://example.com/api/open-positions"),
    chain(bodyAsJson)
  );
}

function createResponse(
  article: Content<Article>,
  comments: QueryResponse<Comment>,
  openPositions: Json
) {
  return {
    ...article,
    comments: comments.hits,
    openPositions
  };
}

i18n for error messages

Custom error messages for every endpoint

There is support for adding internationalization for error-messages. This is done, when you generate the Response using the errorResponse(req: Request, i18nPrefix: string) method.

The i18n-key to use to look up the message has the following shape: ${i18nPrefix}.title.${typeString} where typeString is the last section of EnonicError.type. To support every error in enonic-fp, typeString can only be one of these:

• bad-request-error
• not-found
• internal-server-error
• missing-id-provider
• publish-error
• unpublish-error
• bad-gateway

If your i18nPrefix is e.g "getArticleError", then you can add the following to your phrases.properties to get customized error messages for different endpoints.

getArticleError.title.bad-request-error=Problems with client parameters
getArticleError.title.not-found=No Article Found
getArticleError.title.internal-server-error=Can not retreive article.
getArticleError.title.missing-id-provider=Missing ID Provider.
getArticleError.title.publish-error=Unable to publish the article.
getArticleError.title.unpublish-error=Unable to unpublish the article
getArticleError.title.bad-gateway=Unable to retreive open positions.

Fallback error messages

We recommend adding the following (but translated) keys to your phrases.properties file, as they will provide backup error messages for all instances where custom error messages have not been specified.

errors.title.bad-request-error=Bad request error
errors.title.not-found=Not found
errors.title.internal-server-error=Internal Server Error
errors.title.missing-id-provider=Missing ID Provider.
errors.title.publish-error=Unable to publish data
errors.title.unpublish-error=Unable to unpublish data
errors.title.bad-gateway=Bad gateway

Alternatively you could use the status number as the typeString-part of the key. But this will not be able to separate different errors with the same status (e.g both internal-server-error, missing-id-provider and publish-error has status = 500).

errors.title.400=Bad request error
errors.title.404=Not found
errors.title.500=Internal Server Error
errors.title.502=Bad gateway

Building the project

npm run build