feat: callback on file

[AndersDJohnson]

Supports dependents/node-dependency-tree#147.

These new callback options onFile and onAfterFile, in combination with dependents/node-dependency-tree#149 and dependents/node-precinct#111, will give external consumers enough info to know the position in the graph as node-dependency-tree crawls the project, with full access to the AST and other metadata for each processed file, on top of which we can build our own functionality.

This should eliminate the need for a lot of other feature requests.

Can enhance tests and documentation for this once we have conceptual approval.

We can slowly add this to other detective packages, like the various JavaScript module systems.

Example usage:

Suppose we have a metadata object to track data about each file we process (maybe in real code we would use a Map):

const metadata = {};

Then suppose we call the detective with this onFile function:

    {
      onFile: (data) => {
        const { ast, walker, options } = data;
        const { filename, treePath } = options;

        // Our key in the map
        const metadataKey = [...treePath, filename].join(" > ");
        
        const localMetadata = {};

        metadataMap[localMetadata] = {};

        try {
          walker.walk(ast, (node) => {
            // Check for more stuff in the file...

            localMetadata.type = node.type;
          });
        } catch (error) {
          console.error("*** error", error);
        }
      },
   }

Now our metadata will look something like this:

{
  '/Users/anders/code/app/App.tsx': { type: 'Literal' },
  '/Users/anders/code/app/App.tsx > /Users/anders/code/app/components/Header.tsx': { type: 'Literal' },
  '/Users/anders/code/app/App.tsx > /Users/anders/code/app/components/Header.tsx > /Users/anders/code/app/components/Title.tsx': { type: 'Identifier' },
  '/Users/anders/code/app/App.tsx > /Users/anders/code/app/components/Footer.tsx': { type: 'Literal' }
}

[mrjoelkemp]

This looks great for flexibility. Thanks for doing this. What's an example use of onAfterFile?

[AndersDJohnson]

@mrjoelkemp Thanks! The difference is that onAfterFile includes the dependencies result, unlike onFile. I'm willing to consolidate on just onAfterFile if you like. Wasn't sure if there would be use cases for both, now or in future.

[mrjoelkemp]

Whatever you think is best. Thanks for clarifying

[AndersDJohnson]

@mrjoelkemp Thanks! Just adding the options to the README (see 890d412). Let me know what you think and anything else needed before we can merge!

[AndersDJohnson]

@mrjoelkemp Sorry to bother. Wondering if you had any more thoughts on this, or if we're good to merge & release? I'm happy to step in as a maintainer as well if you like. Or I suppose I could fork & publish for my purposes, but would prefer to support your main line project!

I'm thinking onFile could be useful in addition to onAfterFile if in future we wanted to support consumer-supplied mutations of the AST before the dependency processor runs.

[AndersDJohnson]

@XhmikosR Are you maintaining now? Thanks!

[XhmikosR]

Not really, just had some time and decided to merge a couple of changes. @mrjoelkemp should have a look at this :)