From d4e878552481ab674084fa6532ef2f24d0b2220d Mon Sep 17 00:00:00 2001 From: Samuel Macleod Date: Tue, 12 Aug 2025 18:02:03 +0100 Subject: [PATCH 1/4] workers-types v5 --- .github/workflows/release.yml | 2 +- justfile | 3 +- npm/workers-types/README.md | 59 +------------------ npm/workers-types/entrypoints.svg | 53 ----------------- .../{latest => }/index.d.ts | 0 .../generated-snapshot/{latest => }/index.ts | 0 types/scripts/build-types.ts | 24 +------- 7 files changed, 7 insertions(+), 134 deletions(-) delete mode 100644 npm/workers-types/entrypoints.svg rename types/generated-snapshot/{latest => }/index.d.ts (100%) rename types/generated-snapshot/{latest => }/index.ts (100%) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e56e09b3f4c..f33fd55ceef 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -30,7 +30,7 @@ jobs: run: | echo "date=$(cat src/workerd/io/supported-compatibility-date.txt)" >> $GITHUB_OUTPUT; echo "version=${{ (github.event_name != 'push' && inputs.prerelease == true) && '0' || '1'}}.$(cat src/workerd/io/supported-compatibility-date.txt | tr -d '-').${{ github.event_name == 'push' && '0' || inputs.patch }}" >> $GITHUB_OUTPUT; - echo "types_version=${{ (github.event_name != 'push' && inputs.prerelease == true) && '0' || '4'}}.$(cat src/workerd/io/supported-compatibility-date.txt | tr -d '-').${{ github.event_name == 'push' && '0' || inputs.patch }}" >> $GITHUB_OUTPUT; + echo "types_version=${{ (github.event_name != 'push' && inputs.prerelease == true) && '0' || '5'}}.$(cat src/workerd/io/supported-compatibility-date.txt | tr -d '-').${{ github.event_name == 'push' && '0' || inputs.patch }}" >> $GITHUB_OUTPUT; check-tag: name: Check tag is new outputs: diff --git a/justfile b/justfile index b37257b297a..8a64246e0ae 100644 --- a/justfile +++ b/justfile @@ -97,8 +97,7 @@ clippy package="...": generate-types: bazel build //types:types - cp -r bazel-bin/types/definitions/latest types/generated-snapshot/ - cp -r bazel-bin/types/definitions/experimental types/generated-snapshot/ + cp -r bazel-bin/types/definitions/ types/generated-snapshot/ update-reported-node-version: python3 tools/update_node_version.py src/workerd/api/node/node-version.h diff --git a/npm/workers-types/README.md b/npm/workers-types/README.md index 21e637828d8..13191202327 100644 --- a/npm/workers-types/README.md +++ b/npm/workers-types/README.md @@ -34,69 +34,14 @@ The following is a minimal `tsconfig.json` for use alongside this package: ### Compatibility dates -![Entrypoints for compatibility dates](./npm/workers-types/entrypoints.svg) - -The Cloudflare Workers runtime manages backwards compatibility through the use of [Compatibility Dates](https://developers.cloudflare.com/workers/platform/compatibility-dates/). Using different compatibility dates affects the runtime types available to your Worker, and so it's important you specify the correct entrypoint to the `workers-types` package to match your compatibility date (which is usually set in your `wrangler.toml` configuration file). `workers-types` currently exposes the following entrypoints to choose from: - -- `@cloudflare/workers-types` - - The default entrypoint exposes the runtime types for a compatibility date before `2021-11-03`. - -- `@cloudflare/workers-types/2021-11-03` - - This entrypoint exposes the runtime types for a compatibility date between `2021-11-03` and `2022-01-31`. - -- `@cloudflare/workers-types/2022-01-31` - - This entrypoint exposes the runtime types for a compatibility date between `2022-01-31` and `2022-03-21`. - -- `@cloudflare/workers-types/2022-03-21` - - This entrypoint exposes the runtime types for a compatibility date between `2022-03-21` and `2022-08-04`. - -- `@cloudflare/workers-types/2022-08-04` - - This entrypoint exposes the runtime types for a compatibility date between `2022-08-04` and `2022-10-31`. - -- `@cloudflare/workers-types/2022-10-31` - - This entrypoint exposes the runtime types for a compatibility date between `2022-10-31` and `2022-11-30`. - -- `@cloudflare/workers-types/2022-11-30` - - This entrypoint exposes the runtime types for a compatibility date between `2022-11-30` and `2023-03-01`. - -- `@cloudflare/workers-types/2023-03-01` - - This entrypoint exposes the runtime types for a compatibility date between `2023-03-01` and `2023-07-01`. - -- `@cloudflare/workers-types/2023-07-01` - - This entrypoint exposes the runtime types for a compatibility date after `2023-07-01`. - -- `@cloudflare/workers-types/experimental` - - This entrypoint exposes the runtime types for the latest compatibility date. The types exposed by this entrypoint will change over time to always reflect the latest version of the Workers runtime. - -To use one of these entrypoints, you need to specify them in your `tsconfig.json`. For example, this is a sample `tsconfig.json` for using the `2022-08-04` entrypoint. - -```json -{ - "compilerOptions": { - "target": "esnext", - "module": "esnext", - "lib": ["esnext"], - "types": ["@cloudflare/workers-types/2022-08-04"] - } -} -``` +The Cloudflare Workers runtime manages backwards compatibility through the use of [Compatibility Dates](https://developers.cloudflare.com/workers/platform/compatibility-dates/). The `@cloudflare/workers-types` package provides a typing environment that corresponds to the latest version of the Cloudflare Workers runtime. Instead of using `@cloudflare/workers-types` directly, we recommend following the [Typescript language documentation](https://developers.cloudflare.com/workers/languages/typescript/) for Cloudflare Workers to generate a runtime typing environment that corresponds exactly to your compatibility date and flags. ### Importable Types It's not always possible (or desirable) to modify the `tsconfig.json` settings for a project to include all the Cloudflare Workers types. For use cases like that, this package provides importable versions of its types, which are usable with no additional `tsconfig.json` setup. For example: ```ts -import type { Request as WorkerRequest, ExecutionContext } from "@cloudflare/workers-types/experimental" +import type { Request as WorkerRequest, ExecutionContext } from "@cloudflare/workers-types" export default { fetch(request: WorkerRequest, env: unknown, ctx: ExecutionContext) { diff --git a/npm/workers-types/entrypoints.svg b/npm/workers-types/entrypoints.svg deleted file mode 100644 index 057a1524417..00000000000 --- a/npm/workers-types/entrypoints.svg +++ /dev/null @@ -1,53 +0,0 @@ - - - - - - @cloudflare/workers-types - - - - @cloudflare/workers-types/2021-11-03 - - - - @cloudflare/workers-types/2022-01-31 - - - - @cloudflare/workers-types/2022-03-21 - - - - @cloudflare/workers-types/2022-08-04 - - - - @cloudflare/workers-types/2022-10-31 - - - - @cloudflare/workers-types/2022-11-30 - - - - @cloudflare/workers-types/experimental - - - - - - - - - - - types Entrypoint - compatibility_date - 2021-11-03 - 2022-01-31 - 2022-03-21 - 2022-08-04 - 2022-10-31 - 2022-11-30 - diff --git a/types/generated-snapshot/latest/index.d.ts b/types/generated-snapshot/index.d.ts similarity index 100% rename from types/generated-snapshot/latest/index.d.ts rename to types/generated-snapshot/index.d.ts diff --git a/types/generated-snapshot/latest/index.ts b/types/generated-snapshot/index.ts similarity index 100% rename from types/generated-snapshot/latest/index.ts rename to types/generated-snapshot/index.ts diff --git a/types/scripts/build-types.ts b/types/scripts/build-types.ts index d3a82a3c648..96ae9c83ebb 100644 --- a/types/scripts/build-types.ts +++ b/types/scripts/build-types.ts @@ -11,27 +11,9 @@ import { getFilePath } from "../src/utils"; const OUTPUT_PATH = getFilePath("types/definitions"); const ENTRYPOINTS = [ - { compatDate: "2021-01-01", name: "oldest" }, - // https://developers.cloudflare.com/workers/platform/compatibility-dates/#formdata-parsing-supports-file - { compatDate: "2021-11-03" }, - // https://developers.cloudflare.com/workers/platform/compatibility-dates/#settersgetters-on-api-object-prototypes - { compatDate: "2022-01-31" }, - // https://developers.cloudflare.com/workers/platform/compatibility-dates/#global-navigator - { compatDate: "2022-03-21" }, - // https://developers.cloudflare.com/workers/platform/compatibility-dates/#r2-bucket-list-respects-the-include-option - { compatDate: "2022-08-04" }, - // https://developers.cloudflare.com/workers/platform/compatibility-dates/#new-url-parser-implementation - { compatDate: "2022-10-31" }, - // https://developers.cloudflare.com/workers/platform/compatibility-dates/#streams-constructors - // https://developers.cloudflare.com/workers/platform/compatibility-dates/#compliant-transformstream-constructor - { compatDate: "2022-11-30" }, - // https://github.com/cloudflare/workerd/blob/fcb6f33d10c71975cb2ce68dbf1924a1eeadbd8a/src/workerd/io/compatibility-date.capnp#L275-L280 (http_headers_getsetcookie) - { compatDate: "2023-03-01" }, - // https://github.com/cloudflare/workerd/blob/fcb6f33d10c71975cb2ce68dbf1924a1eeadbd8a/src/workerd/io/compatibility-date.capnp#L307-L312 (urlsearchparams_delete_has_value_arg) - { compatDate: "2023-07-01" }, - // Latest compatibility date with experimental features - { compatDate: "2999-12-31", name: "latest" }, - // Latest compatibility date with experimental features + // Latest compatibility date + { compatDate: "2999-12-31", name: "" }, + // All experimental flags turned on { compatDate: "experimental" }, ]; From 6a4313871a7550b8e9a554053fe28896c4e96cb2 Mon Sep 17 00:00:00 2001 From: Samuel Macleod Date: Tue, 12 Aug 2025 18:18:45 +0100 Subject: [PATCH 2/4] fix diff --- .github/workflows/test.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 190a0be5f84..64c07781efb 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -125,8 +125,7 @@ jobs: bazel build --strip=always --remote_cache=https://bazel:${{ secrets.BAZEL_CACHE_KEY }}@bazel-remote-cache.devprod.cloudflare.dev --config=ci --config=release_linux //types:types - name: Check snapshot diff run: | - diff -r types/generated-snapshot/latest bazel-bin/types/definitions/latest > types.diff - diff -r types/generated-snapshot/experimental bazel-bin/types/definitions/experimental >> types.diff + diff -r types/generated-snapshot bazel-bin/types/definitions > types.diff - name: 'Put diff on the environment' if: failure() id: types_diff From 987f09fbc460e711d9060236536a491c42d2d9b0 Mon Sep 17 00:00:00 2001 From: Samuel Macleod Date: Tue, 12 Aug 2025 18:25:46 +0100 Subject: [PATCH 3/4] fix diff --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 64c07781efb..6a54b249373 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -201,7 +201,7 @@ jobs: - name: Create and install workers-types package run: | - cp /tmp/test-types/oldest/* /tmp/test-types + cp /tmp/test-types/* /tmp/test-types cat > /tmp/test-types/package.json << EOF { "name": "@cloudflare/workers-types" From 97a4120396eed63c8ae80ddb689e706dd572ad47 Mon Sep 17 00:00:00 2001 From: Samuel Macleod Date: Tue, 12 Aug 2025 18:30:28 +0100 Subject: [PATCH 4/4] fix diff --- .github/workflows/test.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 6a54b249373..b6902c7697c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -201,7 +201,6 @@ jobs: - name: Create and install workers-types package run: | - cp /tmp/test-types/* /tmp/test-types cat > /tmp/test-types/package.json << EOF { "name": "@cloudflare/workers-types"