TS SDK: default a task id to the handler's name

A native Dag handler takes one object of named arguments, and a call names
each input. withArgList(...) supplies the same inputs in the order the
handler destructures them, zipped with the keys read off its argument
pattern, so nothing labels an argument arg0.

The task id still defaults to the handler's function name, which is why
airflow-ts-pack passes esbuild's keepNames; argument names are property
names, which minification leaves alone, so the pack step minifies
identifiers again.

Author: jason810496

airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst

@@ -247,8 +247,8 @@ A ``Dag`` is declared on this side rather than in Python: its schedule, its task
 the edges between them are all written in TypeScript. The surface is still growing, so a Dag declared
 this way is not served to Airflow yet.
 
-``dag.task(taskId, handler)`` returns a *factory*. Calling it places the task in the Dag and supplies the
-handler's arguments, so the call graph is the task graph:
+``dag.task(taskId, handler)`` returns a *factory*. A handler takes one object of named arguments, and
+calling the factory names each input, so the call graph is the task graph:
 
 .. code-block:: typescript
 
@@ -257,26 +257,50 @@ handler's arguments, so the call graph is the task graph:
     const dag = new Dag("ts_etl");
 
     const extract = dag.task("extract", async (): Promise<number> => 42);
-    const transform = dag.task("transform", async (rows: number, region: string) => rows * 2);
-    const load = dag.task("load", async (total: number) => {});
+    const transform = dag.task(
+      "transform",
+      async ({ rows, region }: { rows: number; region: string }) => rows * 2,
+    );
+    const load = dag.task("load", async ({ total }: { total: number }) => {});
 
-    load(transform(extract(), "us"));
+    const extracted = extract();
+    const total = transform({ rows: extracted, region: "us" });
+    load({ total });
 
-Arguments are passed in the order the handler declares them. A handler that declares a single object of
-named arguments can also be called with that object, which names each input instead of ordering it:
+Naming the inputs is how a task is called. A handler that takes no arguments is called with none, and
+a single argument is named like any other, ``load({ total })``.
+
+``withArgList`` supplies the same inputs in order, for a call that reads better that way:
 
 .. code-block:: typescript
 
-    const store = dag.task("store", async ({ total }: { total: number }) => {});
+    import { withArgList } from "apache-airflow-ts-sdk";
+
+    transform(withArgList(extracted, "us"));
 
-    store({ total: extract() });
+Each value binds to the argument in that position, and the order is the one the handler destructures
+its argument in, so the handler has to take a plain object pattern. A named call is the one the
+compiler checks in full: it reports an argument left out, a misspelled one, and a literal of the
+wrong type.
 
 Each argument takes either an upstream reference or a literal JSON value. A reference has to be the
 argument itself: one buried inside an array or an object is a literal, and draws no edge.
 
 Every task has to be called exactly once. An uncalled task fails when the Dag is read, so none can be
 left out of the graph by accident.
 
+The task id may be omitted, in which case it is the handler's function name:
+
+.. code-block:: typescript
+
+    const extract = dag.task(async function extract(): Promise<number> {
+      return 42;
+    });
+
+``airflow-ts-pack`` keeps function names intact, so bundling cannot rename a task. A handler with no
+name of its own, such as an arrow function passed inline, has nothing to take an id from and needs
+one: either positionally or as ``taskId`` in its spec. Give it in one place only, not both.
+
 ``new Dag`` and ``dag.task`` both take a trailing spec of Airflow options:
 ``{ schedule: "@daily", tags: ["etl"] }`` for the Dag, ``{ retries: 2, retryDelay: 30 }`` for a task.
 
@@ -398,9 +422,8 @@ layout header. The layout records the byte ranges and SHA-256 digests of the man
 so there is one file to deploy, with no separate manifest or ``node_modules``.
 
 The code is minified because an integrity digest is only worth taking over an artifact nobody is expected to
-read or edit in place. The ``/*! */`` license banners of bundled dependencies are kept. Nothing is identified by
-a function name, so minified names are safe: a Dag and a task are named by the string ids their registration
-states, and a handler is dispatched by reference.
+read or edit in place. Function names are kept through minification, since a task id defaults to its
+handler's name. The ``/*! */`` license banners of bundled dependencies are kept.
 
 Because the shipped code is not the code anyone wrote, the packer also embeds the entry module verbatim in a
 ``/*# airflowSource ... #*/`` block comment, verified by its own digest, so Airflow has something readable to

ts-sdk/adr/0002-native-dag-interface.md

@@ -27,16 +27,15 @@ Proposed. Revised after the review on #72047.
 
 1. **`dag.task(handler)` returns a factory, and the task id is optional.** With no id the task takes
    the handler's function name (`dag.task(extract)` → task `"extract"`); `dag.task(taskId, handler)`
