uranusjr commented on code in PR #71144: URL: https://github.com/apache/airflow/pull/71144#discussion_r3748386152
########## ts-sdk/src/sdk/dag.ts: ########## @@ -0,0 +1,251 @@ +/*! + * 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}`); + } +} + +/** + * 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. + */ +export type TaskInputs = Readonly<Record<string, TaskRef>>; + +/** + * Named options for `dag.task()`. + * + * Keyword-only so neither field has to be positioned around the other, and so + * future fields can be added without a new parameter. Unknown keys are + * rejected, so a typo fails at import time rather than being ignored. + */ +export interface TaskOptions { + /** + * Upstream task handles this task consumes. **Reserved: validated and + * retained, but inert today.** + * + * Nothing reads it yet: a handler receives `{ctx, client}` only, and no + * dependency is declared from it — in today's Python-stub mode the stub Dag + * defines task order. To read an upstream task's return value, ask for it + * explicitly: `client.getXCom({ key: "return_value", taskId: "extract" })`. + * Omitting `taskId` there reads the *running* task's own XCom. + */ + readonly inputs?: TaskInputs; + /** Task-level options. **Reserved: retained, but inert today.** */ + readonly spec?: TaskSpec; +} + +/** Per-task record a Dag retains: the handle, the handler, its spec, and the + * upstream handles feeding it. */ +export interface TaskRecord { + readonly task: TaskRef; + readonly handler: TaskHandler; + readonly spec: TaskSpec; + /** Upstream handles keyed by input name; empty when the task has no inputs. */ + readonly inputs: TaskInputs; +} + +// Assigned inside Dag's static block: gives package-internal code read access +// to the #tasks private field without a public accessor on the Dag class. +let taskRecordsOf: (dag: Dag) => ReadonlyMap<string, TaskRecord>; + +// Every Dag ever constructed, so the bundle manifest can report the ones that +// were never passed to registerDags(...) and airflow-ts-pack can warn about them. +const declaredDagIds = new Set<string>(); + +/** + * A Dag declared in TypeScript. + * + * Today the Dag structure itself is still declared by a Python stub file; a + * `Dag` instance binds TypeScript handlers to that stub's Dag/task IDs. The + * instance retains its `spec` and every task's `(taskId, handler, spec)` so a + * future `serialize()` can produce the serialized Dag JSON for native + * TypeScript Dag declaration. + */ +export class Dag { + /** Identifier of this Dag. Must match the Python Dag's `dag_id`. */ + readonly dagId: string; + /** Dag-level options this instance was constructed with, copied and frozen. */ + readonly spec: DagSpec; + readonly #tasks = new Map<string, TaskRecord>(); + + static { + taskRecordsOf = (dag) => dag.#tasks; + } + + constructor(dagId: string, spec: DagSpec = {}) { + validateKey("dagId", dagId); + this.dagId = dagId; + // Copied and frozen, as task specs and inputs are: nothing reads a spec + // until the bundle manifest is built, long after the user's module has run, + // so a later mutation of their object would silently change what is packed. + // Shallow — a nested value in a future generated spec stays mutable. + this.spec = Object.freeze({ ...spec }); + declaredDagIds.add(dagId); Review Comment: Also not a big fan with using a global variable like this, especially in the constructor. Why not make the registry a public interface instead, similar to how the Java SDK has a Bundle class? -- 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]
