aazuspan / minee Goto Github PK

If a module is exported by the entry and imported by another module, its properties are empty when accessed through the entry. In other words, if entry exports foo and bar, and foo imports bar, entry.bar will be empty. This will happen whether or not foo exports bar.

Below is a simplified bundle output to demonstrate the error:

var modules = {
  "entry": function (exports2, _requireBundled) {
    return (
      (exports2.foo = _requireBundled("foo")),
      (exports2.bar = _requireBundled("bar")),
      exports2
    );
  },

  "foo": function (exports2, _requireBundled) {
    // Importing bar removes its properties from the entry module
    _requireBundled("bar");
    
    return (
      (exports2 = {}),
      exports2
    );
  },
  "bar": function (exports2, _requireBundled) {
    return (
      (exports2 = {
        a: 1,
        b: 2,
        c: 3
      }),
      exports2
    );
  },
};
function loads(modules2, entry) {
  var moduleCache = {},
    _requireBundled = function (moduleName) {
      if (moduleCache[moduleName]) return moduleCache[moduleName];
      var exp = {};
      return (moduleCache[moduleName] = exp), modules2[moduleName](exp, _requireBundled);
    };
  return _requireBundled(entry);
}

// Should print an object {a: 1, b: 2, c: 3}, but instead prints {}
print(loads(modules, "entry").bar);

The error is almost definitely caused by module caching in the loads function. You can fix this by exporting bar before foo in the entry, but ideally I wouldn't need to worry about import order in the bundle.

Running npm version to bump for a new release updates everything except the version defined in cli.ts:

Remembering to do that manually is a pain. If I can automate it, let's do that.

Also, I should probably report the minee version in the bundled header for debugging purposes.

Currently launching the minee CLI without any arguments just throws error: missing required argument 'entry'. It would be more helpful to run the help command by default.

To avoid re-entering CLI options, minee should support a project config file where you could specify any option e.g. entry, dest, noHeader.

In order to handle that, entry would need to be changed from a CLI argument (required) to an option (optional) so that users could run the CLI without specifying the entry if they have a config file.

Need to decide whether to use JSON or JS for the config. This article recommends JS, but the downside would be slightly more complicated config files since users would need to export their options. We could add a sub-command like init or config that walks the user through the options and builds the config file, but that seems like overkill for a relatively simple set of options.

Most bundlers report how long they took to run, so let's do that. The only challenge will be getting a human-readable time delta, although we can probably make do with just reporting seconds with a couple decimal points since bundling should never take more than a few seconds.

Currently, bundling will happily overwrite existing files. Maybe we should ask for confirmation in the CLI before overwriting for safety, but at the same time that would be a bit of a hassle and maybe not necessary since we would just be overwriting generated files. Should take a look at how other bundlers handle this...

Currently when bundling, licenses are only copied from @license comment blocks within source code files. If that block doesn't exist, licenses should fall back to a repository LICENSE file, if that exists.

Check out Typedoc, the mermaid plugin for Typedoc, and gh-pages.

I think that should be everything I need, along with a few package.json scripts, to build a static docs site and push to Github pages whenever I make a release. Once I do that, I can remove some of the low-level details from the readme and just link to the docs.

For flexibility, bundleModule shouldn't write the output file by default. Instead, a save(dest, {options}) method should be added to the Bundle class.

Currently minee automatically minifies code when bundling, but there might be cases where you don't want that. One specific example is if you wanted to generate documentation from bundled code, you would want to avoid mangling variables, properties, parameters, etc. To accommodate that, I should add a minify and preserveNames (or similar) option to the API, CLI, and config file options. Turning minify off would disable any minifying, while preserveNames would avoid mangling names if minify was true.

Implementation-wise, this should be pretty simple. The minifier, esbuild, supports minifying options: minifyWhitespace, minifyIdentifiers, minifySyntax. I could use those exactly, but I think minify and preserveNames is a little simpler for most use cases.

The only challenge here is that the EE Code Editor does not treat require like a normal function. Instead, any require calls automatically trigger a GET request even if they're never called or if require is re-defined. Bundling currently leaves require calls untouched but replaces the require function with one that loads from the bundle. Mangling means Earth Engine doesn't recognize those calls and make requests, but if you turned off minifying it would, removing any performance benefit from bundling. To account for that, we'll need to rename require to something that won't cause GET requests and won't clash with user-defined functions (since this will be applied to user code), maybe _requireBundle? To do that, we'll need to traverse and edit the AST then turn the modified AST back into source code, which unfortunately means that we to add a code generator dependency (probably @babel/generator or escodegen).

We should be able to lighten the dependencies a little by requiring @babel/traverse and @babel/parser and getting rid of @babel/core.

At the moment, you can only bundle remote Earth Engine repositories. If you're editing a module in a local git clone, this can lead to awkward workflows where you make changes locally, push them to EE, bundle them from EE, and push the bundle back to EE. Ideally, minee could accept a local path or Earth engine path and work identically, e.g. minee users/aazuspan/geeSharp:src/entry.js or minee ./src/entry.js. This would be more convenient and much faster since you wouldn't need to clone and hit Earth Engine servers every time.

This should be as simple as just re-working Module and Repository classes to accept and parse local paths, and the current logic of only attempting to clone modules that cannot be found at the local path would continue to work as expected. There could be cases where you have a combination of local and remote repos, e.g. a local clone that requires an external repo, but that shouldn't be a problem. Just need to make it clear to the user where the repository is coming from to avoid any confusion with out-of-sync repos.