feat: modularization and bundling enhancements

[andy-haynes]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• Commit messages follow the conventional commits spec
• If this is a code change: I have written unit tests.
• If this changes code in a published package: I have run pnpm changeset to create a changeset JSON document appropriate for this change.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This PR contains several enhancements intended to modernize and simplify usage of the @near-js packages:

• packages are now exported as modules, enabling tree shaking (@near-js packages only, near-api-js was too much of a headache)
• dependencies have been updated to isomorphic packages wherever possible
• global references have been removed, allowing frictionless integration with modern frameworks like Vite
• tests have been moved to TS, enabling direct import and debugging of source TS
• Node and pnpm versions have been updated to 20.15.0 and 9.4.0, respectively

One of the more substantial changes required to target es2022 was the removal of the Assignable class and modification of the Enum class, both used primarily in @near-js/transactions for (de)serialization of actions. With public class fields, the behavior around setting class fields from the base constructor has changed and the dynamic setting logic in Assignable is no longer valid. However, this provides a good opportunity to define class properties per action, which while redundant, provides more intuitive typing support. See relevant SO question.

While Assignable could be removed*, I effectively ran into the opposite problem with Enum. Serialization breaks if any of the following are violated:

• both Enum-derived classes must inherit from Enum, so we can't just delete Enum and implement same logic in the classes
• the enum field cannot be defined as a public field on Enum nor set from within the Enum constructor - the inheriting class must set it, so I've updated it to be abstract enum: string;
• the Enum constructor must still take the properties and set them on itself, despite the class constructor explicitly setting them... this is what appeared to break Assignable-derived classes 😑

I'd need to look into this further to understand what's exactly going on, but the current implementation works and is only a little less confusing than the existing one. *Assignable will remain for backward compatibility reasons, as outdated NAJ peer dependencies in Wallet Selector dependencies break otherwise.

Test Plan

Due to the scope of these changes, a next (near-api-js@next) tag has been created in NPM referencing packages built from this branch. Long term the next tag will require a dedicated build step in order to remain current. Wallet Selector update looks good (React example works): near/wallet-selector#1183

The attempt at an esbuild bundle was missing some functionality and will require further debugging to get working (see branch feat/dist-bundling for original implementation). For now we will be deprecating as part of this major release in favor of using ES modules in browser.

So going from supporting this:

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/near-api-js.min.js"></script>
<script type="module">
  const { providers: { JsonRpcProvider } } = window.nearApi;
  ...
</script>

To relying on modern (starting ~2017-18) browsers supporting modules:

<script type="module">
  import { providers } from 'https://esm.sh/near-api-js@next';
  const { JsonRpcProvider } = providers;
  ...
</script>

This will reduce bundle size substantially for most use cases and is expected to be an easy lift for applications using the old format.

Related issues/PRs

[changeset-bot]

🦋 Changeset detected

Latest commit: f027f1b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 15 packages

Name	Type
@near-js/accounts	Minor
@near-js/biometric-ed25519	Minor
@near-js/crypto	Minor
@near-js/iframe-rpc	Minor
@near-js/keystores	Minor
@near-js/keystores-browser	Minor
@near-js/keystores-node	Minor
near-api-js	Major
@near-js/providers	Major
@near-js/signers	Minor
@near-js/transactions	Minor
@near-js/types	Minor
@near-js/utils	Major
@near-js/wallet-account	Minor
@near-js/cookbook	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[andy-haynes]

@gtsonevv @gagdiez I wanted to get a sanity check on this since it should have always been an Enum but I think worked just because Assignable is flexible. It now needs to extend Enum in order to follow the new rules around class fields and how that impacts serialization (see PR description). Doesn’t seem to cause issues but if you have concerns/insights please let me know.

Note that this also impacts Signature in the same way, which was similarly changed to support both ED25519 and SECP256K1 curves.