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" });

Reply via email to