@cloudflare/workers-types 1.0.9 → 1.20250124.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/2021-11-03/index.d.ts +6445 -0
  2. package/2021-11-03/index.ts +6346 -0
  3. package/2022-01-31/index.d.ts +6471 -0
  4. package/2022-01-31/index.ts +6372 -0
  5. package/2022-03-21/index.d.ts +6496 -0
  6. package/2022-03-21/index.ts +6397 -0
  7. package/2022-08-04/index.d.ts +6497 -0
  8. package/2022-08-04/index.ts +6398 -0
  9. package/2022-10-31/index.d.ts +6500 -0
  10. package/2022-10-31/index.ts +6401 -0
  11. package/2022-11-30/index.d.ts +6505 -0
  12. package/2022-11-30/index.ts +6406 -0
  13. package/2023-03-01/index.d.ts +6507 -0
  14. package/2023-03-01/index.ts +6408 -0
  15. package/2023-07-01/index.d.ts +6507 -0
  16. package/2023-07-01/index.ts +6408 -0
  17. package/README.md +106 -14
  18. package/entrypoints.svg +53 -0
  19. package/experimental/index.d.ts +6586 -0
  20. package/experimental/index.ts +6487 -0
  21. package/index.d.ts +6337 -277
  22. package/index.ts +6346 -0
  23. package/oldest/index.d.ts +6445 -0
  24. package/oldest/index.ts +6346 -0
  25. package/package.json +4 -9
  26. package/.prettierrc +0 -6
  27. package/test.ts +0 -6
package/README.md CHANGED
@@ -1,36 +1,128 @@
1
1
  # Cloudflare Workers Types
2
2
 
3
- **Install**
3
+ ## Install
4
4
 
5
5
  ```bash
6
- npm install --save-dev @cloudflare/workers-types
6
+ npm install -D @cloudflare/workers-types
7
7
  -- Or
8
8
  yarn add -D @cloudflare/workers-types
9
9
  ```
10
10
 
11
- **Usage**
11
+ ## Usage
12
12
 
13
- Just supply an empty import in one of your source files to receive the workers types
13
+ The following is a minimal `tsconfig.json` for use alongside this package:
14
14
 
15
- ```typescript
16
- import {} from '@cloudflare/workers-types'
15
+ **`tsconfig.json`**
16
+
17
+ ```json
18
+ {
19
+ "compilerOptions": {
20
+ "target": "esnext",
21
+ "module": "esnext",
22
+ "lib": ["esnext"],
23
+ "types": ["@cloudflare/workers-types"]
24
+ }
25
+ }
17
26
  ```
18
27
 
19
- Make sure that the `WebWorker` library is included in [`tsconfig`](https://www.typescriptlang.org/v2/en/tsconfig#lib). e.g.: `"lib": ["WebWorker"] // As well as "DOM", "ESNext", etc.`. `@cloudflare/workers-types` definitions are merged with `WebWorker`.
28
+ ### Compatibility dates
20
29
 
30
+ ![Entrypoints for compatibility dates](./entrypoints.svg)
21
31
 
22
- ### Using a KV namespace
32
+ 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:
23
33
 
24
- It's recommended that you create an ambient type file for your KV namespace bindings. Create a file named `types.d.ts` in your src directory:
34
+ - `@cloudflare/workers-types`
25
35
 
26
- **`types.d.ts`**
36
+ The default entrypoint exposes the runtime types for a compatibility date before `2021-11-03`.
27
37
 
