fix(types): remove need for dom.iterable, dom, lib (#5047)

This commit changes our code to work with `@types/node` `18` through to the `24`, with and without `dom`, `dom.iterable`. Things *should* work in other runtimes, with the correct types for them, but that is difficult to verify as we use Node so much in our build to make sure things work.

It’s been about 5 year of no movement on adding WebAssembly types to Node (<https://redirect.github.com/microsoft/TypeScript-DOM-lib-generator/issues/826>). We do not expose these types to users, so we can also inline the small API surface we need.

The types of `Headers` are a bit different in undici (used in `@types/node`) and the DOM. I don’t know why. I refactored the code, to use properties instead of functions, and to call super methods through `Headers.prototype.*.call`. An esoteric difference. Someone subclassing and overwriting our types would have to do it similarly slightly differently too. But well, they should not use `ArcjetHeaders` if they are going to overwrite things, they could use `Headers` just as well.

The changes *except* for `Headers` do not turn up in generated `.d.ts` files, so should not affect users.

Importantly, there is a weird typescript thing (bug?) which will generate `import('undici-types).Headers` or `import('undici-types).Response` or so if return types are inferred.
This was noticeable in `nosecone` and `nosecone-next`.
That’s bad because we want *users* to choose where `Headers`, `Response`, etcetera are defined.
The simple solution is to write return types.
I do believe that *libraries* (not apps) should have explicit return types, as explicit contracts for what the API is, so I think that’s good anyway.

Closes GH-16.

Author: wooorm-arcjet

analyze-wasm/edge-light.ts

@@ -5,7 +5,7 @@ import componentCoreWasm from "./wasm/arcjet_analyze_js_req.component.core.wasm?
 import componentCore2Wasm from "./wasm/arcjet_analyze_js_req.component.core2.wasm?module";
 import componentCore3Wasm from "./wasm/arcjet_analyze_js_req.component.core3.wasm?module";
 
-async function moduleFromPath(path: string): Promise<WebAssembly.Module> {
+async function moduleFromPath(path: string): Promise<WebAssemblyLike.Module> {
   if (path === "arcjet_analyze_js_req.component.core.wasm") {
     return componentCoreWasm;
   }

analyze-wasm/index.ts

@@ -9,7 +9,7 @@ const componentCoreWasmPromise = componentCoreWasm();
 const componentCore2WasmPromise = componentCore2Wasm();
 const componentCore3WasmPromise = componentCore3Wasm();
 
-async function moduleFromPath(path: string): Promise<WebAssembly.Module> {
+async function moduleFromPath(path: string): Promise<WebAssemblyLike.Module> {
   if (path === "arcjet_analyze_js_req.component.core.wasm") {
     return componentCoreWasmPromise;
   }

analyze-wasm/wasm.d.ts

@@ -1,11 +1,41 @@
+// Basic interface of WebAssembly that we use.
+// See:
+// <https://github.com/microsoft/TypeScript/blob/7956c0016/src/lib/dom.generated.d.ts#L37654>.
+// This only includes `Module` which we use here.
+// This can be removed when WebAssembly is in `@types/node` as we use that here.
+declare namespace WebAssemblyLike {
+  type ImportExportKind = "function" | "global" | "memory" | "table";
+
+  interface ModuleExportDescriptor {
+    kind: ImportExportKind;
+    name: string;
+  }
+
+  interface ModuleImportDescriptor {
+    kind: ImportExportKind;
+    module: string;
+    name: string;
+  }
+
+  interface Module {}
+
+  const Module: {
+    prototype: Module;
+    new (bytes: ArrayBufferView<ArrayBuffer> | ArrayBuffer): Module;
+    customSections(moduleObject: Module, sectionName: string): ArrayBuffer[];
+    exports(moduleObject: Module): ModuleExportDescriptor[];
+    imports(moduleObject: Module): ModuleImportDescriptor[];
+  };
+}
+
 /**
  * Vercel uses the `.wasm?module` suffix to make WebAssembly available in their
  * Vercel Functions product.
  *
  * https://vercel.com/docs/functions/wasm#using-a-webassembly-file
  */
 declare module "*.wasm?module" {
-  export default WebAssembly.Module;
+  export default WebAssemblyLike.Module;
 }
 
 /**
@@ -16,13 +46,13 @@ declare module "*.wasm?module" {
  * https://developers.cloudflare.com/workers/runtime-apis/webassembly/javascript/#bundling
  */
 declare module "*.wasm" {
-  export default WebAssembly.Module;
+  export default WebAssemblyLike.Module;
 }
 
 /**
  * Our Rollup build turns `.wasm?js` imports into JS imports that provide the
  * `wasm()` function which decodes a base64 Data URL into a WebAssembly Module
  */
 declare module "*.wasm?js" {
-  export function wasm(): Promise<WebAssembly.Module>;
+  export function wasm(): Promise<WebAssemblyLike.Module>;
 }

analyze-wasm/workerd.ts

@@ -5,7 +5,7 @@ import componentCoreWasm from "./wasm/arcjet_analyze_js_req.component.core.wasm"
 import componentCore2Wasm from "./wasm/arcjet_analyze_js_req.component.core2.wasm";
 import componentCore3Wasm from "./wasm/arcjet_analyze_js_req.component.core3.wasm";
 
-async function moduleFromPath(path: string): Promise<WebAssembly.Module> {
+async function moduleFromPath(path: string): Promise<WebAssemblyLike.Module> {
   if (path === "arcjet_analyze_js_req.component.core.wasm") {
     return componentCoreWasm;
   }

arcjet-bun/package.json

@@ -56,11 +56,11 @@
   "devDependencies": {
     "@arcjet/eslint-config": "1.0.0-beta.10",
     "@arcjet/rollup-config": "1.0.0-beta.10",
-    "@types/node": "24.3.0",
     "@rollup/wasm-node": "4.50.0",
     "bun-types": "1.2.21",
     "eslint": "9.34.0",
-    "typescript": "5.9.2"
+    "typescript": "5.9.2",
+    "undici-types": "7.15.0"
   },
   "publishConfig": {
     "access": "public",

examples/nodejs-rate-limit/tsconfig.json

@@ -1,8 +1,9 @@
 {
   "compilerOptions": {
     "checkJs": true,
-    "lib": ["dom.iterable", "dom", "es2022"],
+    "lib": ["es2022"],
     "module": "node16",
+    "skipLibCheck": true,
     "strict": true,
     "target": "es2022"
   },

headers/index.ts

@@ -2,6 +2,11 @@ function isIterable(val: any): val is Iterable<any> {
   return typeof val?.[Symbol.iterator] === "function";
 }
 
+type HeadersInit =
+  | Headers
+  | Array<[string, string]>
+  | Record<string, Array<string> | string | undefined>;
+
 /**
  * Arcjet headers.
  *
@@ -12,9 +17,7 @@ function isIterable(val: any): val is Iterable<any> {
  *   [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers).
  */
 export class ArcjetHeaders extends Headers {
-  constructor(
-    init?: HeadersInit | Record<string, string[] | string | undefined>,
-  ) {
+  constructor(init?: HeadersInit | undefined) {
     super();
     if (
       typeof init !== "undefined" &&
@@ -26,9 +29,7 @@ export class ArcjetHeaders extends Headers {
           this.append(key, value);
         }
       } else {
-        for (const [key, value] of Object.entries(
-          init as Record<string, string[] | string | undefined>,
-        )) {
+        for (const [key, value] of Object.entries(init)) {
           if (typeof value === "undefined") {
             continue;
           }
@@ -58,15 +59,15 @@ export class ArcjetHeaders extends Headers {
    * @returns
    *   Nothing.
    */
-  append(key: string, value: string): void {
+  append: (key: string, value: string) => void = (key, value) => {
     if (typeof key !== "string" || typeof value !== "string") {
       return;
     }
 
     if (key.toLowerCase() !== "cookie") {
-      super.append(key, value);
+      Headers.prototype.append.call(this, key, value);
     }
-  }
+  };
   /**
    * Set a header while ignoring `cookie`.
    *
@@ -80,15 +81,15 @@ export class ArcjetHeaders extends Headers {
    * @returns
    *   Nothing.
    */
-  set(key: string, value: string): void {
+  set: (key: string, value: string) => void = (key, value) => {
     if (typeof key !== "string" || typeof value !== "string") {
       return;
     }
 
     if (key.toLowerCase() !== "cookie") {
-      super.set(key, value);
+      Headers.prototype.set.call(this, key, value);
     }
-  }
+  };
 }
 
 /**

nosecone-next/index.ts

@@ -61,7 +61,7 @@ function nextStyleSrc() {
  *   Next.js middleware that sets secure headers.
  */
 export function createMiddleware(options: Options = defaults) {
-  return async () => {
+  return async (): Promise<Response> => {
     const headers = nosecone(options);
     // Setting this specific header is the way that Next.js implements
     // middleware. See:

nosecone/index.ts

@@ -943,7 +943,7 @@ export function createXssProtection() {
  * @returns
  *   `Headers` with the configured security headers.
  */
-export function nosecone(options?: Options | undefined) {
+export function nosecone(options?: Options | undefined): Headers {
   let contentSecurityPolicy =
     options?.contentSecurityPolicy ?? defaults.contentSecurityPolicy;
   let crossOriginEmbedderPolicy =