Skip to content

deprecate/remove base64 module once native Uint8Array.toBase64 lands unflagged in Node.js #2

Description

@knoan

goal

Remove the @metreeca/core/base64 module (or deprecate then remove) once V8 / Node.js expose the native
Uint8Array.prototype.toBase64 / Uint8Array.fromBase64 APIs unflagged, so consumers can use the standard APIs
directly.

scope

  • Monitor Node.js releases for the version where the feature becomes default-on (currently gated behind the V8
    --js-base-64 experimental flag through Node 24.x; already Baseline 2025 in evergreen browsers).
  • Bump engines.node in package.json to the minimum Node.js version that ships the feature unflagged.
  • Delete src/standard/base64.ts and src/standard/base64.test.ts, or mark encodeBase64 / decodeBase64
    @deprecated with migration guidance pointing at the native API, then remove in a later major.
  • Drop the ./base64 export from package.json.
  • Remove the row and the description-list reference from README.md.
  • Log the change under CHANGELOG.mdRemoved / Deprecated.

acceptance criteria

  • engines.node raised to the first version that ships Uint8Array.toBase64 / fromBase64 unflagged
  • src/standard/base64.ts removed, or marked @deprecated with migration snippet
  • ./base64 export removed from package.json (when fully removed)
  • README.md updated
  • CHANGELOG.md entry added under [Unreleased]

dependencies

  • V8 unflagging the --js-base-64 experimental flag
  • Node.js release shipping the unflagged V8
  • Willingness to raise the minimum Node.js version

notes

Current wrapper exists only because the native path is flagged on Node; browsers have been Baseline since
September 2025 (Chrome 140, Firefox 133, Safari 18.2). Native migration target:

function encodeBase64(plain: string): string {
    return new TextEncoder().encode(plain).toBase64({ alphabet: "base64url", omitPadding: true });
}
function decodeBase64(encoded: string): string {
    return new TextDecoder().decode(Uint8Array.fromBase64(encoded, { alphabet: "base64url" }));
}

Project baseline to watch alongside this: tsconfig.json target: "ES2022", module: "NodeNext" — likely needs a
lib bump once TypeScript ships types for toBase64 / fromBase64 in its default lib. See the > [!NOTE] panel at
the top of src/standard/base64.ts for the full background.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions