This is an automated email from the ASF dual-hosted git repository.
jason810496 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new c03582f6618 TS SDK: Add if and switch to task groups (#75565)
c03582f6618 is described below
commit c03582f66181f2291e4d619e5250b054056f6c46
Author: Guan-Ming Chiu <[email protected]>
AuthorDate: Wed Nov 18 15:55:41 2026 +0000
TS SDK: Add if and switch to task groups (#75565)
* TS SDK: Add if and switch to task groups
* Address review comments
Signed-off-by: Guan-Ming (Wesley) Chiu
<[email protected]>
---------
Signed-off-by: Guan-Ming (Wesley) Chiu
<[email protected]>
---
.../language-sdks/typescript.rst | 4 +-
ts-sdk/src/sdk/dag.ts | 66 ++++++++++++++++------
ts-sdk/tests/public-api.test.ts | 2 +-
ts-sdk/tests/sdk/branching.test.ts | 16 ++++++
ts-sdk/tests/sdk/conditional.test.ts | 24 ++++++++
ts-sdk/tests/sdk/trigger-dag-run.test.ts | 13 +++++
6 files changed, 104 insertions(+), 21 deletions(-)
diff --git
a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst
b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst
index 3662d0171e9..d5976f6871a 100644
--- a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst
+++ b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst
@@ -306,8 +306,8 @@ to label the branches of ``dag.if`` or ``dag.switch`` (see
below):
Task groups
~~~~~~~~~~~
-``dag.taskGroup(groupId)`` opens a group with the same ``task`` and
``taskGroup`` methods as the Dag. Every id
-declared in it is prefixed with the group's, as in Python:
+``dag.taskGroup(groupId)`` opens a group with the same ``task``,
``taskGroup``, ``if`` and ``switch`` methods
+as the Dag. Every id declared in it is prefixed with the group's, as in Python:
.. code-block:: typescript
diff --git a/ts-sdk/src/sdk/dag.ts b/ts-sdk/src/sdk/dag.ts
index adf41236edd..5689a27e195 100644
--- a/ts-sdk/src/sdk/dag.ts
+++ b/ts-sdk/src/sdk/dag.ts
@@ -208,11 +208,11 @@ export interface TaskRef<TReturn = unknown> extends Node {
* A scope that declares tasks under a shared id prefix, and carries edges as a
* whole — Python's `TaskGroup`, spelled to TypeScript convention.
*
- * Offers the same `task` and `taskGroup` methods as the Dag, so nesting is the
- * same call at every depth. Each id it declares is prefixed with the group id
- * unless {@link TaskGroupOptions.prefixGroupId} turns that off, and the group
- * itself stands at either end of an edge, so a whole group can be ordered
- * against a task or against another group.
+ * Offers the same `task`, `taskGroup`, `if` and `switch` methods as the Dag,
+ * so nesting is the same call at every depth. Each id it declares is prefixed
+ * with the group id unless {@link TaskGroupOptions.prefixGroupId} turns that
+ * off, and the group itself stands at either end of an edge, so a whole group
+ * can be ordered against a task or against another group.
*/
export interface TaskGroupRef extends Node {
/** Identifier of the Dag this group belongs to. */
@@ -242,6 +242,16 @@ export interface TaskGroupRef extends Node {
): TaskFactory<TArgs, TResult>;
/** Nest a group inside this one. */
taskGroup(groupId: string, options?: TaskGroupOptions): TaskGroupRef;
+ /** Declare a condition in this group; its id is prefixed as a task's is. */
+ if<TArgs extends object | void = void>(
+ handler: (args: TArgs) => boolean | Promise<boolean>,
+ ...args: DeciderArgs<NoInfer<TArgs>>
+ ): Condition;
+ /** Declare a switch in this group; its id is prefixed as a task's is. */
+ switch<TArgs extends object | void = void>(
+ handler: (args: TArgs) => TaskRef | Promise<TaskRef>,
+ ...args: DeciderArgs<NoInfer<TArgs>>
+ ): Branch;
before(...downstream: readonly Node[]): TaskGroupRef;
after(...upstream: readonly Node[]): TaskGroupRef;
}
@@ -793,20 +803,30 @@ export class Dag {
handler: (args: TArgs) => boolean | Promise<boolean>,
...args: DeciderArgs<NoInfer<TArgs>>
): Condition {
- return this.#placeCondition(this.#placeDecider(handler, args) as
TaskRef<boolean>);
+ return this.#placeCondition("dag.if", undefined, handler, args);
}
- #placeDecider(handler: (args: never) => unknown, args: readonly unknown[]):
TaskRef {
+ #placeDecider(
+ groupId: string | undefined,
+ handler: (args: never) => unknown,
+ args: readonly unknown[],
+ ): TaskRef {
const [inputs, spec] = args as [unknown, TaskOptions | undefined];
- const factory = this.#addTask(undefined, handler, spec) as (...inputs:
unknown[]) => TaskRef;
+ const factory = this.#addTask(groupId, handler, spec) as (...inputs:
unknown[]) => TaskRef;
return inputs === undefined ? factory() : factory(inputs);
}
- #placeCondition(condition: TaskRef<boolean>): Condition {
+ #placeCondition(
+ method: string,
+ groupId: string | undefined,
+ handler: (args: never) => boolean | Promise<boolean>,
+ args: readonly unknown[],
+ ): Condition {
+ const condition = this.#placeDecider(groupId, handler, args) as
TaskRef<boolean>;
const taskId = condition.taskId;
const branches: ConditionRecord = {};
this.#conditions.set(taskId, branches);
- this.#wrapDecider("dag.if", taskId, async (held: unknown) => {
+ this.#wrapDecider(method, taskId, async (held: unknown) => {
if (typeof held !== "boolean") {
throw new Error(
`Condition "${taskId}" of Dag "${this.dagId}" returned
${describeValue(held)} ` +
@@ -822,7 +842,7 @@ export class Dag {
// `await` calls `then(resolve, reject)`, so a function here means the
condition was awaited.
if (typeof target === "function") {
throw new Error(
- `dag.if(...) of Dag "${this.dagId}" was awaited. It builds a branch
rather than ` +
+ `${method}(...) of Dag "${this.dagId}" was awaited. It builds a
branch rather than ` +
"doing work, so there is nothing to wait for; drop the await",
);
}
@@ -870,7 +890,7 @@ export class Dag {
}
#wrapDecider(
- verb: "dag.if" | "dag.switch",
+ method: string,
taskId: string,
decide: (returned: unknown) => Promise<{ skip: string[]; result: unknown
}>,
): void {
@@ -879,7 +899,7 @@ export class Dag {
if (record.fn === undefined) {
const { label, operatorName } = record.operator;
throw new Error(
- `A ${label ?? operatorName} task of Dag "${this.dagId}" was given to
${verb}, ` +
+ `A ${label ?? operatorName} task of Dag "${this.dagId}" was given to
${method}, ` +
"which needs a handler to decide the branch with",
);
}
@@ -903,7 +923,7 @@ export class Dag {
handler: (args: TArgs) => TaskRef | Promise<TaskRef>,
...args: DeciderArgs<NoInfer<TArgs>>
): Branch {
- return this.#placeBranch(this.#placeDecider(handler, args) as
TaskRef<TaskRef>);
+ return this.#placeBranch("dag.switch", undefined, handler, args);
}
#forwardEdges<T>(ref: TaskRef, self: () => T) {
@@ -919,11 +939,17 @@ export class Dag {
};
}
- #placeBranch(decider: TaskRef<TaskRef>): Branch {
+ #placeBranch(
+ method: string,
+ groupId: string | undefined,
+ handler: (args: never) => TaskRef | Promise<TaskRef>,
+ args: readonly unknown[],
+ ): Branch {
+ const decider = this.#placeDecider(groupId, handler, args) as
TaskRef<TaskRef>;
const taskId = decider.taskId;
const candidates: TaskRef[] = [];
this.#branches.set(taskId, candidates);
- this.#wrapDecider("dag.switch", taskId, async (chosen: unknown) => {
+ this.#wrapDecider(method, taskId, async (chosen: unknown) => {
const known = candidates.map((ref) => ref.taskId);
const picked = isTaskRef(chosen) && chosen.dagId === this.dagId ?
chosen.taskId : undefined;
if (picked === undefined || !known.includes(picked)) {
@@ -1242,6 +1268,10 @@ export class Dag {
) => this.#addTask<TArgs, TReturn>(groupId, taskIdOrHandler,
handlerOrOptions, maybeOptions),
taskGroup: (childId: string, options?: TaskGroupOptions) =>
this.#addGroup(groupId, childId, options),
+ if: (handler: (args: never) => boolean | Promise<boolean>, ...args:
readonly unknown[]) =>
+ this.#placeCondition(`taskGroup("${groupId}").if`, groupId, handler,
args),
+ switch: (handler: (args: never) => TaskRef | Promise<TaskRef>, ...args:
readonly unknown[]) =>
+ this.#placeBranch(`taskGroup("${groupId}").switch`, groupId, handler,
args),
before: (...downstream) => {
for (const other of downstream) this.#addOrderEdge(group, other,
"before");
return group;
@@ -1476,7 +1506,7 @@ export class Dag {
if (branches.whenTrue === undefined) {
throw new Error(
`Condition "${taskId}" of Dag "${this.dagId}" names no branch, so it
decides nothing; ` +
- "give it one with dag.if(handler, inputs).then(task)",
+ "give it one with .then(task)",
);
}
}
@@ -1484,7 +1514,7 @@ export class Dag {
if (cases.length === 0) {
throw new Error(
`Branch "${taskId}" of Dag "${this.dagId}" has no cases, so it
decides nothing; ` +
- "give it the tasks to choose between with dag.switch(handler,
inputs).case(task)",
+ "give it the tasks to choose between with .case(task)",
);
}
}
diff --git a/ts-sdk/tests/public-api.test.ts b/ts-sdk/tests/public-api.test.ts
index 980c4c3e205..ec24a41467b 100644
--- a/ts-sdk/tests/public-api.test.ts
+++ b/ts-sdk/tests/public-api.test.ts
@@ -333,7 +333,7 @@ describe("public API", () => {
// A group is a scope and an edge endpoint, and nests the same way at
// every depth.
expectTypeOf<Extract<keyof TaskGroupRef, string>>().toEqualTypeOf<
- "dagId" | "groupId" | "task" | "taskGroup" | "before" | "after"
+ "dagId" | "groupId" | "task" | "taskGroup" | "if" | "switch" | "before"
| "after"
>();
expectTypeOf<TaskGroupRef["groupId"]>().toEqualTypeOf<string>();
expectTypeOf<TaskGroupRef["taskGroup"]>().toEqualTypeOf<
diff --git a/ts-sdk/tests/sdk/branching.test.ts
b/ts-sdk/tests/sdk/branching.test.ts
index 9245b38b879..00d997153b2 100644
--- a/ts-sdk/tests/sdk/branching.test.ts
+++ b/ts-sdk/tests/sdk/branching.test.ts
@@ -22,6 +22,7 @@ import {
Dag,
finalizeDag,
getDagOrderEdges,
+ getDagTaskGroups,
getDagTaskInputs,
getDagTaskRecords,
Label,
@@ -183,6 +184,21 @@ describe("dag.switch", () => {
expect(getDagOrderEdges(dag)).toContainEqual({ upstream: "pick_path",
downstream: "notify" });
});
+ it("declares a switch in a task group, under the group's prefix", async ()
=> {
+ const dag = new Dag("d");
+ const long = dag.task("handle_long", async () => undefined)();
+ const short = dag.task("handle_short", async () => undefined)();
+ const pick = dag
+ .taskGroup("routing")
+ .switch(async () => long, undefined, { taskId: "pick_path" });
+ pick.case(long).case(short);
+
+ expect(pick.taskId).toBe("routing.pick_path");
+
expect(getDagTaskGroups(dag).get("routing")?.taskIds).toEqual(["routing.pick_path"]);
+ const { skipDownstreamTasks } = await runHandler(dag, "routing.pick_path");
+ expect(skipDownstreamTasks).toHaveBeenCalledWith(["handle_short"]);
+ });
+
it("is a branch of a condition, so a switch can sit under dag.if", () => {
const { dag, long, short, decider } = branchedDag();
decider.case(long).case(short);
diff --git a/ts-sdk/tests/sdk/conditional.test.ts
b/ts-sdk/tests/sdk/conditional.test.ts
index 71f8656ddc7..3080b3778d3 100644
--- a/ts-sdk/tests/sdk/conditional.test.ts
+++ b/ts-sdk/tests/sdk/conditional.test.ts
@@ -22,6 +22,7 @@ import {
Dag,
finalizeDag,
getDagOrderEdges,
+ getDagTaskGroups,
getDagTaskInputs,
getDagTaskRecords,
Label,
@@ -219,6 +220,29 @@ describe("dag.if", () => {
expect(getDagOrderEdges(dag)).toContainEqual({ upstream: "has_rows",
downstream: "notify" });
});
+ it("declares a condition in a task group, under the group's prefix", async
() => {
+ const dag = new Dag("d");
+ const ifReady = dag.task("load_if_ready", async () => undefined)();
+ const fallback = dag.task("load_fallback", async () => undefined)();
+ const gate = dag.taskGroup("checks").if(async () => true, undefined, {
taskId: "has_rows" });
+ gate.then(ifReady).else(fallback);
+
+ expect(gate.taskId).toBe("checks.has_rows");
+
expect(getDagTaskGroups(dag).get("checks")?.taskIds).toEqual(["checks.has_rows"]);
+ const { skipDownstreamTasks } = await runHandler(dag, "checks.has_rows");
+ expect(skipDownstreamTasks).toHaveBeenCalledWith(["load_fallback"]);
+ });
+
+ it("names the group method when a group's condition is awaited", async () =>
{
+ const gate = new Dag("d")
+ .taskGroup("checks")
+ .if(async () => true, undefined, { taskId: "has_rows" });
+
+ await expect(Promise.resolve(gate as unknown as
Promise<void>)).rejects.toThrow(
+ /taskGroup\("checks"\)\.if\(\.\.\.\) of Dag "d" was awaited/,
+ );
+ });
+
it("takes another condition as a branch", () => {
const { dag, ifReady, gated } = gatedDag();
const inner = dag.if(async () => true, undefined, { taskId: "is_weekday"
});
diff --git a/ts-sdk/tests/sdk/trigger-dag-run.test.ts
b/ts-sdk/tests/sdk/trigger-dag-run.test.ts
index ae3c3712cf1..019f1b2ac81 100644
--- a/ts-sdk/tests/sdk/trigger-dag-run.test.ts
+++ b/ts-sdk/tests/sdk/trigger-dag-run.test.ts
@@ -250,6 +250,19 @@ describe("triggerDagRun", () => {
);
});
+ it.each(["if", "switch"] as const)("a trigger task given to a task group's
%s", (decider) => {
+ const group = new Dag("d").taskGroup("routing");
+ const declare = group[decider] as (...args: unknown[]) => unknown;
+
+ expect(() =>
+ declare(triggerDagRun({ dagId: "downstream_etl" }), undefined, {
+ taskId: "trigger_downstream",
+ }),
+ ).toThrowError(
+ `A triggerDagRun task of Dag "d" was given to
taskGroup("routing").${decider}, which needs`,
+ );
+ });
+
it("a trigger task left uncalled, when the Dag is read", () => {
const dag = new Dag("d");
dag.task(triggerDagRun({ dagId: "downstream_etl" }), { taskId:
"trigger_downstream" });