API design questions

I see that you could do

 const { system, print, filesystem, strings } = toolbox

To be honest, I haven’t used this style at all, I prefer to import these things from gluegun itself.

import { system, print, filesystem, strings } from 'gluegun'

I don’t know why this API decision was made and I am pretty sure you have your reasons to do so, but I am curious about this.

Especially that the type systems love static analysis and dealing with runtime mutations are really hard to maintain in terms of typing.

I know that Gluegun has the capability of extensions which I don’t understand why you would need to mutate the toolbox itself instead of simply import the extension as any other JS module.

Now doing this

  .plugins('node_modules', { matching: 'movie-*' })

I see the useful use case of loading more commands at runtime, but the packages itself do not need extensions itself but the ability to enable commands at runtime.

So,

I am curious about this 🤔

[jamonholmgren]

I really appreciate the feedback, @yordis ! It’s clear you’re an excellent engineer. I think you’re right that if developers aren’t disciplined it could cause problems. If developers are worried about it, I would recommend using the approach you outlined. I’m going to bias in favor of low-friction (getting started) over massive-scale with Gluegun’s primary documentation, but we can watch closely what developers report as they use Gluegun and see if adjustments should be made.

[yordis]

I get that, that is why I like the idea of mutating the context but without doing that much magic. What I dislike from the current implementation is that everything is explicit and introduces too many questions.

The rabbit hole on this is expecting other plugins to mutate your context so you can use specific functionality. If people are not disciplined, this could become an issue.

If you find yourself relying on contexts that you do not control on your library, probably the best solution is to import the functionality explicit rather than implicit and then people can’t figure out where things are coming from.

For example, I am doing this right now.

import { IStrawHatConfig } from '../environment';

export interface IStrawHatToolbox extends Toolbox {
  strawHat: {
    config: IStrawHatConfig;
  };
}

export interface IStrawHatCommand extends GluegunCommand<IStrawHatToolbox> {
  env: Environments;
}

export function createCommand(
  command: IStrawHatCommand
): GluegunCommand<IStrawHatToolbox> {
  return {
    ...command,
    async run(toolbox) {
      print.info(`Running on CI: ${print.colors.success(isCI)}`);
      setupEnv(command.env);

      toolbox.strawHat = {
        config: strawHatConfigFactory({
          env: command.env,
        }),
      };

      await command.run(toolbox as IStrawHatToolbox);
    },
  };
}

Do I extend the context?

Yes, I do, but you are explicit on doing. When you call createCommand you can figure out who is inject things into your context.

For example, an issue with this API design is avoiding a naming conflict.

How do you know that some random extension will no break another extension by using the same context key or something like that?

The only solution will be to be aware of your plugins/extensions, but the more flexible and popular something become, the harder will be to do this.

Note

I am not trying to bash here, these are feedbacks from using Gluegun and getting burned out so many times in my career.

Every implementation has ups and downs, and I am just trying to figure out if how to improve Gluegun.