src/sdk/arg-names.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.
*/
// Stating a binding explicitly.
import type { TaskFunction } from "./task.js";
/**
* A rename per argument, keyed by the handler's own parameter names.
*
* Every key is checked against the handler's parameter type, so a typo is a
* compile error naming the right key. The values are Python names, which `tsc`
* cannot see and does not check.
*/
export type ArgNameMap<TArgs> = {
readonly [K in keyof TArgs]?: string;
};
// Read back off the handler at the dispatch site. A global symbol, as the brands are:
// two resolved copies must agree on the key, or a handler wrapped by one loses its renames.
const ARG_NAMES = Symbol.for("airflow.ts-sdk.arg-names");
function validate(names: ArgNameMap<unknown>): ReadonlyMap<string, string> {
const candidate: unknown = names;
if (
typeof candidate !== "object" ||
candidate === null ||
Array.isArray(candidate) ||
![Object.prototype, null].includes(Object.getPrototypeOf(candidate) as object | null)
) {
throw new Error("withArgNames(...) takes a plain object mapping argument names to wire names");
}
const entries = new Map<string, string>();
for (const [key, value] of Object.entries(candidate as Record<string, unknown>)) {
if (typeof value !== "string" || value.length === 0) {
throw new Error(
`withArgNames(...) maps "${key}" to ${JSON.stringify(value)}; a wire name must be a non-empty string`,
);
}
entries.set(key, value);
}
return entries;
}
/**
* Bind an argument explicitly, naming it on both sides.
*
* Mapping first, handler second. An entry takes precedence over folding, and
* everything the map does not mention still folds:
*
* ```ts
* interface ReportArgs {
* label: string; // Python calls this `run_label`
* threshold: number;
* }
*
* const report = withArgNames({ label: "run_label" }, async ({ label, threshold }: ReportArgs) => {
* // `label` is the call's `run_label`; `threshold` folded as usual.
* });
*
* bundle.register(new TaskHandler("etl", "report", report));
* ```
*
* Folding absorbs ordinary spelling differences, so this is for a name that genuinely differs:
* a clearer word than the Dag chose, or a TypeScript reserved word like `enum`.
* It should be rare in a real Dag.
*
* The map's keys are checked against the handler's own parameter type,
* so `{ labl: "run_label" }` is a compile error.
* Its values are Python names, which `tsc` cannot check.
*/
export function withArgNames<TArgs, TReturn>(
// NoInfer, so `TArgs` comes from the handler alone:
// inferring it from the map too would make every key correct and check nothing.
names: ArgNameMap<NoInfer<TArgs>>,
handler: TaskFunction<TArgs, TReturn>,
): TaskFunction<TArgs, TReturn> {
const resolved = validate(names);
if (typeof handler !== "function") {
throw new Error("withArgNames(...) takes the handler function as its second argument");
}
// A wrapper rather than a property on the author's own function:
// one handler can be registered for two tasks that rename differently.
const wrapped: TaskFunction<TArgs, TReturn> = (args) => handler(args);
Object.defineProperty(wrapped, ARG_NAMES, { value: resolved });
return wrapped;
}
/** Internal: the renames a handler was wrapped with, empty when it has none. */
export function getArgNames(handler: TaskFunction<never, unknown>): ReadonlyMap<string, string> {
const carrier = handler as unknown as Record<symbol, unknown>;
const names = carrier[ARG_NAMES];
return names instanceof Map ? (names as ReadonlyMap<string, string>) : EMPTY_ARG_NAMES;
}
const EMPTY_ARG_NAMES: ReadonlyMap<string, string> = new Map();