Bug: TypeScript Import Errors (TS2307) for `@aws-lambda-powertools/parser` Submodules (helpers, schemas) after Upgrading from v2.16.0 to v2.17.0

[garysassano]

Expected Behavior

Description:

After upgrading @aws-lambda-powertools/parser from version 2.16.0 to 2.17.0, TypeScript is no longer able to resolve imports from specific submodules like helpers and schemas. This results in TS2307 errors ("Cannot find module '...' or its corresponding type declarations.").

Example Failing Imports (Working in v2.16.0):

import { JSONStringified } from "@aws-lambda-powertools/parser/helpers";
// Error: Cannot find module '@aws-lambda-powertools/parser/helpers' or its corresponding type declarations.ts(2307)

import { APIGatewayProxyEventV2Schema } from "@aws-lambda-powertools/parser/schemas";
// Error: Cannot find module '@aws-lambda-powertools/parser/schemas' or its corresponding type declarations.ts(2307)

Analysis of Changes Between v2.16.0 and v2.17.0:

The primary relevant change between these versions appears to be the introduction and utilization of the exports field in the package.json file in v2.17.0.

1. v2.16.0 Behavior (Inferred):

   • In version 2.16.0 (and earlier), importing from paths like @aws-lambda-powertools/parser/helpers likely relied on Node.js/TypeScript's standard module resolution finding the relevant index.js/index.d.ts files within the node_modules/@aws-lambda-powertools/parser/helpers/ directory structure. The package.json for v2.16.0 likely did not use the top-level exports map in the same way as v2.17.0.

2. v2.17.0 Behavior (exports map):

   • Version 2.17.0's package.json now includes a comprehensive exports map. This map explicitly defines all the public entry points for the package.
   • For example, it defines:
     • . (the main entry point)
     • ./middleware
     • ./schemas
     • ./helpers
     • ./envelopes
     • and others...
   • Crucially, for each entry point, it specifies different files for CommonJS (require) and ES Modules (import), along with their corresponding type definition (.d.ts) files.

   // Excerpt from v2.17.0 package.json
   "exports": {
     // ... other entries
     "./helpers": {
       "require": {
         "types": "./lib/cjs/helpers/index.d.ts",
         "default": "./lib/cjs/helpers/index.js"
       },
       "import": {
         "types": "./lib/esm/helpers/index.d.ts",
         "default": "./lib/esm/helpers/index.js"
       }
     },
     "./schemas": {
       "require": {
         "types": "./lib/cjs/schemas/index.d.ts",
         "default": "./lib/cjs/schemas/index.js"
       },
       "import": {
         "types": "./lib/esm/schemas/index.d.ts",
         "default": "./lib/esm/schemas/index.js"
       }
     }
     // ... other entries
   }

Why This Causes the Error (Likely Scenario):

The exports map provides more control over package entry points but requires the consuming project's tooling (TypeScript, Node.js) to understand it correctly.

• TypeScript moduleResolution: TypeScript's ability to interpret the exports map depends heavily on the compilerOptions.moduleResolution setting in tsconfig.json.
  • Older settings like "moduleResolution": "node" (or "classic") generally do not fully support or respect the exports map. They will try to look for files directly at paths like node_modules/@aws-lambda-powertools/parser/helpers/index.d.ts, fail (because the structure might have changed or the exports map takes precedence), and report the TS2307 error.
  • Newer settings like "moduleResolution": "node16", "nodenext", or "bundler" are designed to work with the exports map. They will correctly look up @aws-lambda-powertools/parser/helpers in the exports map and resolve it to the appropriate file (lib/esm/helpers/index.d.ts or lib/cjs/helpers/index.d.ts based on other settings like module).

Troubleshooting Attempted:

• Tried alternative import paths (e.g., .../lib/helpers, .../lib/esm/helpers) without success.
• Updated tsconfig.json to use "module": "node16" and "moduleResolution": "node16", but the issue persists.
• Other Powertools modules (e.g., logger, metrics, tracer) are imported and resolved correctly with the same tsconfig.json settings.

Current Behavior

see above.

Code snippet

see above.

Steps to Reproduce

see above.

Possible Solution

No response

Powertools for AWS Lambda (TypeScript) version

2.17.0

AWS Lambda function runtime

22.x

Packaging format used

npm

Execution logs

[am29d]

Hey @garysassano , thanks for raising the issue. We did have exports changes so it sounds likely, can you provide me a tsconfig you have been using to discover it?

[garysassano]

@am29d I use projen to manage my projects, which is used also by aws-cdk-cli and awscdk-service-spec monorepos.

These are the default generated files for a TypeScript project:

tsconfig.json

// ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen".
{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "lib",
    "alwaysStrict": true,
    "declaration": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "inlineSourceMap": true,
    "inlineSources": true,
    "lib": [
      "es2020"
    ],
    "module": "CommonJS",
    "noEmitOnError": false,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "stripInternal": true,
    "target": "ES2020"
  },
  "include": [
    "src/**/*.ts"
  ],
  "exclude": []
}

tsconfig.dev.json

// ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen".
{
  "compilerOptions": {
    "alwaysStrict": true,
    "declaration": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "inlineSourceMap": true,
    "inlineSources": true,
    "lib": [
      "es2020"
    ],
    "module": "CommonJS",
    "noEmitOnError": false,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "stripInternal": true,
    "target": "ES2020"
  },
  "include": [
    "src/**/*.ts",
    "test/**/*.ts",
    ".projenrc.ts",
    "projenrc/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

[dreamorosi]

Hi,

While it's true that the default tsconfig generated by Projen seems to not be compatible with the exports, updating the tsconfig.json according to the recommended settings solves the issue.

See two of the options suggested by the error, both working:

Note that after changing the configuration in tsconfig.json you might have to manually restart the TS Server LSP in your IDE for it to take effect.

I made the changes manually, but according to the code snippets you shared you should be able to change the config in projen as well:

// ~~ Generated by projen. To modify, edit .projenrc.ts and run "npx projen".

[garysassano]

Still, why is the Parser the only feature being affected? It means it does things differently from the rest.

[dreamorosi]

It does, as well as other newer packages like validation and event-handler.

The main difference is that we stopped including the typeVersions field to the package.json file and this affects compatibility with older module resolution strategies.

I removed it from that package and avoided including it in newer ones because it's a bit cumbersome to maintain and for Parser it's been quite error prone. Every time we add an export we need to remember to add it also to the typeVersions, and they need to stay in sync.

With that said, I guess it's not something we should've removed in a minor release - so I'll add it back and consider removing it from all packages in the next major version.