From bf5df795c61d9b8ad22da258251a84b00dc1c9f2 Mon Sep 17 00:00:00 2001 From: LIU ZHE YOU Date: Wed, 19 Aug 2026 07:37:40 +0000 Subject: [PATCH 1/2] Prepare TypeScript SDK 1.0.0-beta1 The first beta needs a publishable unscoped npm identity and consistent release metadata across the SDK, examples, and documentation. --- .../language-sdks/typescript.rst | 16 +++++---- .../tests/test_release_management_commands.py | 2 +- ts-sdk/README.md | 16 +++++---- ts-sdk/docs/index.md | 15 ++++---- ts-sdk/docs/package-lock.json | 4 +-- ts-sdk/docs/package.json | 2 +- ts-sdk/example/package.json | 6 ++-- ts-sdk/example/src/main.ts | 2 +- ts-sdk/package.json | 7 ++-- ts-sdk/pnpm-lock.yaml | 34 +++++++++---------- ts-sdk/src/sdk/brand.ts | 2 +- ts-sdk/tests/public-api.test.ts | 2 +- ts-sdk/tests/sdk/registry.test.ts | 2 +- 13 files changed, 60 insertions(+), 50 deletions(-) diff --git a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst index b93be7b38cefc..71678102e20a1 100644 --- a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst +++ b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst @@ -26,13 +26,17 @@ The TypeScript SDK lets you implement Airflow task logic in TypeScript (or plain Node.js. The Dag and its scheduling remain in Python; individual tasks delegate to a Node.js subprocess that is spawned by :class:`~airflow.sdk.coordinators.node.NodeCoordinator` for each task instance. -The SDK is an ESM-only package that ships from the ``ts-sdk/`` directory of the Airflow repository. It is currently in **alpha** and its API may change. +The SDK is an ESM-only package that ships from the ``ts-sdk/`` directory of the Airflow repository. Its current version is **1.0.0-beta1**, and its API may change. .. warning:: - The SDK is not yet published to npm. To try it today, build it from source in the - `ts-sdk/ `__ directory of the Airflow repository and - depend on it locally (see ``ts-sdk/example/`` for a working setup). + The SDK is a beta release. Its API may change in incompatible ways between releases. + +Install the beta package from npm: + +.. code-block:: bash + + npm install apache-airflow-ts-sdk@1.0.0-beta1 .. seealso:: @@ -93,7 +97,7 @@ entry point. .. code-block:: typescript - import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "@apache-airflow/ts-sdk"; + import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "apache-airflow-ts-sdk"; export async function buildMessage({ ctx, client }: TaskHandlerArgs) { const upstream = await client.getXCom({ @@ -304,7 +308,7 @@ Limitations * **A Python stub Dag is still required.** The Execution API does not yet carry Dag structure for non-Python languages, so task names and dependencies are declared in Python with :func:`@task.stub `. -* **Alpha status.** The SDK API may change in incompatible ways between releases. +* **Beta status.** The SDK API may change in incompatible ways between releases. * **One bundle per coordinator.** :class:`~airflow.sdk.coordinators.node.NodeCoordinator` launches the first usable bundle found in ``bundles_root``; it does not yet route different Dags or tasks to different bundles. To serve multiple bundles, register multiple coordinators on separate queues. diff --git a/dev/breeze/tests/test_release_management_commands.py b/dev/breeze/tests/test_release_management_commands.py index 2be5223e30277..63d2232bc650f 100644 --- a/dev/breeze/tests/test_release_management_commands.py +++ b/dev/breeze/tests/test_release_management_commands.py @@ -311,7 +311,7 @@ def test_get_package_version_possibly_from_stable_txt_for_ts_sdk( monkeypatch.setattr(global_constants, "AIRFLOW_ROOT_PATH", tmp_path) package_json = tmp_path / "ts-sdk" / "package.json" package_json.parent.mkdir(parents=True) - package_json.write_text('{"name": "@apache-airflow/ts-sdk", "version": "0.2.0-alpha.1"}\n') + package_json.write_text('{"name": "apache-airflow-ts-sdk", "version": "0.2.0-alpha.1"}\n') if stable_txt_content is not None: stable_txt = tmp_path / "generated" / "_build" / "docs" / "ts-sdk" / "stable.txt" stable_txt.parent.mkdir(parents=True) diff --git a/ts-sdk/README.md b/ts-sdk/README.md index 45ea2bc31a98a..6b693e29d9387 100644 --- a/ts-sdk/README.md +++ b/ts-sdk/README.md @@ -21,19 +21,21 @@ Public TypeScript interfaces for writing Apache Airflow task handlers. -**Status:** alpha · API will change · Node 22+ · ESM-only +**Status:** 1.0.0-beta1 · API may change · Node 22+ · ESM-only This package defines the user-facing task handler contract and the coordinator runtime used to execute registered TypeScript handlers from Airflow. -> **Note:** This package is not yet published to a public npm registry. Until an -> official Apache Airflow release is available, build and use it from source (see -> [Development](#development)). +## Installation + +```bash +npm install apache-airflow-ts-sdk@1.0.0-beta1 +``` ## Task Handlers ```ts -import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "@apache-airflow/ts-sdk"; +import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "apache-airflow-ts-sdk"; export async function sayHello({ ctx, client }: TaskHandlerArgs) { const greeting = await client.getVariable("greeting"); @@ -98,7 +100,7 @@ Airflow metadata in the bundle itself. TypeScript entrypoint: ```ts -import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "@apache-airflow/ts-sdk"; +import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "apache-airflow-ts-sdk"; export async function extract({ client }: TaskHandlerArgs) { const connection = await client.getConnection("sales_db"); @@ -151,7 +153,7 @@ entrypoint that serves them all: ```ts import { salesDag } from "./sales/dag"; import { billingDag } from "./billing/dag"; -import { DagRegistry, serveDags } from "@apache-airflow/ts-sdk"; +import { DagRegistry, serveDags } from "apache-airflow-ts-sdk"; await serveDags(new DagRegistry(salesDag, billingDag)); ``` diff --git a/ts-sdk/docs/index.md b/ts-sdk/docs/index.md index edda33fe48dc1..3b093b29e6291 100644 --- a/ts-sdk/docs/index.md +++ b/ts-sdk/docs/index.md @@ -24,15 +24,16 @@ writing Apache Airflow task handlers and the coordinator runtime that executes registered TypeScript handlers from an Airflow worker. > **Note** -> This package is **alpha**: the API will change, it requires **Node 22+**, and -> it is **ESM-only**. It is not yet published to a public npm registry — until an -> official Apache Airflow release is available, build and use it from source. +> This package is **1.0.0-beta1**: the API may change, it requires **Node 22+**, and +> it is **ESM-only**. ## Getting Started -The SDK is currently distributed as source in the `ts-sdk/` directory of the -Apache Airflow repository. Build it there and add it as a local dependency of -your task bundle; it is not yet published to a public npm registry. +Install the beta package from npm: + +```bash +npm install apache-airflow-ts-sdk@1.0.0-beta1 +``` Define a Dag and register its task handlers. Handlers receive a `TaskContext` and a `TaskClient`; any non-`undefined` return value is pushed to XCom under @@ -40,7 +41,7 @@ the `"return_value"` key by the active runtime, matching Python `@task` behavior: ```ts -import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "@apache-airflow/ts-sdk"; +import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "apache-airflow-ts-sdk"; export async function sayHello({ ctx, client }: TaskHandlerArgs) { const greeting = await client.getVariable("greeting"); diff --git a/ts-sdk/docs/package-lock.json b/ts-sdk/docs/package-lock.json index 14391fc3d73ad..233fedc7a06e8 100644 --- a/ts-sdk/docs/package-lock.json +++ b/ts-sdk/docs/package-lock.json @@ -1,12 +1,12 @@ { "name": "ts-sdk-docs-toolchain", - "version": "0.0.0", + "version": "1.0.0-beta1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ts-sdk-docs-toolchain", - "version": "0.0.0", + "version": "1.0.0-beta1", "devDependencies": { "@clean-jsdoc-theme/typedoc": "^5.1.1", "@msgpack/msgpack": "^3.1.2", diff --git a/ts-sdk/docs/package.json b/ts-sdk/docs/package.json index 36cbddecd6731..09592f13bcd39 100644 --- a/ts-sdk/docs/package.json +++ b/ts-sdk/docs/package.json @@ -1,6 +1,6 @@ { "name": "ts-sdk-docs-toolchain", - "version": "0.0.0", + "version": "1.0.0-beta1", "private": true, "description": "Documentation toolchain for the Apache Airflow TypeScript SDK (ts-sdk). TypeDoc renders the API reference straight to HTML with the clean-jsdoc-theme; it is kept in its own package so the docs-only dependencies stay out of the SDK's runtime and build toolchain.", "type": "module", diff --git a/ts-sdk/example/package.json b/ts-sdk/example/package.json index 6569ce6b74ffd..f9db569e2b06d 100644 --- a/ts-sdk/example/package.json +++ b/ts-sdk/example/package.json @@ -1,7 +1,7 @@ { - "name": "@apache-airflow/ts-sdk-example", + "name": "apache-airflow-ts-sdk-example", "private": true, - "version": "0.0.0", + "version": "1.0.0-beta1", "type": "module", "license": "Apache-2.0", "scripts": { @@ -9,7 +9,7 @@ "typecheck": "tsc --noEmit" }, "dependencies": { - "@apache-airflow/ts-sdk": "file:.." + "apache-airflow-ts-sdk": "file:.." }, "devDependencies": { "@types/node": "^26.1.2", diff --git a/ts-sdk/example/src/main.ts b/ts-sdk/example/src/main.ts index d08530615e57f..563f474b422a2 100644 --- a/ts-sdk/example/src/main.ts +++ b/ts-sdk/example/src/main.ts @@ -17,7 +17,7 @@ * under the License. */ -import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "@apache-airflow/ts-sdk"; +import { Dag, DagRegistry, serveDags, type TaskHandlerArgs } from "apache-airflow-ts-sdk"; const dag = new Dag("typescript_example"); diff --git a/ts-sdk/package.json b/ts-sdk/package.json index da1e4dea5d0b6..d0c56be943195 100644 --- a/ts-sdk/package.json +++ b/ts-sdk/package.json @@ -1,6 +1,6 @@ { - "name": "@apache-airflow/ts-sdk", - "version": "0.1.0-alpha.0", + "name": "apache-airflow-ts-sdk", + "version": "1.0.0-beta1", "packageManager": "pnpm@10.28.1", "description": "TypeScript Task SDK for Apache Airflow task handlers", "license": "Apache-2.0", @@ -19,6 +19,9 @@ "bugs": { "url": "https://github.com/apache/airflow/issues" }, + "publishConfig": { + "tag": "beta" + }, "exports": { ".": { "types": "./dist/index.d.ts", diff --git a/ts-sdk/pnpm-lock.yaml b/ts-sdk/pnpm-lock.yaml index 00c9113e8e1b0..fb67541f0f76d 100644 --- a/ts-sdk/pnpm-lock.yaml +++ b/ts-sdk/pnpm-lock.yaml @@ -45,7 +45,7 @@ importers: example: dependencies: - '@apache-airflow/ts-sdk': + apache-airflow-ts-sdk: specifier: file:.. version: file:(esbuild@0.28.2) devDependencies: @@ -61,16 +61,6 @@ importers: packages: - '@apache-airflow/ts-sdk@file:': - resolution: {directory: '', type: directory} - engines: {node: '>=22'} - hasBin: true - peerDependencies: - esbuild: ^0.28.2 - peerDependenciesMeta: - esbuild: - optional: true - '@apidevtools/json-schema-ref-parser@11.9.3': resolution: {integrity: sha512-60vepv88RwcJtSHrD6MjIL6Ta3SOYbgfnkHb+ppAVK+o9mXprRtulx7VlRl3lN3bbvysAfCS7WMVfhUYemB0IQ==} engines: {node: '>= 16'} @@ -738,6 +728,16 @@ packages: ajv@6.15.0: resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==} + 'apache-airflow-ts-sdk@file:': + resolution: {directory: '', type: directory} + engines: {node: '>=22'} + hasBin: true + peerDependencies: + esbuild: ^0.28.2 + peerDependenciesMeta: + esbuild: + optional: true + argparse@2.0.1: resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} @@ -1340,12 +1340,6 @@ packages: snapshots: - '@apache-airflow/ts-sdk@file:(esbuild@0.28.2)': - dependencies: - '@msgpack/msgpack': 3.1.3 - optionalDependencies: - esbuild: 0.28.2 - '@apidevtools/json-schema-ref-parser@11.9.3': dependencies: '@jsdevtools/ono': 7.1.3 @@ -1855,6 +1849,12 @@ snapshots: json-schema-traverse: 0.4.1 uri-js: 4.4.1 + apache-airflow-ts-sdk@file:(esbuild@0.28.2): + dependencies: + '@msgpack/msgpack': 3.1.3 + optionalDependencies: + esbuild: 0.28.2 + argparse@2.0.1: {} assertion-error@2.0.1: {} diff --git a/ts-sdk/src/sdk/brand.ts b/ts-sdk/src/sdk/brand.ts index b9fab223862f4..a785f736c02b9 100644 --- a/ts-sdk/src/sdk/brand.ts +++ b/ts-sdk/src/sdk/brand.ts @@ -40,4 +40,4 @@ export function hasBrand(value: unknown, name: string): boolean { /** Tail shared by the errors reporting a second resolved copy. */ export const DUPLICATE_COPY_HINT = - "comes from a different copy of @apache-airflow/ts-sdk; deduplicate the dependency so one copy is resolved"; + "comes from a different copy of apache-airflow-ts-sdk; deduplicate the dependency so one copy is resolved"; diff --git a/ts-sdk/tests/public-api.test.ts b/ts-sdk/tests/public-api.test.ts index a9b2f888019d3..c1722b85c8920 100644 --- a/ts-sdk/tests/public-api.test.ts +++ b/ts-sdk/tests/public-api.test.ts @@ -75,7 +75,7 @@ describe("public API", () => { const foreign = {}; Object.defineProperty(foreign, Symbol.for("airflow.ts-sdk.DagRegistry"), { value: true }); await expect(serveDags(foreign as unknown as DagRegistry)).rejects.toThrow( - /different copy of @apache-airflow\/ts-sdk/, + /different copy of apache-airflow-ts-sdk/, ); }); diff --git a/ts-sdk/tests/sdk/registry.test.ts b/ts-sdk/tests/sdk/registry.test.ts index 289ffd5935b26..201e559800c6c 100644 --- a/ts-sdk/tests/sdk/registry.test.ts +++ b/ts-sdk/tests/sdk/registry.test.ts @@ -123,7 +123,7 @@ describe("DagRegistry", () => { const foreign = { dagId: "foreign_dag" }; Object.defineProperty(foreign, Symbol.for("airflow.ts-sdk.Dag"), { value: true }); expect(() => new DagRegistry(foreign as unknown as Dag)).toThrowError( - /different copy of @apache-airflow\/ts-sdk/, + /different copy of apache-airflow-ts-sdk/, ); }); From b78584248ffed1ce537d741565e5054c4916b81e Mon Sep 17 00:00:00 2001 From: LIU ZHE YOU Date: Thu, 20 Aug 2026 05:18:51 +0000 Subject: [PATCH 2/2] Keep the TypeScript SDK beta below 1.0 --- .../language-sdks/typescript.rst | 12 ++++-------- ts-sdk/README.md | 4 ++-- ts-sdk/docs/index.md | 4 ++-- ts-sdk/docs/package-lock.json | 4 ++-- ts-sdk/docs/package.json | 2 +- ts-sdk/example/package.json | 2 +- ts-sdk/package.json | 2 +- 7 files changed, 13 insertions(+), 17 deletions(-) diff --git a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst index 71678102e20a1..5953c501ed06e 100644 --- a/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst +++ b/airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst @@ -26,17 +26,13 @@ The TypeScript SDK lets you implement Airflow task logic in TypeScript (or plain Node.js. The Dag and its scheduling remain in Python; individual tasks delegate to a Node.js subprocess that is spawned by :class:`~airflow.sdk.coordinators.node.NodeCoordinator` for each task instance. -The SDK is an ESM-only package that ships from the ``ts-sdk/`` directory of the Airflow repository. Its current version is **1.0.0-beta1**, and its API may change. +The SDK is an ESM-only package that ships from the ``ts-sdk/`` directory of the Airflow repository. It is currently in **beta** and its API may change. .. warning:: - The SDK is a beta release. Its API may change in incompatible ways between releases. - -Install the beta package from npm: - -.. code-block:: bash - - npm install apache-airflow-ts-sdk@1.0.0-beta1 + The SDK is not yet published to npm. To try it today, build it from source in the + `ts-sdk/ `__ directory of the Airflow repository and + depend on it locally (see ``ts-sdk/example/`` for a working setup). .. seealso:: diff --git a/ts-sdk/README.md b/ts-sdk/README.md index 6b693e29d9387..5d90568fc3892 100644 --- a/ts-sdk/README.md +++ b/ts-sdk/README.md @@ -21,7 +21,7 @@ Public TypeScript interfaces for writing Apache Airflow task handlers. -**Status:** 1.0.0-beta1 · API may change · Node 22+ · ESM-only +**Status:** 0.1.0-beta1 · API may change · Node 22+ · ESM-only This package defines the user-facing task handler contract and the coordinator runtime used to execute registered TypeScript handlers from Airflow. @@ -29,7 +29,7 @@ runtime used to execute registered TypeScript handlers from Airflow. ## Installation ```bash -npm install apache-airflow-ts-sdk@1.0.0-beta1 +npm install apache-airflow-ts-sdk@0.1.0-beta1 ``` ## Task Handlers diff --git a/ts-sdk/docs/index.md b/ts-sdk/docs/index.md index 3b093b29e6291..09c44272848b9 100644 --- a/ts-sdk/docs/index.md +++ b/ts-sdk/docs/index.md @@ -24,7 +24,7 @@ writing Apache Airflow task handlers and the coordinator runtime that executes registered TypeScript handlers from an Airflow worker. > **Note** -> This package is **1.0.0-beta1**: the API may change, it requires **Node 22+**, and +> This package is **0.1.0-beta1**: the API may change, it requires **Node 22+**, and > it is **ESM-only**. ## Getting Started @@ -32,7 +32,7 @@ registered TypeScript handlers from an Airflow worker. Install the beta package from npm: ```bash -npm install apache-airflow-ts-sdk@1.0.0-beta1 +npm install apache-airflow-ts-sdk@0.1.0-beta1 ``` Define a Dag and register its task handlers. Handlers receive a `TaskContext` diff --git a/ts-sdk/docs/package-lock.json b/ts-sdk/docs/package-lock.json index 233fedc7a06e8..d3b69dabaceec 100644 --- a/ts-sdk/docs/package-lock.json +++ b/ts-sdk/docs/package-lock.json @@ -1,12 +1,12 @@ { "name": "ts-sdk-docs-toolchain", - "version": "1.0.0-beta1", + "version": "0.1.0-beta1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ts-sdk-docs-toolchain", - "version": "1.0.0-beta1", + "version": "0.1.0-beta1", "devDependencies": { "@clean-jsdoc-theme/typedoc": "^5.1.1", "@msgpack/msgpack": "^3.1.2", diff --git a/ts-sdk/docs/package.json b/ts-sdk/docs/package.json index 09592f13bcd39..fd0e1328f257c 100644 --- a/ts-sdk/docs/package.json +++ b/ts-sdk/docs/package.json @@ -1,6 +1,6 @@ { "name": "ts-sdk-docs-toolchain", - "version": "1.0.0-beta1", + "version": "0.1.0-beta1", "private": true, "description": "Documentation toolchain for the Apache Airflow TypeScript SDK (ts-sdk). TypeDoc renders the API reference straight to HTML with the clean-jsdoc-theme; it is kept in its own package so the docs-only dependencies stay out of the SDK's runtime and build toolchain.", "type": "module", diff --git a/ts-sdk/example/package.json b/ts-sdk/example/package.json index f9db569e2b06d..d29e3e2e667f1 100644 --- a/ts-sdk/example/package.json +++ b/ts-sdk/example/package.json @@ -1,7 +1,7 @@ { "name": "apache-airflow-ts-sdk-example", "private": true, - "version": "1.0.0-beta1", + "version": "0.1.0-beta1", "type": "module", "license": "Apache-2.0", "scripts": { diff --git a/ts-sdk/package.json b/ts-sdk/package.json index d0c56be943195..8bc9560f17be0 100644 --- a/ts-sdk/package.json +++ b/ts-sdk/package.json @@ -1,6 +1,6 @@ { "name": "apache-airflow-ts-sdk", - "version": "1.0.0-beta1", + "version": "0.1.0-beta1", "packageManager": "pnpm@10.28.1", "description": "TypeScript Task SDK for Apache Airflow task handlers", "license": "Apache-2.0",