More type annotations / TyeScript support

[thibaudcolas]

I’d be interested to hear how much support of TypeScript you’re aiming for? Personally I’m happy coding with JS or TS but found myself reaching for TypeScript for this work, as I don’t have any experience with other forms of QA for Cloudflare workers (unit tests or integration tests).

The current implementation uses JSDoc annotations. Here are specific aspects where I think more types / better types could help when retrieving power / grid intensity data:

• zone: not super clear whether this can be a country code (if so 2-letter ISO code, or 3-letter) or also supports regions / cities. The Electricity Maps docs only say "A string representing the zone identifier". It’d be nice to know more precisely what can be provided. Type annotations could help with that. Edit: see Electricity Maps zones endpoint response.
• options: The current type annotations say it’s required. The code seems to treat it as optional.
• The return types of functions is only defined as Promise<object>. That’s better than nothing but it’d definitely help to have more precise annotations.

Here’s the TypeScript declaration file I arrived at for what it’s worth: gridAwareWebsites.d.ts.

Cloudflare plugin

I had similar small issues with the getLocation helper from the Cloudflare plugin, which does come with TypeScript types in a declaration file but they’re not compatible with the types shipped by Cloudflare itself (@cloudflare/workers-types). Specifically, the type checking fails here with request:

const { country } = await getLocation(request);

Error:

Argument of type 'Request<unknown, IncomingRequestCfProperties<unknown>>' is not assignable to parameter of type 'cloudflareRequest'.
  Types of property 'cf' are incompatible.
    Type 'IncomingRequestCfProperties<unknown> | undefined' is not assignable to type '{ country?: string | undefined; latitude?: number | undefined; longitude?: number | undefined; } | undefined'.
      Type 'IncomingRequestCfProperties<unknown>' is not assignable to type '{ country?: string | undefined; latitude?: number | undefined; longitude?: number | undefined; } | undefined'.
        Type 'IncomingRequestCfProperties<unknown>' is not assignable to type '{ country?: string | undefined; latitude?: number | undefined; longitude?: number | undefined; }'.
          Types of property 'latitude' are incompatible.
            Type 'string | undefined' is not assignable to type 'number | undefined'.
              Type 'string' is not assignable to type 'number'.

Cloudflare considers latitude and longitude to be strings. If the goal is to support TypeScript out of the box, it might be simpler for that code to use Cloudflare’s built-in type annotations.