1.4.1 β€’ Published 4 months ago

jobar v1.4.1

Weekly downloads
-
License
MIT
Repository
-
Last release
4 months ago

Jobar

Temporal

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:

OptionTypeDescription
workflowStartOptionsWorkflowStartOptionsWorkflow startup options See related doc
setWorkflowId(req: Request) => stringFunction to define a unique workflow identifier based on the request
isExposedbooleanIndicates 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
endpointstringEndpoint URL Required if isExposed is true
prefixUrlstringEndpoint URL prefix Default: /tasks
needWorkflowFullRequestbooleanGive 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:

OptionTypeDescription
getDataConverter() => Promise<DataConverter>Allows using a custom data converter (e.g., encryption) See related documentation
connectionOptionsConnectionOptionsTemporal connection options See related documentation
clientOptionsClientOptionsTemporal 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:

OptionTypeDescription
appExpressExpress application instance
workflowsPathstringPath to workflows
temporalAddressstringTemporal server address
loggerLoggerWinston logger instance Default: Logger Winston default
logLevelstringLogging level (debug, info, error, etc.) Default: debug
namespacestringNamespace used in Temporal Default: default
defaultStatusCodeErrornumberDefault HTTP error code Default: 500
onRequestErrorRequestErrorFunctionDefault 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


πŸ“ 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


πŸ“· AperΓ§u du Dashboard Temporal

Temporal Dashboard

1.4.1

4 months ago

1.4.0

5 months ago

1.3.1

5 months ago

1.3.0

5 months ago

1.2.15

5 months ago

1.2.14

5 months ago

1.2.13

5 months ago

1.2.12

5 months ago

1.2.11

5 months ago

1.2.10

5 months ago

1.2.9

5 months ago

1.2.8

5 months ago

1.2.6

5 months ago

1.2.5

5 months ago

1.2.4

5 months ago

1.2.3

5 months ago

1.2.2

5 months ago

1.2.1

5 months ago

1.2.0

5 months ago

1.1.2

5 months ago

1.1.1

5 months ago

1.1.0

5 months ago

1.0.15

5 months ago

1.0.14

5 months ago

1.0.13

5 months ago

1.0.10

5 months ago

1.0.7

5 months ago

1.0.5

5 months ago

1.0.0

5 months ago