Apache Airflow TypeScript SDK

The Apache Airflow TypeScript SDK provides the public TypeScript interfaces for writing Apache Airflow task handlers and the coordinator runtime that executes registered TypeScript handlers from an Airflow worker.

Note This package is 0.1.0-beta1: the API may change, it requires Node 22+, and it is ESM-only.

Getting Started

Install the beta package from npm:

npm install apache-airflow-ts-sdk@0.1.0-beta1

Bind a handler to the Python-owned task it implements, register it on a Bundle, and serve it. A handler is a plain function: getContext() returns the TaskContext and getClient() the TaskClient for as long as it runs, so neither is a parameter. Any non-undefined return value is pushed to XCom under the "return_value" key by the active runtime, matching Python @task behavior:

import { Bundle, getClient, getContext, TaskHandler } from "apache-airflow-ts-sdk";

export async function sayHello() {
  const greeting = await getClient().getVariable("greeting");
  return { message: `Hello from ${getContext().taskId}: ${greeting}` };
}

const bundle = new Bundle();
bundle.register(new TaskHandler("example_dag", "say_hello", sayHello));
await bundle.serve();

register takes any number of items, so one bundle can provide for several TaskHandlers.

When the Python Dag calls a stub task TaskFlow-style, those arguments reach the handler by name. Names bind by folding on both sides, lowercased with underscores removed, so a Python region_code reaches a handler's regionCode with nothing declared:

interface TransformArgs {
  regionCode: string;
  threshold: number;
}

export async function transform({ regionCode, threshold }: TransformArgs) {
  // ...
}

withArgNames states a binding folding cannot reach, for a name the Python side never used. It should be rare, since folding covers ordinary spelling differences.

Dag is another interface, for a Dag declared in TypeScript rather than in Python, and is still a work in progress.

Coordinators

Airflow runs TypeScript task bundles through the Python-side NodeCoordinator (airflow.sdk.coordinators.node.NodeCoordinator). A Python Dag declares the scheduling shape with stub tasks and owns the task dependencies between them, and the TypeScript module registers handlers with matching task IDs. See the Non-Python Task SDKs guide for the conceptual overview of language SDKs.

API Reference

The reference is generated directly from the TypeScript sources with TypeDoc. Use the sidebar or the search box to browse the API.