shivaam commented on code in PR #71144:
URL: https://github.com/apache/airflow/pull/71144#discussion_r3755603430
##########
ts-sdk/src/sdk/registry.ts:
##########
@@ -17,85 +17,84 @@
* under the License.
*/
+import { Dag, getDagTaskRecords, type TaskRef } from "./dag.js";
import type { TaskHandler } from "./task.js";
-// Mirrors the Python task-SDK KEY_REGEX and validate_key in
airflow.sdk.definitions._internal.node.
-const KEY_REGEX = /^[\p{L}\p{N}_.-]+$/u;
-const MAX_KEY_LENGTH = 250;
-
-function validateKey(name: string, value: string): void {
- if (typeof value !== "string" || !KEY_REGEX.test(value)) {
- throw new Error(
- `${name} must be made of alphanumeric characters, dashes, dots, and
underscores`,
- );
- }
- if (value.length > MAX_KEY_LENGTH) {
- throw new Error(`${name} must be less than ${MAX_KEY_LENGTH} characters,
not ${value.length}`);
- }
-}
-
-/** Identifies the Airflow task handled by a TypeScript function. */
-export interface TaskRegistration {
- /** Identifier of the Dag containing this task. */
+/** A registered Dag with its task IDs, returned by {@link
DagRegistry.listDags}.
+ * A task-less Dag is included, so the bundle manifest keeps it visible. */
+export interface RegisteredDag {
+ /** Identifier of the registered Dag. */
readonly dagId: string;
- /** Airflow task ID, including any TaskGroup prefix. */
- readonly taskId: string;
+ /** Airflow task IDs, including any TaskGroup prefix. */
+ readonly tasks: string[];
}
-/** Registry of TypeScript task handlers keyed by Dag ID and task ID. */
-export class TaskRegistry {
- readonly #tasks = new Map<string, Map<string, TaskHandler>>();
+/**
+ * The Dags a bundle process can execute, keyed by Dag ID.
+ *
+ * This is what a bundle entry point builds and hands to `serveDags(registry)`:
+ *
+ * ```ts
+ * const dag = new Dag("my_dag");
+ * dag.task("extract", extractFn);
+ * await serveDags(new DagRegistry(dag));
+ * ```
+ *
+ * It holds no sockets and starts nothing, so a test can build one and invoke a
+ * handler through {@link getTaskHandler} without any runtime in scope.
+ *
+ * Lookups delegate live to each Dag's task map, so tasks added to a Dag
+ * after registration are visible — the registry records Dag identity, not
+ * a snapshot of its tasks.
+ */
+export class DagRegistry {
Review Comment:
Do users need listTasks(), and listDags() directly? Since DagRegistry is
exported from the package root, these become part of the public API. They are
only required by the coordinator though. Could the public registry expose only
registration, with package-internal helpers handling the rest?
##########
ts-sdk/src/sdk/dag.ts:
##########
@@ -0,0 +1,252 @@
+/*!
+ * 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.
+ */
+
+// The Dag authoring surface: `new Dag(dagId)` plus `dag.task(taskId,
handler)`.
+
+import type { TaskHandler } from "./task.js";
+
+// Mirrors the Python task-SDK KEY_REGEX and validate_key in
airflow.sdk.definitions._internal.node.
+const KEY_REGEX = /^[\p{L}\p{N}_.-]+$/u;
+const MAX_KEY_LENGTH = 250;
+
+function validateKey(name: string, value: string): void {
+ if (typeof value !== "string" || !KEY_REGEX.test(value)) {
+ throw new Error(
+ `${name} must be made of alphanumeric characters, dashes, dots, and
underscores`,
+ );
+ }
+ if (value.length > MAX_KEY_LENGTH) {
+ throw new Error(`${name} must be less than ${MAX_KEY_LENGTH} characters,
not ${value.length}`);
+ }
+}
+
+function validateEmptySpec(name: string, value: unknown): void {
+ if (
+ typeof value !== "object" ||
+ value === null ||
+ Array.isArray(value) ||
+ Reflect.ownKeys(value).length > 0
+ ) {
+ throw new Error(`${name} must be an empty object`);
+ }
+}
+
+/**
+ * Dag-level options. **Reserved: no fields yet.**
+ *
+ * Native TypeScript Dag declaration (schedule, tags, ...) will add optional
+ * fields here without changing the `Dag` constructor, generated from the
+ * serialized-Dag JSON schema the way `src/generated/supervisor.ts` is. Until
+ * then only `{}` is accepted, so a field that would be silently dropped —
+ * `new Dag("d", { schedule: "@daily" })` — is a compile error rather than a
+ * Dag that packs and runs without the schedule.
+ */
+export type DagSpec = Record<string, never>;
+
+/**
+ * Task-level options. **Reserved: no fields yet.**
+ *
+ * Future task fields (retries, ...) will land here without changing the
+ * `dag.task()` signature. As with {@link DagSpec}, only `{}` is accepted
today.
+ */
+export type TaskSpec = Record<string, never>;
+
+/**
+ * Opaque handle to a task registered on a {@link Dag}, returned by
+ * `dag.task(...)`.
+ *
+ * Identity only — the handler is deliberately not exposed. Handles are what
the
+ * reserved `inputs` option accepts, and what native TypeScript Dag declaration
+ * will use to wire dependencies.
+ */
+export interface TaskRef {
+ /** Identifier of the Dag this task belongs to. */
+ readonly dagId: string;
+ /** Airflow task ID, including any TaskGroup prefix. */
+ readonly taskId: string;
+}
+
+/**
+ * Upstream task handles keyed by input name. **Reserved: validated and
+ * retained, but inert today** — see {@link TaskOptions.inputs}.
+ *
+ * Values must be handles returned by `dag.task(...)`. Literal values are
+ * deliberately out of scope for now; the future native-Dag work decides how
+ * they are declared.
+ */
Review Comment:
Super nit: I found some of the comments a little hard to scan and seems like
they are written in response to review comments rather than as docs for someone
hovering in an editor. It might help to use a consistent order?
- What it represents today
- Current limitations
- Future purpose
I also prefer simpler language such as “not used yet” instead of “inert.”
For example:
```
/**
* Task references keyed by input name.
*
* References are stored and validated, but they do not create dependencies
or
* pass values to handlers yet. Each reference must identify an earlier task
* in the same Dag. Literal values are not currently supported.
*
* In the future, these references will be used to define dependencies in
* native TypeScript Dags.
*/
```
Not suggesting to drop the reasoning as it is useful.
--
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]
