RFC: Support a way to specify runtime compatibility date and flags for dependencies

[xortive]

JS packages written against the Workers Runtime API should be able to specify compatibility information, to prevent scenarios where the user tries to use a newer compatibility date than is supported by one of their dependencies, or tries to use a compatibility flag that is incompatible with one of their dependencies.

This has happened when copying code from an existing project into a newly generated one with a newer compatibility date, and is a difficult problem to discover -- it would be nice if Cloudflare's packages, and hopefully the greater ecosystem, could contribute to preventing this class of issues.

Package authors targeting the Workers Runtime should specify compatibility information, and we should consider requiring one to be specified if the cf-workers specific target is used (what was discussed in #84).

I propose using package.json#engines.cf-workers, though we'll need an object rather than just the semver compatibility string that's used for node.

I think this should be advisory and not block publish, unless a specific compatibility_flag incompatibility is detected which is much more likely to cause breakage.

[geelen]

though we'll need an object rather than just the semver compatibility string that's used for node.

Why is that? Seems like it's geared up to just be a string like "2021-09-14"? https://developers.cloudflare.com/workers/platform/compatibility-dates

[xortive]

though we'll need an object rather than just the semver compatibility string that's used for node.

Why is that? Seems like it's geared up to just be a string like "2021-09-14"? https://developers.cloudflare.com/workers/platform/compatibility-dates

If we support specifying flags, I don't think it should be in the same string

[geelen]

Ah, of course. I forgot all about compatibility flags. Yeah I agree it shouldn't be in the same string, maybe both a shorthand and a longhand could be valid?

{
  "engines": {
    "cf-workers": "2021-09-14"
  }
}

{
  "engines": {
    "cf-workers": {
      "compatibility_date": "2021-09-14",
      "compatibility_flags": ["formdata_parser_supports_files"]
    }
  }
}

Is it weird mixing kebab-case and snake_case there tho? Should it be cfWorkers and compatibilityDate instead?

[penalosa]

cc @jasnell I wonder if this could link in at all with the workerd key for workers compatible packages? Is runtime compatibility versioning something that WinterCG has been considering?