-   sets it explicitly, which an anonymous handler must do. Calling the factory both places the task in
-   the Dag and supplies its arguments, in the order the handler declares them
-   (`load(transform(extract(), "us"))`). A handler that declares a single object of named arguments can
-   also be called with that object — the shape Python TaskFlow uses for
-   `load(transformed=transform(...))`.
-2. **The call graph is the task graph.** `tsc` checks every wired key against the handler's own
-   parameter type, and a `TaskRef` exists only once its producing call has returned, so a cycle
-   through arguments is unrepresentable rather than rejected by a validator. A reference passed by
-   position is checked against the argument's own type, which is what tells the two call shapes apart
-   when a handler declares a single argument.
+   sets it explicitly, which an anonymous handler must do. A handler takes one object of named
+   arguments, and calling the factory both places the task in the Dag and names each of its inputs
+   (`load({ total: transform({ rows: extract(), region: "us" }) })`) — the shape Python TaskFlow uses
+   for `load(transformed=transform(...))`. `withArgList(...)` supplies the same inputs in the order
+   the handler destructures them, for a call that reads better that way.
+2. **The call graph is the task graph.** `tsc` checks every named input against the handler's own
+   argument type, and a `TaskRef` exists only once its producing call has returned, so a cycle
+   through arguments is unrepresentable rather than rejected by a validator. A listed call is checked
+   by value type, and which argument each value supplies is the position it was given in.
 3. **Every task is called exactly once.** An uncalled task fails when the Dag is read, so none can be
    silently left out of the graph.
 4. **`before` and `after` draw order-only edges** — the TypeScript pair for `>>` and `<<`, both
@@ -149,20 +148,20 @@ convention.
   by design. Native declaration is what fills them, generated from the serialized-Dag JSON schema the
   way `src/generated/supervisor.ts` is. This ADR does not choose those fields; it fixes where an
   author writes them.
-- `TaskOptions` carries the spec and the handler's positional argument names, which the packer fills in
-  from the parameter list so the Dag names each argument as its handler does. With wiring moved to the
-  factory call, `inputs` is no longer an option.
+- `TaskOptions` carries the task's spec and nothing else: the names on the wire are the keys of the
+  call itself. With wiring moved to the factory call, `inputs` is no longer an option.
 - `TaskHandlerArgs` is removed from the public API, `DagRegistry` becomes `Bundle`, and
   `serveDags(registry)` becomes `bundle.serve()`, which breaks
   0.1.0-beta1 authors; see [ADR-0001](0001-mixed-lang-dag-interface.md) for the shipped call sites
   that change.
 
 ## Alternatives
 
-- **Named-only wiring**, rejected in the review on #73435: naming every input reads well at twenty
-  tasks but forces an object around a single argument, and positional calls are what TypeScript
-  authors write. Both are offered, and the handler's own parameter list decides which one a task can
-  use.
+- **Positional handlers**, `async (rows: number, region: string) => ...`, offered first and then
+  dropped: a positional parameter list has no names on the wire unless the SDK reads them out of the
+  handler's source, and a single object of named arguments is what a TypeScript library takes
+  anyway. The handler is object-only, and `withArgList(...)` keeps the positional call site for the
+  cases that read better in order.
 - **Injected `ctx`/`client` arguments**, mimicking the Python signature. Rejected, per the above and
   because feeling native to TypeScript matters more than matching Python's parameter list.
 
@@ -181,17 +180,19 @@ convention.
 - **The spec argument already has its slot.** `dag.task(taskId, handler, options)` reads `{ spec = {} }`
   and runs `validateEmptySpec` on it (`ts-sdk/src/sdk/dag.ts`), so task fields land on a path that
   exists rather than a new one.
-- **A positional argument binds by order, and its name is a label.** The serialized Dag names each
-  argument, so the packer reads the names from the handler's parameter list; `arg0`, `arg1` and so on
-  stand in for a name it cannot see, without changing which value reaches which argument.
+- **A listed call binds by order, and the names still come from the handler.** The serialized Dag
+  names every argument, so `withArgList(...)` is zipped with the keys the handler destructures, read
+  off its argument pattern at the call. A pattern that cannot be read that way, such as one with a
+  default or a rest element, is refused rather than guessed at, and its task is called by name.
 - **A `TaskRef` is inert** — a handle for wiring, not a promise. Nothing in a Dag file executes a task
   body.
-- **A defaulted task id is resolved at pack time, not read at runtime.** esbuild renames function
-  identifiers, so `handler.name` in a packed bundle is the minified name, not the author's. The pack
-  step (`ts-sdk/src/cli/pack.ts`) therefore reads an omitted id from the handler's declared name in
-  source and writes it into the registration, rather than depending on `handler.name` or enabling
-  esbuild's `keepNames` across the whole bundle. A handler with no source name leaves nothing to
-  read, which is why an anonymous handler must state its id.
+- **A defaulted task id is read off the handler itself.** The pack step (`ts-sdk/src/cli/pack.ts`)
+  minifies and passes esbuild's `keepNames`, so `handler.name` is the author's in a packed bundle as
+  much as in one run from source; an argument name is a property name, which minification leaves
+  alone. Rewriting the call at pack time was tried first and dropped: it needed a TypeScript parser
+  in the packer to tell a real `.task(` from one inside a string or a comment, and it could not see a
+  handler declared in another module. A handler with no name leaves nothing to read, which is why an
+  anonymous handler must state its id.
 - **`withArgNames` and the name folding behind it** ([ADR-0001](0001-mixed-lang-dag-interface.md))
   exist for the mixed-language case and are never needed here: both ends of every name are
   TypeScript, so `tsc` checks the wiring end to end and there is no foreign name to reconcile.

