src/sdk/task-handler.tstypescript
/*!
 * 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 mixed-language authoring surface: a TypeScript function bound to the
// Python-owned task it implements.

import { brand, hasBrand } from "./brand.js";
import type { TaskFunction } from "./task.js";

// Assigned inside TaskHandler's static block, as Dag does for its tasks.
let functionOf: (handler: TaskHandler<never, unknown>) => TaskFunction;

/** Internal: whether `value` is a TaskHandler built by any copy of this package. */
export function isTaskHandler(value: unknown): value is TaskHandler<never, unknown> {
  return hasBrand(value, "TaskHandler");
}

function requireId(label: string, value: string): string {
  // Typed as string, so plain JavaScript is what these catch, along with the
  // empty string, which types cannot rule out and which no Airflow id can be.
  const candidate: unknown = value;
  if (typeof candidate !== "string" || candidate.length === 0) {
    throw new Error(`${label} for a task handler must be a non-empty string`);
  }
  return value;
}

/**
 * A TypeScript function bound to the Python-owned task it implements.
 *
 * A mixed-language Dag declares its structure in Python, with a `@task.stub`
 * per task routed to the Node coordinator. TypeScript supplies the task bodies
 * and nothing else: no dag_id of its own, no schedule, no task order.
 *
 * ```ts
 * const bundle = new Bundle();
 * bundle.register(new TaskHandler("etl", "transform", transform));
 * await bundle.serve();
 * ```
 *
 * `dagId` must match the Python Dag's `dag_id` and `taskId` a `@task.stub` in
 * it, including any TaskGroup prefix. Both are written out: nothing is derived
 * from the handler's function name, which the build step is free to rename.
 *
 * Identity and a body, and no more. A handler has no factory to call, so wiring
 * one the way a natively declared task is wired is a compile error rather than
 * a runtime throw. For a native Dag, use {@link Dag} instead.
 */
export class TaskHandler<TArgs = void, TReturn = unknown> {
  /** Identifier of the Python Dag this task belongs to. */
  readonly dagId: string;
  /** Airflow task ID this handler implements, including any TaskGroup prefix. */
  readonly taskId: string;
  readonly #handler: TaskFunction<TArgs, TReturn>;

  static {
    functionOf = (handler) => handler.#handler as TaskFunction;
  }

  constructor(dagId: string, taskId: string, handler: TaskFunction<TArgs, TReturn>) {
    this.dagId = requireId("dagId", dagId);
    this.taskId = requireId("taskId", taskId);
    if (typeof handler !== "function") {
      throw new Error(`handler for Dag "${dagId}" task "${taskId}" must be a function`);
    }
    brand(this, "TaskHandler");
    this.#handler = handler;
  }
}

/**
 * Internal: the function a TaskHandler carries, for bundle dispatch.
 *
 * Not re-exported from the package root, and the package `"exports"` map blocks
 * deep imports, so this is unreachable from outside the SDK. The field is
 * private for the same reason `TaskRef` does not expose its handler: what a
 * handler binds is identity, and reaching the body is the runtime's business.
 */
export function getTaskHandlerFunction(handler: TaskHandler<never, unknown>): TaskFunction {
  return functionOf(handler);
}