Node.js SDK

TaskDaemon node.js sdk guide

Node.js SDK

The Node.js SDK for writing TaskDaemon handlers.

Installation

Install the published npm package from your handler application’s directory:

npm install --save-exact @taskdaemon/handler@0.1.2

For TypeScript, also install the compiler and Node.js types:

npm install --save-dev typescript @types/node

Commit the generated package-lock.json and include it with package.json in the Docker build context. The Dockerfiles below use the registry dependency and install from this lockfile.

For a local source build from the same release:

git clone --branch v0.1.2 --depth 1 https://github.com/jona62/TaskDaemon-Handlers.git vendor/TaskDaemon-Handlers
npm ci --prefix vendor/TaskDaemon-Handlers/nodejs
npm pack ./vendor/TaskDaemon-Handlers/nodejs --pack-destination ./vendor
npm install ./vendor/taskdaemon-handler-0.1.2.tgz

For a source-based Docker build, copy this archive into the same vendor path before running npm ci.

Keep diagnostic logs on stderr; the handler protocol uses stdout for one response per task. A request starts with attempt: 1; retries require a valid retryable error and remaining stored budget.

Basic Usage

import { run, success, error, Task } from '@taskdaemon/handler';

function handler(task: Task) {
  const name = task.task_data.name || 'World';
  return success({ message: `Hello, ${name}!` });
}

run(handler);

Task Interface

interface Task {
  task_id: string;
  task_type: string;
  task_data: Record<string, unknown>;
  attempt: number;  // Current attempt (starts at 1)
}

Return Types

The SDK provides helper functions for creating results:

// Success with result
return success({ processed: true, count: 42 });

// Non-retryable error (default)
return error("Invalid input");

// Retryable error
return error("Service unavailable", true);

Or construct the result object directly:

type Result =
  | { status: 'success'; result: unknown }
  | { status: 'error'; error: string; retryable: boolean };

Async Handlers

Handlers can be async. Install axios for this example:

npm install axios

import { run, success, error, Task } from '@taskdaemon/handler';
import axios from 'axios';

async function handler(task: Task) {
  try {
    const response = await axios.get(task.task_data.url as string);
    return success({ data: response.data });
  } catch (e) {
    return error(String(e), true);  // Retryable
  }
}

run(handler);

Complete Example

Install sharp and axios, and use a TypeScript build configured for Node and default imports (for example esModuleInterop: true):

npm install sharp axios
npm install --save-dev typescript @types/node

import { run, success, error, Task } from '@taskdaemon/handler';
import sharp from 'sharp';
import axios from 'axios';

async function resizeImage(task: Task) {
  try {
    const { image_url, width, height } = task.task_data as {
      image_url: string;
      width: number;
      height: number;
    };

    // Download image
    const response = await axios.get(image_url, { responseType: 'arraybuffer' });

    // Resize
    const resized = await sharp(response.data)
      .resize(width, height)
      .png()
      .toBuffer();

    // Encode
    const b64 = resized.toString('base64');

    return success({
      data: b64,
      size: [width, height],
      format: 'png'
    });
  } catch (e) {
    return error(String(e));
  }
}

run(resizeImage);

Error Handling

Uncaught exceptions are automatically converted to non-retryable errors:

function handler(task: Task) {
  // If this throws, it becomes { status: 'error', error: '...', retryable: false }
  const value = task.task_data.required_field;
  return success({ value });
}

Dockerfile

FROM node:20-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci

COPY handler.ts ./
RUN npx --no-install tsc handler.ts --target ES2020 --module commonjs --esModuleInterop

CMD ["node", "handler.js"]

Or for JavaScript:

FROM node:20-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

COPY handler.js ./

CMD ["node", "handler.js"]

Handler Configuration

[handlers.process]
image = "node-handler:latest"
instances = 4
timeout = 30