feat: add functions configuration API to @netlify/config

[eduardoboucas]

Which problem is this pull request solving?

This PR adds an initial implementation of the functions configuration API, including support for two properties: js_external_modules and ignoredModules.

These can be defined at the top-level [1], target a specific function by name [2], or target multiple functions by name with a glob [3].

# [1]
[functions]
  js_external_modules = ["module-one"]

# [2]
[functions.my-function]
  js_external_modules = ["module-two"]

# [3]
[functions."a_prefix_*"]
  js_external_modules = ["module-three"]

@netlify/config is responsible for reading these values and normalising them. The configuration above will be returned as following:

{
  "functions": {
    "*": {
      "js_external_modules": [
        "module-one"
      ],
    },
    "a_prefix_*": {
      "js_external_modules": [
        "module-three"
      ]
    },
    "my-function": {
      "js_external_modules": [
        "module-two"
      ]
    }
  }
}

It is then up to the consumers, like zip-it-and-ship-it, to apply the globs to a list of functions and apply the configuration parameters accordingly.

Checklist

Please add a x inside each checkbox:

• I have read the contribution guidelines.
• The status checks are successful (continuous integration). Those can be seen below.

[ehmicky]

Should we add a "pre-normalize" validation to ensure that functions.{key} is an plain object?
(except when key is either externalModules or ignoredModules, where it can also be an array of strings)

[eduardoboucas]

If we do this, I think we'll end up duplicating validation logic for each key in two places: once in this pre-normalisation step, and the other for the individual keys after normalisation.

If you do specify a functions.{key} that is not a plain object, it'll be inferred as a configuration property of the top-level object, which is valid syntax. If the goal is to prevent unknown configuration keys (e.g. something other than externalModules or ignoredModules), wouldn't it be better to do it after normalisation, so that we can validate both the top-level and function-level objects?

I did consider this, but my understanding is that we allow unknown properties to get through elsewhere in the application?

[ehmicky]

What about doing it in the post-normalization steps, checking that any functions.* is a plain object?

The downside of doing it in the post-normalization is that the normalization logic would not be able to rely on the assumption that functions.* is a plain object. However, it looks like the current normalization logic would work without that assumption.

The main reason would be to validate against users using something like:

[functions]
my_function = "/functions/my_function.js"

Syntax like this might break @netlify/config because of the assumption that functions.* is a plain object. For example, the functions.*.js_external_modules validation might rely on that assumption.

[eduardoboucas]

Ah, good point! I've done it in the post-normalisation step and, as you say, it works fine. I've added a test for the specific example you shared. It's in 7e33c07.

[eduardoboucas]

(Let me know if that looks okay to you.)

[ehmicky]

This looks good! 👍

[eduardoboucas]

In 91b6138 I've updated the property names, so that externalModules and ignoredModules become js_external_modules and js_ignored_modules, respectively.

We're now using snake case, in line with other configuration properties, and we're prefixing the properties with js_ since they're only relevant for JavaScript functions. This change resulted from an internal discussion with @rstavchansky and @verythorough.

[eduardoboucas]

It just occurred to me that since we're introducing support for TypeScript, the js_ prefix might not be the most accurate. Even though the function will technically run JavaScript, developers may be authoring TypeScript.

Would node_external_modules and node_ignored_modules make more sense? 🤔

(cc @verythorough)

[ehmicky]

Would node_external_modules and node_ignored_modules make more sense? thinking

Considering the term modules is itself quite language-specific, would it make sense to use a language-specific suffix instead of prefix? For example external_node_modules and ignored_node_modules?

[eduardoboucas]

Consider the term modules is itself quite language-specific, would it make sense to use a language-specific suffix instead of prefix? For example external_node_modules and ignored_node_modules?

That feels more human-friendly, for sure! I'm okay with that if everyone else is.