j8s

A lightweight service orchestration framework for JavaScript/TypeScript. Run multiple services in a single process using worker threads.

GitHub: https://github.com/HuakunShen/j8s
JSR: https://jsr.io/@hk/j8s

Features

Run services in main thread or worker threads
Health checks for all services
Restart policies (always, unless-stopped, on-failure, no)
Run services on a schedule (cron jobs)
Timeout support for services
Communication between worker and main thread using RPC
Built-in REST API with OpenAPI documentation

Installation

# Deno
deno add @hk/j8s

# Bun
bunx jsr add @hk/j8s

# npm
npx jsr add @hk/j8s

Basic Usage

Main Thread Service

import { BaseService, ServiceManager } from "j8s";

class MyService extends BaseService {
  async start(): Promise<void> {
    console.log("Service started");
  }

  async stop(): Promise<void> {
    console.log("Service stopped");
  }

  async healthCheck() {
    return { status: "running", details: {} };
  }
}

const manager = new ServiceManager();
const service = new MyService("my-service");
manager.addService(service, { restartPolicy: "always" });
await manager.startService(service);

Worker Thread Service

import { ServiceManager, createWorkerService } from "j8s";

const workerService = createWorkerService(
  "worker-service",
  new URL("./worker.ts", import.meta.url),
  {
    workerData: { config: { maxRetries: 5 }, initialState: "idle" },
  },
);

const manager = new ServiceManager();
manager.addService(workerService, {
  restartPolicy: "on-failure",
  maxRetries: 3,
});
await manager.startService(workerService);

Cron Jobs

class BackupService extends BaseService {
  async start(): Promise<void> {
    console.log("Running backup...");
    // Backup logic
  }
}

const backupService = new BackupService("backup-service");
manager.addService(backupService, {
  cronJob: {
    schedule: "0 0 * * *", // Midnight every day
    timeout: 60000,
  },
});

REST API

import { serve } from "@hono/node-server";
import { ServiceManager, createServiceManagerAPI } from "j8s";

const manager = new ServiceManager();
// Add services...

const app = createServiceManagerAPI(manager, {
  openapi: { enabled: true },
  scalar: { enabled: true },
});

serve({ fetch: app.fetch, port: 3000 });

API Endpoints

GET /services - List all services
GET /services/:name - Get service details
GET /services/:name/health - Get health for a service
POST /services/:name/start - Start a service
POST /services/:name/stop - Stop a service
POST /services/:name/restart - Restart a service
DELETE /services/:name - Remove a service

Use Cases

Microservices orchestration
Background job workers
Scheduled tasks
Service health monitoring
Multi-service desktop applications

A JavaScript service orchestration framework inspired by Kubernetes.

j8s

On this page