Merge pull request #1348 from jmartin4563/esm-loader

Add ES Module loader initial implementation

.github/workflows/ci-workflow.yml

@@ -38,6 +38,8 @@ jobs:
       run: npm ci
     - name: Run Unit Tests
       run: npm run unit
+    - name: Run ESM Unit Tests
+      run: npm run unit:esm
 
   integration:
     runs-on: ubuntu-latest

THIRD_PARTY_NOTICES.md

@@ -64,6 +64,7 @@ code, the source code can be found at [https://github.com/newrelic/node-newrelic
 * [sinon](#sinon)
 * [tap](#tap)
 * [temp](#temp)
+* [testdouble](#testdouble)
 * [when](#when)
 
 **[optionalDependencies](#optionalDependencies)**
@@ -8977,6 +8978,35 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 ```
 
+### testdouble
+
+This product includes source derived from [testdouble](https://github.com/testdouble/testdouble.js) ([v3.16.6](https://github.com/testdouble/testdouble.js/tree/v3.16.6)), distributed under the [MIT License](https://github.com/testdouble/testdouble.js/blob/v3.16.6/LICENSE.txt):
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015 Test Double, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+```
+
 ### when
 
 This product includes source derived from [when](https://github.com/cujojs/when) ([v3.7.8](https://github.com/cujojs/when/tree/v3.7.8)), distributed under the [MIT License](https://github.com/cujojs/when/blob/v3.7.8/LICENSE.txt):

esm-loader.mjs

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2022 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import newrelic from './index.js'
+import shimmer from './lib/shimmer.js'
+import loggingModule from './lib/logger.js'
+
+const logger = loggingModule.child({ component: 'esm-loader' })
+
+/**
+ * Hook chain responsible for resolving a file URL for a given module specifier
+ *
+ * Our loader has to be the last user-supplied loader if chaining is happening,
+ * as we rely on `nextResolve` being the default Node.js resolve hook to get our URL
+ *
+ * Docs: https://nodejs.org/api/esm.html#resolvespecifier-context-nextresolve
+ *
+ * @param {string} specifier
+ *        String identifier in an import statement or import() expression
+ * @param {object} context
+ *        Metadata about the specifier, including url of the parent module and any import assertions
+ *        Optional argument that only needs to be passed when changed
+ * @param {Function} nextResolve
+ *        The Node.js default resolve hook
+ * @returns {Promise} Promise object representing the resolution of a given specifier
+ */
+export async function resolve(specifier, context, nextResolve) {
+  if (!newrelic.agent) {
+    return nextResolve(specifier)
+  }
+
+  /**
+   * We manually call the default Node.js resolve hook so
+   * that we can get the fully qualified URL path and the
+   * package type (commonjs/module/builtin) without
+   * duplicating the logic of the Node.js hook
+   */
+  const resolvedModule = await nextResolve(specifier)
+  const instrumentationName = shimmer.getInstrumentationNameFromModuleName(specifier)
+  const instrumentationDefinition = shimmer.registeredInstrumentations[instrumentationName]
+
+  if (instrumentationDefinition) {
+    logger.debug(`Instrumentation exists for ${specifier}`)
+
+    if (resolvedModule.format === 'commonjs') {
+      // ES Modules translate import statements into fully qualified filepaths, so we create a copy of our instrumentation under this filepath
+      const instrumentationDefinitionCopy = Object.assign({}, instrumentationDefinition)
+
+      // Stripping the prefix is necessary because the code downstream gets this url without it
+      instrumentationDefinitionCopy.moduleName = resolvedModule.url.replace('file://', '')
+
+      shimmer.registerInstrumentation(instrumentationDefinitionCopy)
+
+      logger.debug(
+        `Registered CommonJS instrumentation for ${specifier} under ${instrumentationDefinitionCopy.moduleName}`
+      )
+    } else {
+      logger.debug(`${specifier} is not a CommonJS module, skipping for now`)
+    }
+  }
+
+  return resolvedModule
+}

package.json

@@ -138,17 +138,18 @@
     "docs": "npm ci && jsdoc -c ./jsdoc-conf.json --private -r .",
     "integration": "npm run prepare-test && npm run sub-install && time tap test/integration/**/**/*.tap.js --timeout=180 --no-coverage --reporter classic",
     "prepare-test": "npm run ssl && npm run docker-env",
-    "lint": "eslint ./*.js lib test bin examples",
-    "lint:fix": "eslint --fix, ./*.js lib test bin examples",
+    "lint": "eslint ./*.{js,mjs} lib test bin examples",
+    "lint:fix": "eslint --fix, ./*.{js,mjs} lib test bin examples",
     "public-docs": "jsdoc -c ./jsdoc-conf.json --tutorials examples/shim api.js lib/shim/ lib/transaction/handle.js && cp examples/shim/*.png out/",
     "publish-docs": "./bin/publish-docs.sh",
     "services": "./bin/docker-services.sh",
     "smoke": "npm run ssl && time tap test/smoke/**/**/*.tap.js --timeout=180 --no-coverage",
     "ssl": "./bin/ssl.sh",
     "sub-install": "node test/bin/install_sub_deps",
-    "test": "npm run integration && npm run unit",
+    "test": "npm run integration && npm run unit && npm run unit:esm",
     "third-party-updates": "oss third-party manifest --includeOptDeps && oss third-party notices --includeOptDeps && git add THIRD_PARTY_NOTICES.md third_party_manifest.json",
     "unit": "rm -f newrelic_agent.log && time tap --test-regex='(\\/|^test\\/unit\\/.*\\.test\\.js)$' --timeout=180 --no-coverage --reporter classic",
+    "unit:esm": "rm -f newrelic_agent.log && time tap --test-regex='(\\/|^test\\/unit\\/.*\\.test\\.mjs)$' --timeout=180 --no-coverage --reporter classic --node-arg=--loader=testdouble",
     "update-cross-agent-tests": "./bin/update-cats.sh",
     "versioned-tests": "./bin/run-versioned-tests.sh",
     "update-changelog-version": "node ./bin/update-changelog-version",
@@ -215,6 +216,7 @@
     "sinon": "^4.5.0",
     "tap": "^16.0.1",
     "temp": "^0.8.1",
+    "testdouble": "^3.16.6",
     "when": "*"
   },
   "repository": {
@@ -232,6 +234,7 @@
     "THIRD_PARTY_NOTICES.md",
     "lib/",
     "bin/tracetractor",
-    "bin/test-naming-rules.js"
+    "bin/test-naming-rules.js",
+    "esm-loader.mjs"
   ]
 }

test/.eslintrc.js

@@ -7,6 +7,9 @@
 module.exports = {
   plugins: ['disable'],
   processor: 'disable/disable',
+  parserOptions: {
+    ecmaVersion: '2020'
+  },
   settings: {
     'disable/plugins': ['jsdoc']
   },