feat(logger): Add dual exports with esmodule support on Logger

[antstanley]

Description of your changes

This change adds dual package exports to the Logger package, so it now exports CommonJs and ES Modules. The intention is that this PR is more for discussion purposes at this point, as I've made quite a few decisions to implement this efficiently.

The changes are primarily isolated to this package, and does not break any other packages or require changes on other packages.

Hopefully it informs the best approach to do this on all the packages.

To implement this I've had to do the following

Change the package type to module as default

• Add the type field to package.json and set it to module
• Update all the imports in the src and test folders to include the .js extension
• Reference: https://www.totaltypescript.com/relative-import-paths-need-explicit-file-extensions-in-ecmascript-imports
• tldr: TypeSciprt won't export a pure ESM file without "type": "module", and when that is set it won't compile with the .js extension on imports.

Add dual exports to package.json

• Add the exports property, and use conditional exports to specify which set of files to use when importing or requiring
• Set require to use lib/cjs/index.js
• Set import to use lib/esm/index.js
• Reference: https://www.typescriptlang.org/docs/handbook/esm-node.html

Add tsconfig.esm.json to monorepo root and to package root

• ESM specific TypeScript configs to enable building of ES Modules
• Root tsconfig.esm.json extends the base tsconfig.json file and overrides the module specific settings
• Package tsconfig.esm.json extends the root ESM config by specifying the outDir as lib/esm
• Package tsconfig.json is updated to set the outDir to lib/cjs

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext", 
    "noEmitHelpers": true 
  }
}

Update build scripts

• Now three build scripts in package.json
• build:cjs - Build the CommonJs build using the default tsconfig.json
• build:esm - Build the ESM build using tsconfig.esm.json
• build - Calls both build scripts

Add postbuild script to define module types in lib/cjs and lib/esm

• Created a simple JS script to create package.json files in the output directories

• post build script - Creates a package.json file in lib/esm and lib/cjs to set the module type to the correct type respectively for each folder

• The package root package.json file has property type set to module to direct TypeScript and Node to parse file as ESM, the problem with this is all .js files will be seen as ESM files, so the files in lib/cjs which are CommonJS files, will be seen as the wrong file type. By putting a secondary package.json in lib/cjs with the property "type": "commonjs" it will direct Node to interpret those files as CommonJS files.

• The post build script creates package.json files in lib/cjs and lib/esm, but it only really needs to create one in lib/cjs for those CommonJS files. I decided to add a package.json file to lib/esm with "type": "module" to be explicit, and to mirror file structure of lib/cjs, though technically its not needed, as the package's root package.json already has the type property set correctly for ESM files.

• NOTE the postbuild script has been replaced by appending && echo '{ \"type\": \"commonjs\" }' > lib/cjs/package.json to the end of build:* scripts

Enhancements / Fixes for tests

Removed all barrel files

• jest / ts-jest was giving errors when trying to interpret any export * from 'someModule' lines, which happens mostly in barrel files.
• Barrel files have a performance impact on import and load times.
• Instead of spending the time debugging jest/ts-jest configs I decided to remove all barrel files and switch to direct imports
• Reference: Speeding up the JavaScript ecosystem - The barrel file debacle
• Reference: Performance comparison on direct imports vs barrel files

Related issues, RFCs

RFC: #1714

Issue number: #521

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my change is effective and works
• The PR title follows the conventional commit semantics

Breaking change checklist

NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

[dreamorosi]

Thanks for this amazing PR, I really appreciate it!

One question, perhaps out of ignorance. Is it normal that in the ESM build, the files that contain only types/interfaces are empty? I.e.

cat packages/logger/lib/esm/log/LogItemInterface.js 
export {};

[antstanley]

Thanks for this amazing PR, I really appreciate it!

One question, perhaps out of ignorance. Is it normal that in the ESM build, the files that contain only types/interfaces are empty? I.e.

cat packages/logger/lib/esm/log/LogItemInterface.js 
export {};

So this won't have an impact on the running code, and the types are in the declaration file. It's normal behaviour for the TypeScript compiler tsc. There are a few long running issues over on the TypeScript repo over this behaviour because it can break some front end project builds. At this moment there is not flag to disable it.

[dreamorosi]

@antstanley, thank you so much for this PR!

I really appreciate you stepping up for the community and contributing this PR, as well as addressing and iterating very rapidly.

Let's merge it!

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!

[antstanley]

So happy to see this in! Great work @dreamorosi and @shdq!