fix: route ESM Lambdas through handler.mjs via CJS shim

AWS Lambda's CJS resolver picks `dist/handler.js` before `dist/handler.mjs`
when the handler string is `node_modules/datadog-lambda-js/dist/handler.handler`,
causing ESM user functions to fail with ERR_REQUIRE_ESM (or the surface
"Cannot find module" variant when _tryRequireSync swallows it).

Today `dist/handler.js` ships as a verbatim copy of `dist/handler.cjs`
(via `cp ./dist/handler.cjs ./dist/handler.js` in the publish scripts),
so it can never load ESM user code.

This replaces the copy with a real `src/handler.js` shim that:

- Detects ESM user code via the task root `package.json` `type` field or
  a `.mjs` `DD_LAMBDA_HANDLER` / `_HANDLER`.
- For CJS user code: synchronously delegates to `handler.cjs`, preserving
  the prior fast path (no cold-start regression).
- For ESM user code: exposes an async handler that lazily `import()`s
  `handler.mjs` on the first invocation. `handler.mjs`'s async `load()`
  transparently handles both CJS and ESM user modules.

`scripts/update_dist_version.sh` already copies `src/handler.*` into
`dist/`, so the shim ships automatically; the explicit
`cp ./dist/handler.cjs ./dist/handler.js` lines in `publish_npm.sh` and
`publish_prod.sh` are no longer needed and are removed.

Refs: #782
Refs: SLES-2888, SLES-2895, SVLS-9238

Author: zarirhamza

.gitlab/scripts/publish_npm.sh

@@ -29,5 +29,4 @@ if [ -d "./dist" ]; then
     rm -rf ./dist
 fi
 yarn build
-cp ./dist/handler.cjs ./dist/handler.js
 npm publish

scripts/publish_prod.sh

@@ -95,7 +95,6 @@ else
         rm -rf ./dist
     fi
     yarn build
-    cp ./dist/handler.cjs ./dist/handler.js
     yarn publish --new-version "$NEW_VERSION"
 fi
 

src/handler.js

@@ -0,0 +1,63 @@
+// CJS entry shim used by AWS Lambda's bootstrap when the handler string
+// resolves to `node_modules/datadog-lambda-js/dist/handler.handler`.
+//
+// Lambda's resolver searches for `.js` before `.mjs`, so this file is what
+// gets loaded for both CJS and ESM user functions. We branch at runtime:
+//
+//   - CJS user code: synchronously delegate to handler.cjs (preserves the
+//     prior fast-path behavior — no extra dynamic import on cold start).
+//
+//   - ESM user code: expose an async handler that lazily `import()`s
+//     handler.mjs on the first invocation. handler.mjs's async `load()`
+//     transparently handles both CJS and ESM user modules, so this also
+//     fixes the ERR_REQUIRE_ESM failure mode reported in
+//     https://github.com/DataDog/datadog-lambda-js/issues/782.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+function userIsEsm() {
+  const handlerEnv = process.env.DD_LAMBDA_HANDLER || process.env._HANDLER || "";
+  if (/\.mjs(\..*)?$/.test(handlerEnv)) {
+    return true;
+  }
+
+  const taskRoot = process.env.LAMBDA_TASK_ROOT || process.cwd();
+  try {
+    const pkgPath = path.join(taskRoot, "package.json");
+    const raw = fs.readFileSync(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    if (pkg && pkg.type === "module") {
+      return true;
+    }
+  } catch (_) {
+    // package.json missing or unreadable — assume CJS, matches prior behavior.
+  }
+
+  return false;
+}
+
+if (userIsEsm()) {
+  let cachedHandler;
+  let cachedError;
+
+  exports.handler = async function ddEsmHandler(event, context) {
+    if (cachedError) {
+      throw cachedError;
+    }
+    if (!cachedHandler) {
+      try {
+        const mod = await import("./handler.mjs");
+        cachedHandler = mod.handler;
+      } catch (error) {
+        cachedError = error;
+        throw error;
+      }
+    }
+    return cachedHandler(event, context);
+  };
+} else {
+  module.exports = require("./handler.cjs");
+}