fix: support esm named imports

[prescottprue]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, local variables)
• Refactoring (no functional changes, no api changes)
• Adding Tests
• Build related changes
• CI related changes
• Documentation changes
• Other... Please describe:

What is the current behavior?

When using named imports in ESM you see the error saying that module.exports:

import { Client } from '@okta/okta-sdk-nodejs';
         ^^^^^^
SyntaxError: Named export 'Client' not found. The requested module '@okta/okta-sdk-nodejs' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from '@okta/okta-sdk-nodejs';
const { Client } = pkg;

Though the default export mentioned in the message is technically possible, the need to do this isn't called out by tools like Typescript (more on this below)

Issue Number: N/A

What is the new behavior?

You can use named imports in ESM:

index.js

import { Client } from '@okta/okta-sdk-nodejs'
console.log('Client using named import', Client)

package.json

{
  "type": "module",
  "dependencies": {
    "@okta/okta-sdk-nodejs": "7.1.1"
  }
}

Running:

node ./index.js

Does this PR introduce a breaking change?

• Yes
• No

Other information

Node making named exports via static analysis is part of a known issue in Typescript (i.e. the naming being available in Typescript but not in Node): https://www.typescriptlang.org/docs/handbook/modules/reference.html#interoperability-rules

Properties (other than default) of the CommonJS module’s module.exports may or may not be available as named imports to the ES module. Node.js attempts to make them available via static analysis. TypeScript cannot know from a declaration file whether that static analysis will succeed, and optimistically assumes it will. This limits TypeScript’s ability to catch named imports that may crash at runtime. See microsoft/TypeScript#54018 for more details.

As called out in this typescript issue:

Node uses cjs-module-lexer to syntactically analyze CommonJS modules without executing them in order to turn module.exports properties into named exports that can be imported as named (or namespace) imports by ES modules. However, syntactic analysis has its limitations, and not all module.exports properties get detected on all modules. (In practice, it’s common for this to be all-or-nothing, as with the typescript package in its current state: it has no named exports available.)

Reviewers

[hershmire]

@jaredperreault-okta or anyone else on the Okta team, is this something you would consider applying?

[prescottprue]

@jamesbuchan-okta or @oleksandrpravosudko-okta is anyone able to give a review?

[hershmire]

@tanish-okta @sagar-okta can we get someone to review this PR that's been out since Oct 2024?

[sagar-okta]

LGTM, please rebase once with latest master as this is a old PR. There was a SDK refresh done in between. Just to make sure tests are running correctly.

[prescottprue]

@sagar-okta thanks for the review - the branch has been updated from master

[prescottprue]

@sagar-okta is anything else needed here to get this merged?

[sagar-okta]

Approved, not sure why I cannot see the test runs but changes looks good.

[prescottprue]

Great thanks @sagar-okta - I'm seeing "Merging is blocked" on my end due to "Commits must have verified signatures". Guessing that means that a maintainer needs to merge?

[sagar-okta]

Hi @prescottprue there is an error in the merge process "Commits must have verified signatures." Please make sure you did commit through a valid gpg keys because if not done you cannot merge it.

[sagar-okta]

Hi @prescottprue also please submit your cla since this would be an external contribution

[prescottprue]

@sagar-okta how do I submit a CLA? I don't see anything about it in the contributing docs or the README. I'm making sure to have a GPG key set up - may have to create a new PR