pierrejeambrun opened a new issue, #76370: URL: https://github.com/apache/airflow/issues/76370
Airflow Dags are no longer Python only. Language SDKs for **Java**, **Go** and **TypeScript** let you declare a whole Dag (schedule, tasks, options and dependencies) in another language, or implement the stub tasks of a Python Dag in it. The TypeScript SDK ships with Airflow 3.4 (release candidates are out now) as the [`@apache-airflow/ts-sdk`](https://www.npmjs.com/package/@apache-airflow/ts-sdk) npm package, currently in beta. This issue collects community feedback on the **interface the TypeScript SDK exposes for authoring Dags**. The API is still in beta, so now is the time to change it. Please comment with what feels natural, what feels awkward, and what is missing for your use case. ## What it looks like A Dag declared entirely in TypeScript, with no Python file: <img src="https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/01-dag-code.png"; width="800" alt="A TypeScript Dag with a task group, typed task inputs and a dag.if branch" /> - `dag.task(...)` returns a factory, and calling it places the task in the Dag. Passing one task's result to another draws the dependency and moves the value as an XCom. - Task inputs are type checked. A misspelled or missing argument fails at compile time, not at parse time or run time: <img src="https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/03-type-check.png"; width="800" alt="tsc reporting a misspelled task input" /> ## Running it locally Install the SDK, build the Dag into a single bundle file, put it in a Dag bundle, and route a queue to the Node.js coordinator: <img src="https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/02-local-setup.png"; width="800" alt="npm install, airflow-ts-pack and the [sdk] configuration" /> The workers and the Dag processor need Node.js 22 or later. From there it is a regular Dag: it is scheduled, it shows up in the UI with its task group and branches, and each task runs on Node.js: <img src="https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/04-ui-graph.png"; width="800" alt="Graph view of a TypeScript Dag run" /> The **Code** tab shows the TypeScript source embedded in the bundle: <img src="https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/05-ui-code.png"; width="800" alt="Code view showing the TypeScript source" /> ## What is supported, and what is not yet Not every Airflow feature has a TypeScript form yet. Supported today: Dag and task arguments, TaskFlow-style inputs, `before` / `after` dependencies, edge labels, task groups, `dag.if` and `dag.switch` branching, `triggerDagRun`, human-in-the-loop (`approval()` / `hitl()`), and Variables, Connections, XComs and the task state store from task code. Still to come, among others: task loops, dynamic task mapping, Dag params, Dag and task callbacks, assets (definition, scheduling, inlets and outlets), and `airflow dags test`. Until then, a Dag that needs one of these can be declared in Python, with its tasks implemented in TypeScript through `@task.stub`. The [compatibility matrix](https://airflow.staged.apache.org/docs/apache-airflow/3.4.0/authoring-and-scheduling/language-sdks/index.html#compatibility-matrix) tracks what each SDK supports, for Java, Go and TypeScript side by side. ## Feedback we are looking for Anything is welcome. These are the questions we would most like answers to: 1. **Wiring tasks.** Does calling a task factory with other tasks' results feel natural for declaring dependencies? Is `before` / `after` a good TypeScript equivalent of `>>` / `<<`? 2. **Naming and shape.** `dag.task`, `dag.taskGroup`, `dag.if(...).then(...).else(...)`, `dag.switch(...).case(...)`, `Label.of(text).on(task)`, task ids taken from function names: anything you would name or structure differently? 3. **Options.** Dag and task options are Airflow's own arguments in camelCase (`retryDelay`, `triggerRule`, ...). Does that work for you, or would you expect something more idiomatic? 4. **Type safety.** What else should the compiler catch for you? 5. **Build and deploy.** Is building one bundle file with `airflow-ts-pack` and dropping it in a Dag bundle a good fit for how you ship TypeScript? 6. **Missing features.** Which of the features above would you need first to use it for real? Short code snippets of what you would like to write are the most useful kind of feedback. ## Links - [TypeScript SDK guide](https://airflow.staged.apache.org/docs/apache-airflow/3.4.0/authoring-and-scheduling/language-sdks/typescript.html) - [TypeScript SDK API reference](https://airflow.staged.apache.org/docs/ts-sdk/stable/) - [Language SDKs overview](https://airflow.staged.apache.org/docs/apache-airflow/3.4.0/authoring-and-scheduling/language-sdks/index.html), with the [Java](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/language-sdks/java.html) and [Go](https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/language-sdks/go.html) guides - [Example Dags](https://github.com/apache/airflow/tree/main/ts-sdk/example) and the [SDK sources](https://github.com/apache/airflow/tree/main/ts-sdk) The 3.4 documentation links point to the staged site and move to airflow.apache.org once 3.4.0 is released. --- Drafted-by: Claude Code (Opus 5.5) (no human review before posting) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
![https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/01-dag-code.png"](https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/01-dag-code.png"){kind=link}
![https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/03-type-check.png"](https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/03-type-check.png"){kind=link}
![https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/02-local-setup.png"](https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/02-local-setup.png"){kind=link}
![https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/04-ui-graph.png"](https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/04-ui-graph.png"){kind=link}
![https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/05-ui-code.png"](https://raw.githubusercontent.com/astronomer/airflow/3681c6c779423991c5fb059f24e219f5364fbbb2/ts-sdk-feedback/05-ui-code.png"){kind=link}