3.x: Removing `options` argument from module config sections
See original GitHub issueThe 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.
Issue Analytics
- State:
- Created 3 years ago
- Reactions:2
- Comments:8 (8 by maintainers)
Top GitHub Comments
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).
One more thing - now that module
options
live in their own key of the module export, it’s very intuitive to reference them withself.options
even if you don’t use the documentation.