jobar v1.4.1
Jobar
Jobar is a TypeScript library that allows orchestrating workflows with Temporal and exposing them easily via an Express API.
π Installation
For the best project structure, we recommend using the following command:
npm create jobar-app@latest my-app
You can now test it easily with Docker:
cd my-app && docker compose up -d
For classic installation
npm install jobar
# or
yarn add jobar
π Features
- π Simplified workflow management with Temporal.io
- π Creation and execution of tasks in dedicated queues
- π Secure data encoding and decoding via an encryption codec
- π Built-in logger with Winston for detailed event tracking
- π Task exposure on HTTP routes using Express
- π§ͺ Comprehensive unit testing with Mocha
- π οΈ Modular and extensible architecture
π Key Concepts
Workflow
A Workflow is a durable function executed by Temporal. It is responsible for orchestrating tasks and managing states.
Example of a Workflow:
import {Request} from 'express';
import {proxyActivities} from '@temporalio/workflow';
import activities from '../activities';
const {hardcodedPasswordLogin} = proxyActivities<typeof activities>({
startToCloseTimeout: '1 minute',
retry: {maximumAttempts: 3},
});
type LoginInput = {username: string; password: string};
export async function login(requestBody: LoginInput, requestHeaders: Request['headers']): Promise<string> {
return await hardcodedPasswordLogin(requestBody.username, requestBody.password);
}
Activity
An Activity is a function that performs a specific operation within a Workflow. Activities can interact with databases, external services, or perform complex computations.
Example of an Activity:
import {JobarError} from 'jobar';
export async function hardcodedPasswordLogin(username: string, password: string): Promise<string> {
if (password !== 'temporal') {
throw Jobar.error('Bad Credentials', {
statusCode: 401,
error: 'Unauthorized',
details: {
password: 'Invalid',
username: 'OK',
},
});
}
return `Hello, ${username} !`;
}
Task
A Task represents a unit of work associated with a Temporal workflow. It can be configured with various options and exposed via an Express API.
Available Options:
Option | Type | Description |
---|---|---|
workflowStartOptions | WorkflowStartOptions | Workflow startup options See related doc |
setWorkflowId | (req: Request) => string | Function to define a unique workflow identifier based on the request |
isExposed | boolean | Indicates if the task should be exposed via an Express API Default: false |
method | 'get', 'post', 'put', 'patch', 'delete' | HTTP method of the endpoint Required if isExposed is true |
endpoint | string | Endpoint URL Required if isExposed is true |
prefixUrl | string | Endpoint URL prefix Default: /tasks |
needWorkflowFullRequest | boolean | Give to the workflow the express Request and Response in arguments instead of Body and Headers Default: false |
Usage Example:
import {Request} from 'express';
import {Task} from 'jobar';
import {login} from '../workflows';
const exampleTask = new Task(login, {
setWorkflowId: (req: Request) => `workflow-login-${req.body.username}`,
isExposed: true,
method: 'post',
endpoint: 'login',
});
TaskQueue
A TaskQueue is a queue grouping multiple Task
instances. Each queue is associated with a Worker
that executes the workflows.
Available Options:
Option | Type | Description |
---|---|---|
getDataConverter | () => Promise<DataConverter> | Allows using a custom data converter (e.g., encryption) See related documentation |
connectionOptions | ConnectionOptions | Temporal connection options See related documentation |
clientOptions | ClientOptions | Temporal client options See related documentation |
Usage Example:
import {TaskQueue, getDataConverter} from 'jobar';
const exampleTaskQueue = new TaskQueue('example', {
getDataConverter, // Default data encryption for Temporal Codec
}).addTask(exampleTask);
Jobar
Jobar is the central engine that orchestrates workflows, connects workers to Temporal, and exposes tasks via an Express API.
Available Options:
Option | Type | Description |
---|---|---|
app | Express | Express application instance |
workflowsPath | string | Path to workflows |
temporalAddress | string | Temporal server address |
logger | Logger | Winston logger instance Default: Logger Winston default |
logLevel | string | Logging level (debug , info , error , etc.) Default: debug |
namespace | string | Namespace used in Temporal Default: default |
defaultStatusCodeError | number | Default HTTP error code Default: 500 |
onRequestError | RequestErrorFunction | Default HTTP onError Default: onRequestErrorDefault |
Usage Example:
# src/index.ts
import express from 'express';
import Jobar from 'jobar';
import exampleTaskQueue from './tasks/example';
import activities from './activities';
const app = express();
app.use(express.json());
const jobar = new Jobar({
app,
workflowsPath: require.resolve('./workflows'),
temporalAddress: 'localhost:7233',
});
jobar.addTaskQueue(exampleTaskQueue).run({activities});
app.listen(3000, () => console.log('Server running on port 3000'));
π Recommended Project Structure
You can use this model as a framework
your-project/
βββ src/
β βββ activities/ # Activity management
β | βββ index.ts # Export all activities in a default variable named `activities`
β βββ tasks/ # Task and queue management
β βββ workflows/ # Workflow management
β | βββ index.ts # Export all workflows visible through the `workflowsPath` option
β βββ index.ts # Entry point
π» Usage Example
Find examples in the official repository π Github Examples
π Links
- π¦ NPM
- π GitHub
- π GitHub Examples
- π¦ GitLab
- π¦ GitLab Examples
- π Temporal TypeScript SDK Documentation
- π¦ NPM Create Jobar App
- π GitHub Create Jobar App
- π¦ GitLab Create Jobar App
π Contributing
Contributions are welcome!
- Fork the repository
- Create a feature branch:
git checkout -b feature-my-feature
- Commit your changes:
git commit -m 'Add my feature'
- Push to the branch:
git push origin feature-my-feature
- Open a Pull Request π
π Contact
- π¨π»βπ» William Donnette
π· AperΓ§u du Dashboard Temporal
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago