Skip to content

Update the TypeScript SDK docs for Dags declared in TypeScript - #73875

Merged
jason810496 merged 5 commits into
apache:mainfrom
jason810496:docs/ts-sdk/native-dag-user-guide
Oct 9, 2026
Merged

jason810496 merged 5 commits into
apache:mainfrom
jason810496:docs/ts-sdk/native-dag-user-guide

Conversation

@jason810496

@jason810496 jason810496 commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Reorganizes the TypeScript SDK docs around its two ways of use, now that Dag definition in TypeScript is on main.

What

  • typescript.rst covers Dag definition first, then a Python Dag with stub TaskHandler: task inputs, task ids, options, order-only dependencies, task groups, dag.if, dag.switch, triggerDagRun, and deploying a bundle into a Dag bundle.
  • The language SDK overview is split the same way, and its table shows which SDKs support Dag definition.
  • The README, the API reference landing page and the example README follow the same shape.
import { Bundle, Dag } from "apache-airflow-ts-sdk";

const dag = new Dag("ts_etl", { schedule: "@daily", queue: "typescript" });

const extract = dag.task("extract", async (): Promise<number> => 42);
const load = dag.task("load", async ({ rows }: { rows: number }) => {});

load({ rows: extract() });

await new Bundle(dag).serve();

The README's compatibility matrix is generated from capabilities.yaml and is left alone.


Was generative AI tooling used to co-author this PR?

@jason810496
jason810496 force-pushed the docs/ts-sdk/native-dag-user-guide branch 2 times, most recently from b214e00 to 6987c6f Compare September 29, 2026 05:29
@jason810496
jason810496 marked this pull request as ready for review September 29, 2026 05:32

@pierrejeambrun pierrejeambrun left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. A few suggestions / questions

PR description mentions PR 73848 which doesn't exists, probably referring to #73844.

Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst Outdated
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst Outdated
Comment thread ts-sdk/README.md Outdated

@pierrejeambrun pierrejeambrun left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Meant to approve feel free to merge when those small comments are resolved.

@jason810496
jason810496 force-pushed the docs/ts-sdk/native-dag-user-guide branch from 6987c6f to 294e244 Compare September 29, 2026 12:14
@jason810496
jason810496 marked this pull request as draft September 29, 2026 12:19
@jason810496
jason810496 force-pushed the docs/ts-sdk/native-dag-user-guide branch 5 times, most recently from 2d3642d to 8f95813 Compare September 30, 2026 04:14
Describe the TypeScript SDK as it will be once the native Dag authoring
surface and native Dag parsing land: declaring a whole Dag in TypeScript,
and implementing mixed-language tasks, from one guide.
@jason810496
jason810496 force-pushed the docs/ts-sdk/native-dag-user-guide branch from 8f95813 to eb91ce4 Compare September 30, 2026 05:12
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/index.rst Outdated
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/index.rst Outdated
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/index.rst Outdated
jason810496 and others added 4 commits October 8, 2026 12:45
…dag-user-guide

Co-Authored-By: Claude <noreply@anthropic.com>
dag.if and dag.switch take the deciding handler and its inputs, and
triggerDagRun goes through dag.task and runs on Node.js, so Jinja in conf
is not rendered. The guide also picks up dag_bundle_to_coordinator, UTC
cron schedules, .airflowignore for handler-only bundles and the CLI
commands that refuse a TypeScript Dag. The overview marks Go as able to
declare Dags.

Co-Authored-By: Claude <noreply@anthropic.com>
"Native Dag" reads as jargon. Dag definition names the SDK feature, as a
reviewer suggested.

Co-Authored-By: Claude <noreply@anthropic.com>
A task is only ever written in one language: a Python Dag declares it as
a stub, and a TaskHandler in the SDK's language implements it.

Co-Authored-By: Claude <noreply@anthropic.com>

@jason810496 jason810496 left a comment •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review, I just address all the review comments.

Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst Outdated
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst Outdated
Comment thread ts-sdk/README.md Outdated
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/index.rst Outdated
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/index.rst Outdated
Comment thread airflow-core/docs/authoring-and-scheduling/language-sdks/index.rst Outdated
@jason810496
jason810496 marked this pull request as ready for review October 9, 2026 06:22
@jason810496
jason810496 merged commit 6e5d9dd into apache:main Oct 9, 2026
72 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants