Functional programming helpers for Enonic XP
npm install enonic-fp
Functional programming helpers for Enonic XP. This library provides fp-ts wrappers
around the Enonic-interfaces provided by enonic-types, which again
wraps the official standard libraries (in jars).
We recommend using this library together with the
xp-codegen-plugin Gradle plugin. xp-codegen-plugin will create TypeScript interfaces for your content-types. Those interfaces will be very useful together with this library.
1. Enonic 7 setup with Webpack
2. Individual Enonic client libraries installed (this library only contains wrappers around the interfaces)
Most functions in this library wraps the result in an
IOEither
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 to be returned. When the first left 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.
In this example we have a service that returns Article content – that has a key as id – as json. Or if something goes
wrong, we return an _Internal Server Error_ instead.
``typescript
import {fold} from "fp-ts/IOEither";
import {pipe} from "fp-ts/pipeable";
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: XP.Request): XP.Response { // 2
const program = pipe( // 3
getContent
fold( // 5
internalServerError,
ok
)
);
return program(); // 6
}
`
1. We import an interface Article { ... } generated by Request
xp-codegen-plugin.
2. We use the imported and Response to control the shape of our controller.pipe
3. We use the function from fp-ts to pipe the result of one function into the next one.get
4. We use the function from content – here renamed getContent so it won't collide with the get function in IOEither
the controller – to return some content where the type is .IOEither
5. The last thing we usually do in a controller is to unpack the . This is done with fold(handleError, handleSuccess)
. _enonic-fp_ comes with a set of functions that creates an IO withfold
the data. There are pre-configured functions that can be used in for some of the most common http status ok()
numbers. Like and internalServerError().program
6. We have so far constructed a constant of type IO, but we have not yet performed a single IO
side effect. It's time to perform those side effects, so we run the by calling it, and return the Response we
get back.
In this example we delete come content by key. We are first doing this on the draft branch. And then we publish itmaster
to the branch.
We will return a http error based on the type of error that happened (trough a lookup in the errorsKeyToStatus map). 204
Or we return a http status , indicating success.
`typescript
import {chain, fold} from "fp-ts/IOEither";
import {pipe} from "fp-ts/pipeable";
import {publish, remove} from "enonic-fp/content";
import {run} from "enonic-fp/context";
import {errorResponse, noContent} from "enonic-fp/controller";
function del(req: XP.Request): XP.Response {
const program = pipe(
runOnBranchDraft(
remove(req.params.key!) // 1
),
chain(() => publish(req.params.key!)), // 2
fold( // 3
errorResponse({ req, i18nPrefix: "articleErrors" }), // 4
noContent // 5
)
);
return program();
}
export {del as delete}; // 6
const runOnBranchDraft = run({ branch: 'draft' }); // 7
`
1. We call the remove function with the key to delete some content. We want to do this on the _draft_ branch, so we runInDraftContext
wrap the call in the function that is defined below. IOEither
Remove returns . If the content didn't exist, it will return an EnonicError with offold()
type "https://problem.item.no/xp/not-found", that can be handled in the
.publish()
2. We want to publish our change from the _draft_ branch to the _master_ branch. The function in key
_enonic-fp_ has an overload that only takes the as a string and defaults to publish from _draft_ to Response
_master_.
3. To create our we call fold, where we handle the error and success cases, and return IO.errorResponse()
4. The function use the HttpError.status field to know which http status number to use on the Response
. It can optionally take the Request and a i18nPrefix as parameters. Request
* The adds the HttpError.instance on the return object, and it will check if req.mode !== 'live',i18nPrefix
and if yes, return more details about the error (this is to prevent exploits based on the error messages).
* The usage of is detailed the i18n for error messages chapter. delete
5. Since this is a delete operation we return a
https status 204 on the success case, which means
"no content".
6. Since delete is a keyword in JavaScript and TypeScript, we have to do this hack to return the function.ContextLib.run
7. This is a curried version of . It returns a new function – here assigned to the constant runOnBranchDraft
– that takes an IO as parameter (which all the wrapped functions already return as IOEither).
In this example we do three 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.
`typescript
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 {Content, QueryResponse} from "/lib/xp/content";
import {getRenderer} from "enonic-fp/thymeleaf";
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 {ok, unsafeRenderErrorPage} from "enonic-fp/controller";
import {tupled} from "fp-ts/function";
const view = resolve('./article.html');
const errorView = resolve('../../templates/error.html');
const renderer = getRenderer
export function get(req: XP.Request): XP.Response {
const articleId = req.params.key!;
return pipe(
sequenceT(ioEither)( // 2
getContent
getCommentsByArticleKey(articleId),
getOpenPositionsOverHttp()
),
map(tupled(createThymeleafParams)), // 3
chain(renderer), // 4
fold(
unsafeRenderErrorPage(errorView), // 5
ok
)
)();
}
function getCommentsByArticleKey(articleId: string)
: IOEither
return query
contentTypes: ["com.example:comment"],
count: 100,
query: data.articleId = '${articleId}'
});
}
function getOpenPositionsOverHttp(): IOEither
return pipe(
request("https://example.com/api/open-positions"), // 6
chain(bodyAsJson)
);
}
function createThymeleafParams( // 7
article: Content
comments: QueryResponse
openPositions: Json
): ThymeleafParams {
return {
id: article._id,
data: article.data,
comments: comments.hits,
openPositions
};
}
interface ThymeleafParams {
readonly id: string;
readonly data: Article;
readonly comments: ReadonlyArray
readonly openPositions: Json
}
`
1. getRenderer() is a curried version of ThymeleafLib.render(). It takes ThymeleafParams (defined below) as a view
type parameter and the as a parameter, and returns a function with this signature: (params: ThymeleafParams) => IOEither
, where the string is the finished rendered page.sequenceT
2. We do a taking the three IOEither as input, and getting an IOEither with the results IOEither
in a tuple (). The first two are queries in map
Enonic, and the last one is over http.
3. We then over the tuple, using createThymeleafParams(). But first we use the tupled function on createThymeleafParams()
to give us _a new version_ of createThymeleafParams that takes the parameters as a tupled
tuple, instead of as individual arguments. A good rule of thumb is to always use together with sequenceT!render()
4. We use the function in a chain(), since it returns an IOEither.pipe
5. If any of the functions in the has returned a Left, we need to handle the EnonicError. InunsafeRenderErrorPage()
this case we want to render an error page. The takes the errorView (html page) as EnonicError
parameter, which should be a template for . If the templating succeeds, an IO is createdbody
with the page as the , and with the http status from the EnonicError. But if it fails, we just need to letHttpLib.request
it fail completely and handled by Enonic XP, because we don't want an infinite loop of failing templating.
6. We use an overloaded version of , which only takes the url as parameter. We then pipe it into thebodyAsJson
function that parses the json in the Request.body and returns an EnonicError if it fails. createThymeleafParams
7. The function gathers all the data and creates one new object that the Thymeleaf-renderer
will take as input.
i18n for error messages
There is support for adding internationalization for error-messages. This is done, when you generate the ResponseerrorResponse({ req: Request, i18nPrefix: string})
using the 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.
`properties`
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.
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.
`properties`
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 separatestatus
different errors with the same (e.g both internal-server-error, missing-id-provider and publish-error
has status = 500).
`properties`
errors.title.400=Bad request error
errors.title.404=Not found
errors.title.500=Internal Server Error
errors.title.502=Bad gateway
`bash``
npm run build