rewire with merged package.json files

[Rahien]

This allows some less savvy debuggers to work while running a docker container built on the js template in development mode, which allows you to skip having to connect using a chrome-based browser and instead just work in your IDE

It also reworks the way dependencies are installed by merging the template package.json into the service's package.json if it exists. If there is a difference in versions, the template wins and a warning is logged during the installation of the packages.

A mu script install is added that installs the dependencies and provides you with a node_modules and package-lock.json file during development.

[Rahien]

fixes warnings during build

[Rahien]

fixes warnings during build

[Rahien]

no need to add a package lock anymore. The service can choose to include/commit one now as the merged package-lock is generated by the mu install script

[Rahien]

need to saveguard the original now as we will merge service and template together which results in a change of this file

[Rahien]

less savvy ides have a problem with debugging in babel node. I don't understand why we are running in babel-node again as we have already babelified before, but this is the current behaviour so i'm leaving it unchanged.

added an env_var to tell the container to just use regular node so less savvy ides are also happy

[Rahien]

this has to be the version of the js image as will be published (feature branch?), if you use e.g. 1.8.0, it will not have the install scripts that are required.

[Rahien]

use development so we also have the dev dependencies

[Rahien]

no longer needed! done during the install step

[madnificent]

Thank you for these PRs. Work in this area can indeed help to get newcomers started with the template. It's a big one.

Note to others: in order to try this, you must build a local image under the name local-js-template and use that as a basis.

Running the PR locally

1. In the template build with this specific name:

     docker build . -t local-js-template

2. In a project using the mu-javascript-template use that in the Dockerfile FROM local-js-template.

3. Run the install script mu script install (we should change this name so verify on later commits).

4. Restart your language server (eg: lsp-workspace-restart)

Findings

I did not dig too deep into the implementation and chose to share these comments in order not to postpone indefinitely.

State of code hints

I could see the built template be installed in node_modules. We must ensure people run user namespaces when running this as this would generate files as root otherwise. This allows to suggest imports in my editor but it did not yet seem to understand the function definition (as it does do for local sources).

For some reason it also kept complaining about missing declaration files which it normally doesn't do. Perhaps the typescript language server update is just more aggressive in forcing to use their tooling. Packages for the types have already been written so it shouldn't be hard to include them though I don't think following their lead is a huge negative for the community...

Includes built sources of mu

The script seems to install the built sources of the mu package with source maps. My language server did not manage to jump to the relevant sources but it was able to do so when adding the original sources in the node_modules instead. Should we add that content instead or will that break when we add coffeescript sources in there?

Adding the relevant JSDOC for sparqlEscapeDateTime then does provide with the expected code hints:

    /**
     * Escape date string or date object into an xsd:dateTime for use in a SPARQL string.
     *
     * @param { Date | string | number } value Date representation
     * (understood by `new Date`) to convert.
     * @return { string } Date representation for SPARQL query.
     */
    function sparqlEscapeDateTime( value ){
      return '"' + new Date(value).toISOString() + '"^^xsd:dateTime';
    };

This may also help in adding the API documentation inside of the template and the constructiond likely looks similar to what exists in the Python ecosystem.

Name of installation script

We should rename the name of the script (install) with another name to not confuse with the installation script a microservice may provide in the configuration. I guess we should try a few. node_modules might be an obvious choice which I think people can remember but I'm not sure if you see an evolution in other directions. Suggestions highly welcomed.

Installation script arguments

Glancing through the code earlier I think I saw something like a clean step. If that's in the script to be called then it should be mentioned in the arguments in scripts/config.json. I did not dig into the sources far enough to be sure.

Future tests

• try with coffeescript or typescript files
• read and understand the implementation
• verify how this behaves when updating node_modules sources for local hacking

[Rahien]

I would not call the install script node_modules as it is very javascript-specific and maybe other templates will have the same problem. How about install-dependencies?

For code hints, there are type definitions available here, but since the template is pure javascript I wanted to keep it this way. Source inclusion and JSDOC can be done of course.

I didn't finish wiring the clean step yet. It removes the package-lock and node_modules of the service for you so that you can do a fresh install, cfr npm ci. However, this is likely something you will rarely do and you can do it manually with very little effort. Probably better to do it that way so you understand what you are doing.