ts-sdk/api-docs/dag-authoring-api.ts

@@ -19,8 +19,17 @@
 
 /** @module Authoring */
 
-export { Bundle, Dag, getClient, getContext, TaskHandler, withArgNames } from "../src/index.js";
+export {
+  Bundle,
+  Dag,
+  getClient,
+  getContext,
+  TaskHandler,
+  withArgList,
+  withArgNames,
+} from "../src/index.js";
 export type {
+  ArgList,
   ArgNameMap,
   DagSpec,
   Registerable,

ts-sdk/src/cli/pack.ts

@@ -215,8 +215,12 @@ export async function runPack(argv: readonly string[]): Promise<void> {
       platform: "node",
       format: "esm",
       target: "node22",
-      // A digest is only worth taking over an artifact nobody reads or edits in place.
       minify: true,
+      // A task id comes from the handler's name, and bundling renames a symbol
+      // that two modules both declare, so the name the SDK reads is pinned to
+      // the one the author wrote. Argument names are property names, which
+      // minification leaves alone.
+      keepNames: true,
       // The manifest is read by running the staged bundle, so the metadata describes what ships.
       outfile: stagingPath,
     });

ts-sdk/src/index.ts

@@ -20,15 +20,16 @@
 export { Dag } from "./sdk/dag.js";
 export { Bundle } from "./sdk/bundle.js";
 export { TaskHandler } from "./sdk/task-handler.js";
+export { withArgList } from "./sdk/arg-list.js";
 export { withArgNames } from "./sdk/arg-names.js";
 export { getClient, getContext } from "./sdk/task.js";
 export { ConnectionNotFoundError, VariableNotFoundError } from "./sdk/client.js";
 export { SUPERVISOR_API_VERSION } from "./coordinator/index.js";
+export type { ArgList } from "./sdk/arg-list.js";
 export type { ArgNameMap } from "./sdk/arg-names.js";
 export type { Registerable } from "./sdk/bundle.js";
 export type {
   DagSpec,
-  PositionalInputs,
   TaskFactory,
   TaskInput,
   TaskInputs,

ts-sdk/src/sdk/arg-list.ts

@@ -0,0 +1,82 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Giving a task's inputs in order instead of by name.
+
+import { brand, hasBrand } from "./brand.js";
+
+// Not a declared field, so the values stay out of the public type: an arg list
+// is a carrier the Dag reads, never something an author takes apart. A global
+// symbol, as the brands are, so two resolved copies agree on the key.
+const VALUES = Symbol.for("airflow.ts-sdk.arg-list-values");
+
+// Carries the value types without carrying a value, the way TaskRef carries
+// its return type.
+declare const LISTED_VALUES: unique symbol;
+
+/**
+ * A task's inputs in the order its handler destructures them, as
+ * {@link withArgList} builds.
+ */
+export interface ArgList<TValues extends readonly unknown[] = readonly unknown[]> {
+  /** @internal Never set; see {@link LISTED_VALUES}. */
+  readonly [LISTED_VALUES]: TValues;
+}
+
+/**
+ * Give a task's inputs in order instead of naming them.
+ *
+ * Naming the inputs is the usual way to call a task, and reads best past a
+ * couple of arguments:
+ *
+ * ```ts
+ * transform({ rows: extracted, region: "us" });
+ * ```
+ *
+ * `withArgList` supplies the same inputs in order, for a call that reads
+ * better that way. Each value binds to the argument in that position:
+ *
+ * ```ts
+ * transform(withArgList(extracted, "us"));
+ * ```
+ *
+ * The order is the one the handler destructures its argument in, so the
+ * handler has to take a plain object pattern — `async ({ rows, region }) =>
+ * ...`. A handler written any other way has no order to read, and its task is
+ * called by name.
+ */
+export function withArgList<const TValues extends readonly unknown[]>(
+  ...values: TValues
+): ArgList<TValues> {
+  const list = {};
+  Object.defineProperty(list, VALUES, { value: Object.freeze([...values]) });
+  brand(list, "ArgList");
+  return Object.freeze(list) as ArgList<TValues>;
+}
+
+/** Internal: whether `value` is an arg list built by any copy of this package. */
+export function isArgList(value: unknown): value is ArgList {
+  return hasBrand(value, "ArgList");
+}
+
+/** Internal: the values an arg list carries, in the order they were given. */
+export function argListValues(list: ArgList): readonly unknown[] {
+  const values: unknown = (list as unknown as Record<symbol, unknown>)[VALUES];
+  return Array.isArray(values) ? (values as readonly unknown[]) : [];
+}