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.

Enonic-wizardry

Enonic-fp aims to only provide functional wrappers for the standard libraries, and nothing else. So we recommend also installing enonic-wizardry. Enonic-wizardry provides useful useful utilities and helper functions that every project needs.

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.

Building the project

npm run build

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 { io } from "fp-ts/lib/IO";
import { fold } from "fp-ts/lib/IOEither";
import { pipe } from "fp-ts/lib/pipeable";
import { Request, Response } from "enonic-types/lib/controller";
import { get as getContent } from "enonic-fp/lib/content";
import { Article } from "../../site/content-types/article/article"; // 1

export function get(req: Request): Response { // 2
  const program = pipe( // 3
    getContent<Article>({ // 4
      key: req.params.key!
    }),
    fold( // 5
      (err) =>
        io.of(
          { // 6
            status: 500,
            body: err,
            contentType: "application/json"
          } as Response
        ),
      (content) =>
        io.of(
          { // 7
            status: 200,
            body: content.data,
            contentType: "application/json"
          }
        )
    )
  );
  
  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 sideeffect. It's time to perform those side effects, so we run the IO by calling it.

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 { IO, io } from "fp-ts/lib/IO";
import { chain, fold, IOEither, map } from "fp-ts/lib/IOEither";
import { pipe } from "fp-ts/lib/pipeable";
import { Request, Response } from "enonic-types/lib/controller";
import { publish, remove } from "enonic-fp/lib/content";
import { EnonicError } from "enonic-fp/lib/errors";
import { run } from "enonic-fp/lib/context";

function del(req: Request): Response {
  const key = req.params.key!;

  const program = pipe(
    runInDraftContext(
      remove({ key }) // 1
    ),
    chain(publishContentByKey(key)),  // 2
    fold( // 3
      (err) =>
        io.of(
          {
            body: err,
            contentType: "application/json",
            status: errorKeyToStatus[err.errorKey]
          } as Response
        ),
      () =>
        io.of(
          {
            body: "",
            status: 204 // 4
          } as Response
        )
    )
  );
  
  return program(); // 5
}

export { del as delete }; // 6

/**
 * This function is found in the "enonic-wizardry" package
 */
function runInDraftContext<A>(a: IO<A>): IO<A> {
  return run<A>({
    branch: 'draft'
  })(a);
}

/**
 * This function is found in the "enonic-wizardry" package
 */
export function publishContentByKey<A>(key: string): (a: A) => IOEither<EnonicError, A> {
  return (a): IOEither<EnonicError, A> => {
    return pipe(
      publish({
        keys: [key],
        sourceBranch: 'draft',
        targetBranch: 'master',
      }),
      map(() => a)
    );
  }
}

const errorKeyToStatus: { [key: string]: number } = {
  InternalServerError: 500,
  NotFoundError: 404,
  PublishError: 500
};

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>.
3. Since this is a delete operation we return a 204 on the success case, which means "no content".
4. We have so far constructed a constant program of type IO<Response>, but we have not yet performed a single sideeffect. It's time to perform those side effects, so we run the IO by calling it.
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/lib/Apply";
import { parseJSON } from "fp-ts/lib/Either";
import { io } from "fp-ts/lib/IO";
import { chain, fold, fromEither, ioEither, IOEither, map } from "fp-ts/lib/IOEither";
import { pipe } from "fp-ts/lib/pipeable";
import { Request, Response } from "enonic-types/lib/controller";
import { QueryResponse } from "enonic-types/lib/content";
import { HttpResponse } from "enonic-types/lib/http";
import { EnonicError } from "enonic-fp/lib/errors";
import { get as getContent, query } from "enonic-fp/lib/content";
import { request } from "enonic-fp/lib/http";
import { Article } from "../../site/content-types/article/article";
import { Comment } from "../../site/content-types/comment/comment";

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

  const program = pipe(
    sequenceT(ioEither)(
      getContent<Article>({ key: articleKey }),
      getCommentsByArticleKey(articleKey),
      getOpenPositionsOverHttp()
    ),
    map(([article, comments, openPositions]) =>
      ({
        ...article,
        comments: comments.hits,
        openPositions
      })
    ),
    fold(
      (err: EnonicError) =>
        io.of(
          {
            body: err,
            contentType: "application/json",
            status: errorKeyToStatus[err.errorKey]
          } as Response
        ),
      (res) =>
        io.of(
          {
            body: res,
            contentType: "application/json",
            status: 200
          }
        )
    )
  );

  return program();
}

const errorKeyToStatus: { [key: string]: number } = {
  BadGatewayError: 502,
  InternalServerError: 500,
  NotFoundError: 404
};

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

function getOpenPositionsOverHttp(): IOEither<EnonicError, any> {
  return pipe(
    request({
      url: "https://example.com/api/open-positions"
    }),
    chain((res: HttpResponse) =>
      fromEither(
        parseJSON(res.body!, (reason: any) =>
          ({
            cause: String(reason),
            errorKey: "BadGatewayError"
          } as EnonicError)
        )
      )
    )
  );
}