This repository contains a simple example of a NodeJS Typescript Transformer.
The main.ts file is the entrypoint for the transformer. It contains the following endpoints:
This endpoint is used by the transformer shell to check if the transformer is healthy.
This endpoint is used by the transformer shell to transform data.
We try to simplify your development experience, by including a pipeline that will automatically test, build and push the release artifact to the GitHub release. However, if you wish to modify the GitHub Action workflow, or use your own, you are completely free to do so.
Before you can utilise our pre-built pipeline, you need to authenticate yourself with it. This is done by:
- generating a personal access token with the permission of creating artifacts.
- adding a
new repository secretto yourSettings > Secrets and variables > Actions, with the name ofRELEASE_GITHUB_TOKEN, and the value of your newly created personal token
You can follow our step-by-step video guide, if you are not accustomed to this process:
Automating the release process for your Transformer with GitHub Actions
We utilise Conventional Commits to automatically manage the versioning of your released artifacts. In short:
- prefixing your commits with
feat:will trigger a minor version (1.2.0) - prefixing your commits with
fix:will trigger a patch version (1.0.3)
As an example: feat: splitting email into username and domain, or fix: email now splits correctly by @ symbol
If you need anything more granular, then you can refer to the link above.
If using the correct conventional commit syntax, then the release process is as follows:
Anything that gets pushed to the main branch, will trigger a pull request; that runs tests to validate the release.
Once the pull request has been merged the release will be published, together with the artifact.
We have 2 recommended methods of working on your transformer.
Your choice may vary depending on your development environment, preference and/or complexity.
You can look at how you start the editor directly in your browser here.
Make your changes and push them to your repository. Bear in mind that you need to use conventional commits to be able to release your transformer. You can read more about it under Deployment.
Prerequisites:
- NodeJS
- Docker
And you must clone the project on to your machine
install dependencies:
yarn install && yarn buildrun the transformer shell
docker-compose -f test/docker/docker-compose.yaml up -dTo start developing with watch mode run:
yarn build:watchIn another terminal or tab, run:
yarn test:watchto run the tests on the built transformer.
When changes are made any of the files the transformer will be reloaded and the tests will be run again.
Note: The dist directory needs to be writable by the transformer shell.
To change the transformer, edit the transform.entrypoint.ts file. To add functionality on startup edit
the start.entrypoint.ts file. To add additional health checks edit the health.entrypoint.ts file.
To change the validation of inputs and outputs edit the test/expected.json file. This file specify the event payloads
that are sent to the transformer and the expected output. The :uuid: and :date: values for the expected outcome
matches to any string.
Change the test/app.spec.ts file to add additional tests and more advanced validation. Further change the files in
the src directory to add more advanced logic.
To use this transformer in the Flowcore platform, create a new adapter and point it to the github release artifact.
The shell will then download the artifact, run it and for each data point post to the transform endpoint.