plugin name constitutes a reserved identifier, blocking ESM compatibility

[FND]

In #71 (comment) @moonglum had a joyous moment:

While transforming this module [to ESM], I ran into a major problem 🙈 I think we need to rename this plugin 😅

If you do what we say on our homepage, it will not work:

export const static = [{                                                                                                                                              
    source: "./src",                                                                                                                                                    
    target: "./dist"                                                                                                                                                    
}];

[FND]

Oh. Oopsie.

Scandalously, pondering this for a few days hasn't revealed a magic solution. However, I have ✨ thoughts ✨ :

1. Renaming this plugin seems like a nightmare for maintainers as well as users: AFAICT there's neither an obvious migration path nor do we have obvious communication channels to downstream folks.

   At best we can emit a deprecation message on install, which, good luck having anyone recognize that in the cesspit that is npm, let alone act on it.

2. There's a potential workaround:

   let config = { /* … */ };
   export { config as static };

   I believe faucet-core would happily ingest that without any adjustments, but other consumers would have to know they must use

   import * as config from "./faucet.config.js";
   
   doStuff(config.static);

   Similarly, and perhaps more importantly, configuration authors would have to be aware of this special case. There's no reasonable way for us to provide useful error messages either.

3. The convention that a plugin's configuration key matches that plugin's name is just that: A convention. There's no technical reason faucet-static's configuration can't be called something else:

   export const assets = { /* … */ };

4. Given all that, I'm wondering whether the best solution would be for faucet-core to ingest both static and another identifier: keys: ["static", "assets"] - except, of course, that introduces ambiguity. It also requires special-case awareness as described above.

5. The fact that CommonJS tolerates this identifier but ESM doesn't might lead to confusion when migrating existing configuration files.

6. That alternative identifier needs to be named. "assets" seems preferable to "files", maybe?

[moonglum]

I imagine you had some time in your hammock. I heard that helps!

I think that's a really reasonable approach. Let's try it out! Thanks for the input, I was already starting to fear that transition 🙈

[FND]

🤔 I'm not actually sure how exactly plugin ingestion works, i.e. what happens under the hood when the key exported by plugin itself differs from faucet-core's presets. I can't properly investigate that now, but that seems worth doing before we proceed.

However, in the interest of incremental progress, how about we ...

1. ... start by adjusting v2.2.0 #71 to not rename the configuration key (i.e. stick with static for now), using the export { config as static } workaround in tests.

   This should not require any changes in existing projects with non-ESM configuration files.

2. ... release a new version of faucet-core (v3.1) which supports the assets key in addition to static (though it has to be either or; never both).

3. ... release a new version of faucet-static which changes the configuration key to assets.

4. ... perhaps make the static key throw a "please change your static key to assets" error, as a one-time migration so we don't have to deal with this ambiguity for all eternity.

   I'm not quite sure how this could work, exactly, but ideally we won't need another version of faucet-core and can do it all within faucet-static instead.

The end result would be faucet-static using assets for its configuration key, a slightly unpleasant wart that will forever haunt our dreams.

[moonglum]

There is a subtle hint that you prefer assets over files. I think both names are awful, as all the pipelines work on files/assets. But that's probably bikeshedding. Step 1 of the FND plan has been executed ✅ Please take a look at the PR, it is now converted to ESM, and addresses (most of?) your feedback.

[moonglum]

Step 2 is also prepared here: faucet-pipeline/faucet-pipeline-core#150 plus the doc changes here: faucet-pipeline/docs#105

[FND]

I share your concern about naming - however, we have this issue with the current naming scheme already, as bundles and such are just static files as well and, in fact, faucet's whole raison d'être is about static assets. So one might argue that "assets" here is implicitly saying "any other assets"...

[moonglum]

Okay, let's go with assets 👍

[moonglum]

@FND Thinking about it again after a few months, I think I would prefer the following solution:

• Release the new version of -static as planned, with the old name and everything. Add a deprecation to the package and ask people to install -assets instead
• Release faucet-pipeline-assets with the same version number that registers under assets
• Change the dependency of the new version of faucet-pipeline-images from -static to -assets
• In a later version of core, drop support for -static

If we go with the current idea, we will forever have a mismatch between the package name and the name it is registred under.

We could even release faucet-pipeline-assets now, as it is backwards compatible and people could use it by registering it manually.

[FND]

I think this makes sense, but over time I kinda lost track of what our ecosystem actually looks like: e.g. I'm not entirely sure of the significance of faucet-images here, other than it being (just?) one consumer of faucet-static / faussets.

Given that uncertainty, my preferred route would be to do what you've described in your last paragraph: Start with a decentralized solution, see how it works in practice - then we can make the switch officially (when we return to this project again in a couple of years... 🙈 ).

I'm aware that this decentralized approach risks having obsolete references in projects' config files, but realistically, nobody but us will ever switch to faussets by themselves?

[moonglum]

We solved this problem by releasing faucet-pipeline-assets. It is a drop-in replacement, that uses assets instead of static for its naming. I consider faucet-pipeline-static soft-deprecated at this point.