28
- ```typescript
29
- import { KVNamespace } from '@cloudflare/workers-types'
38
+ - `@cloudflare/workers-types/2021-11-03`
39
+
40
+ This entrypoint exposes the runtime types for a compatibility date between `2021-11-03` and `2022-01-31`.
41
+
42
+ - `@cloudflare/workers-types/2022-01-31`
43
+
44
+ This entrypoint exposes the runtime types for a compatibility date between `2022-01-31` and `2022-03-21`.
45
+
46
+ - `@cloudflare/workers-types/2022-03-21`
47
+
48
+ This entrypoint exposes the runtime types for a compatibility date between `2022-03-21` and `2022-08-04`.
49
+
50
+ - `@cloudflare/workers-types/2022-08-04`
51
+
52
+ This entrypoint exposes the runtime types for a compatibility date between `2022-08-04` and `2022-10-31`.
53
+
54
+ - `@cloudflare/workers-types/2022-10-31`
55
+
56
+ This entrypoint exposes the runtime types for a compatibility date between `2022-10-31` and `2022-11-30`.
57
+
58
+ - `@cloudflare/workers-types/2022-11-30`
59
+
60
+ This entrypoint exposes the runtime types for a compatibility date between `2022-11-30` and `2023-03-01`.
61
+
62
+ - `@cloudflare/workers-types/2023-03-01`
63
+
64
+ This entrypoint exposes the runtime types for a compatibility date between `2023-03-01` and `2023-07-01`.
65
+
66
+ - `@cloudflare/workers-types/2023-07-01`
67
+
68
+ This entrypoint exposes the runtime types for a compatibility date after `2023-07-01`.
69
+
70
+ - `@cloudflare/workers-types/experimental`
30
71
 
72
+ 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.
73
+
74
+ 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.
75
+
76
+ ```json
77
+ {
78
+ "compilerOptions": {
79
+ "target": "esnext",
80
+ "module": "esnext",
81
+ "lib": ["esnext"],
82
+ "types": ["@cloudflare/workers-types/2022-08-04"]
83
+ }
84
+ }
85
+ ```
86
+
87
+ ### Importable Types
88
+
89
+ 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:
90
+
91
+ ```ts
92
+ import type { Request as WorkerRequest, ExecutionContext } from "@cloudflare/workers-types/experimental"
93
+
94
+ export default {
95
+ fetch(request: WorkerRequest, env: unknown, ctx: ExecutionContext) {
96
+ return new Response("OK")
97
+ }
98
+ }
99
+ ```
100
+
101
+
102
+ ### Using bindings
103
+
104
+ It's recommended that you create a type file for any bindings your Worker uses. Create a file named
105
+ `worker-configuration.d.ts` in your src directory.
106
+
107
+ If you're using Module Workers, it should look like this:
108
+ ```typescript
109
+ // worker-configuration.d.ts
110
+ interface Env {
111
+ MY_ENV_VAR: string;
112
+ MY_SECRET: string;
113
+ myKVNamespace: KVNamespace;
114
+ }
115
+ ```
116
+ For Service Workers, it should augment the global scope:
117
+ ```typescript
118
+ // worker-configuration.d.ts
31
119
  declare global {
32
- const myKVNamespace: KVNamespace
120
+ const MY_ENV_VAR: string;
121
+ const MY_SECRET: string;
122
+ const myKVNamespace: KVNamespace;
33
123
  }
