3.x: Removing `options` argument from module config sections

The problem to solve

Right now in A3, similar to A2, module configuration function sections (including the methods, fields, helpers, and apiRoutes) get two arguments: self and options. self is a reference to the module and options is the actual options object section defined on the module.

The “problem” appears when we or Apos developers use that very useful variable name, “options,” within those function sections. In some cases a module method may take its own set of options. Either the dev needs to use another argument name (e.g., opts) or potentially create confusing code where other devs might not understand which options argument is being used in a context.

To be transparent, this has actually resulted in A3 core bugs where module methods originally had their own options arguments, but then those were removed. But because that argument name was used in the parent context, it took a while to realize that we missed some code cleanup.

It’s also redundant. In these (self, options) function arguments, options is the same thing as self.options. More on that next.

Proposed solution

We deprecate and remove the options argument in module section functions. Instead of methods(self, options), devs will write it as methods(self). The downside of that is that you need to write self.options to get that options object instead of options. Five additional characters.

The benefit of this is additional clarity and that it’s harder to make mistakes when using an options object. Once this change is made, if options is used in a module you can know it’s some variable unique to a specific context. If self.options is used, you can know that it’s referring to the module’s options.

If you ever set const options = self.options; you’re taking that risk on yourself and may God have mercy on your soul.

Alternatives

We do nothing? Other than document that you should name your own options as opts, maybe.

Additional context

This is another thing to update in migrations from 2.x, but compared to all the rest you’ll need to do in migrating module configs, it’s relatively minor in my opinion. An automated module migrator might struggle to parse the options, however any automated tool should get a second review by a developer anyway.

[myovchev]

Well spotted, I don’t have the habit of destructing arguments since my first steps in Typescript (the auto complete of VScode is too good), but in this case it makes a lot of sense (mostly as a self documentation). But I agree again - getting rid of options still seems like a solid win 😃

And as a side note - I have this crazy idea to try and add Typescript support for Apostrophe. I’ll do some research at some point and I’ll let you know about the options we have. Just to be clear - it’s about adding type definitions and NOT rewriting the core to .ts (I’m not that crazy).

[myovchev]

One more thing - now that module options live in their own key of the module export, it’s very intuitive to reference them with self.options even if you don’t use the documentation.