124
+ export {}
34
125
  ```
35
126
 
36
- Now `myKVNamespace` is available to all of your source files.
127
+ Wrangler can also generate this for you automatically from your `wrangler.toml` configuration file, using the `wrangler types` command.
128
+
package/entrypoints.svg ADDED
@@ -0,0 +1,53 @@
1
+ <?xml version="1.0" encoding="utf-8"?>
2
+ <svg viewBox="0 0 540 280" width="540px" height="280px" xmlns="http://www.w3.org/2000/svg">
3
+ <rect width="540" height="280" style="fill: rgb(255, 255, 255);"/>
4
+ <g transform="matrix(1, 0, 0, 1, 61.018997, -319.418854)">
5
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(238, 238, 238);"/>
6
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;" x="135.709" y="369.298">@cloudflare/workers-types</text>
7
+ </g>
8
+ <g transform="matrix(1, 0, 0, 1, 61.018997, -289.418793)">
9
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(221, 221, 221);"/>
10
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;"><tspan x="135.709" y="369.298">@cloudflare/workers-types/</tspan><tspan style="fill: rgb(0, 85, 220); font-weight: 700;">2021-11-03</tspan></text>
11
+ </g>
12
+ <g transform="matrix(1, 0, 0, 1, 61.018997, -259.418793)">
13
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(238, 238, 238);"/>
14
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;"><tspan x="135.709" y="369.298">@cloudflare/workers-types/</tspan><tspan style="fill: rgb(0, 54, 130); font-weight: 700;">2022-01-31</tspan></text>
15
+ </g>
16
+ <g transform="matrix(1, 0, 0, 1, 61.018997, -229.418869)">
17
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(221, 221, 221);"/>
18
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;"><tspan x="135.709" y="369.298">@cloudflare/workers-types/</tspan><tspan style="fill: rgb(0, 85, 220); font-weight: 700;">2022-03-21</tspan></text>
19
+ </g>
20
+ <g transform="matrix(1, 0, 0, 1, 61.018997, -199.418839)">
21
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(238, 238, 238);"/>
22
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;"><tspan x="135.709" y="369.298">@cloudflare/workers-types/</tspan><tspan style="fill: rgb(0, 54, 130); font-weight: 700;">2022-08-04</tspan></text>
23
+ </g>
24
+ <g transform="matrix(1, 0, 0, 1, 61.018997, -169.418839)">
25
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(221, 221, 221);"/>
26
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;"><tspan x="135.709" y="369.298">@cloudflare/workers-types/</tspan><tspan style="fill: rgb(0, 85, 220); font-weight: 700;">2022-10-31</tspan></text>
27
+ </g>
28
+ <g transform="matrix(1, 0, 0, 1, 61.017925, -139.418854)">
29
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(238, 238, 238);"/>
30
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;"><tspan x="135.709" y="369.298">@cloudflare/workers-types/</tspan><tspan style="fill: rgb(0, 54, 130); font-weight: 700;">2022-11-30</tspan></text>
31
+ </g>
32
+ <g transform="matrix(1, 0, 0, 1, 61.017925, -109.418816)">
33
+ <rect x="128.981" y="349.42" width="340" height="30" style="fill: rgb(221, 221, 221);"/>
34
+ <text style="font-family: monospace; font-size: 14px; white-space: pre;" x="135.709" y="369.298">@cloudflare/workers-types/experimental</text>
35
+ </g>
36
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0);" x1="160" y1="60" x2="190" y2="60"/>
37
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0);" x1="160" y1="90" x2="190" y2="90"/>
38
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0);" x1="160" y1="120" x2="190" y2="120"/>
39
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0);" x1="160" y1="150" x2="190" y2="150"/>
40
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0);" x1="160" y1="180" x2="190" y2="180"/>
41
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0);" x1="160" y1="210" x2="190" y2="210"/>
42
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0);" x1="175" y1="60" x2="175" y2="240"/>
43
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0); stroke-dasharray: 2px;" x1="175" y1="30" x2="175" y2="60"/>
44
+ <line style="fill: rgb(216, 216, 216); stroke: rgb(0, 0, 0); stroke-dasharray: 2px;" x1="175" y1="240" x2="175" y2="270"/>
45
+ <text style="fill: rgb(51, 51, 51); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: middle; white-space: pre;" transform="matrix(1, 0, 0, 1, 307.347992, -77.253761)"><tspan x="52.652" y="98.052">types Entrypoint</tspan></text>
46
+ <text style="fill: rgb(51, 51, 51); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: end; white-space: pre;" x="157.185" y="20.798">compatibility_date</text>
47
+ <text style="fill: rgb(0, 85, 220); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: end; white-space: pre;" x="153.994" y="64.798">2021-11-03</text>
48
+ <text style="fill: rgb(0, 54, 130); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: end; white-space: pre;" x="153.994" y="94.798">2022-01-31</text>
49
+ <text style="fill: rgb(0, 85, 220); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: end; white-space: pre;" x="153.994" y="124.798">2022-03-21</text>
50
+ <text style="fill: rgb(0, 54, 130); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: end; white-space: pre;" x="153.994" y="154.798">2022-08-04</text>
51
+ <text style="fill: rgb(0, 85, 220); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: end; white-space: pre;" x="153.994" y="184.798">2022-10-31</text>
52
+ <text style="fill: rgb(0, 54, 130); font-family: monospace; font-size: 14px; font-weight: 700; text-anchor: end; white-space: pre;" x="153.994" y="214.798">2022-11-30</text>
53
+ </svg>