@nodefill/primordials

Node.js primordials object

🧊 The native primordials object from Node.js for anywhere

Docs website | Node.js primordials.js | About Node.js primordials

🤩 Great for authors who want safe intrinsics
📦 Works in Node.js, Deno, Bun and the browser
🍰 Comes with individual files to allow deep imports
🧱 Based on the internal primordials.js from Node.js core

Installation

Install this package using npm, Yarn, or pnpm!

npm install @nodefill/primordials

This package is also compatible with Deno via their compatibility layer. You can import the package directly using the new npm: specifier, or a Deno-compatible ESM CDN like esm.sh or jsDelivr.

import {} from "npm:@nodefill/primordials";
import {} from "https://esm.sh/@nodefill/primordials";

If you're using not using a build tool and you just want to use the package in your browser, you can use an npm CDN like esm.sh or jsDelivr.

import {} from "https://esm.sh/@nodefill/primordials";
import {} from "https://esm.run/@nodefill/primordials";

Usage

This package provides the primordials object from Node.js. Each primordial is also exposed as a separate *.js file if you feel like manually tree-shaking.

import { ArrayIsArray } from "@nodefill/primordials";
import ArrayPrototypeReduce from "@nodefill/primordials/ArrayPrototypeReduce.js";

const sum = (array) => {
  if (!Array.isArray(array)) {
    throw new TypeError(`${array} is not an array`);
  }
  return array.reduce((n, x) => n + x, 0);
};
const safeSum = (array) => {
  if (!ArrayIsArray(array)) {
    throw new TypeError(`${array} is not an array`);
  }
  return ArrayPrototypeReduce(array, (n, x) => n + x, 0);
};

Array.prototype.reduce = () => 100;

console.log(sum([1, 2, 3]));
//=> 100
console.log(safeSum([1, 2, 3]));
//=> 6

We also offer a polyfill.js export for to emulate the Node.js primordials global object.

import "@nodefill/primordials/polyfill.js";

console.log(primordials.ArrayIsArray([]));
//=> true

💾 If you want to be frugal with bundle size, you can explicitly deep-import only specific primordials that you use. This means we won't import the massive 700 item index.js file which can be huge size savings if you're willing to type a few extra words.

import StringPrototypeSlice from "@nodefill/primordials/StringPrototypeSlice.js";
import ArrayBufferIsView from "@nodefill/primordials/ArrayBufferIsView.js";

⚠️ If you import ArrayPrototypeFindLast on Node.js 16, there is no .findLast() function. So what happens? The export will just be undefined. It's on you to ArrayPrototypeFindLast?.(array, ...) if you want to conditionally use it. Just note that it will always be exported but sometimes could be undefined.

import ArrayPrototypeFindLast from "@nodefill/primordials/ArrayPrototypeFindLast.js";

console.log(process.version);
//=> v16.0.0 OR v20.0.0

console.log(ArrayPrototypeFindLast);
//=> undefined OR function findLast() { [native code] }

ℹ Files like RegExpGet$&.js are named RegExpGet$amp.js (replaced with HTML entity names) to avoid issues with restrictive file systems like Windows. 😉

Alternatives

isaacs/node-primordials

• Has processCwd() and friends. See also import { cwd } from "node:process".
• Doesn't have a polyfill.js export to shim the global primordials object.
• A single file. Very easy to copy-paste into your own project.
• Dual release as ESM and CJS. Can encounter the dual package hazard.
• Doesn't have helper SafePromise* exports.
• Doesn't have any Safe* exports yet. See isaacs/node-primordials#9.

ljharb/get-intrinsic

• Different from Node.js core primordials object, but similar goal.
• Uses getIntrinsic("%Math.pow%") instead of import MathPow from "...".
• Uses eval()-like magic instead of an explicit list.
• Far smaller in size.
• Doesn't have a polyfill.js export to shim the global primordials object.

dwlib-js/primordials

• Uses .mjs and .js files, not TypeScript.
• Relies on multiple layers of indirection for what is essentially the same thing as this package.
• Doesn't have a polyfill.js export to shim the global primordials object.
• Doesn't have helper SafePromise* exports.
• Doesn't have Safe* exports.

💡 You can always just not use bound primordials like ArrayPrototypePush() and just use plain prototype lookup .push() if you want to save bundle size and general tooling complexity. 🤷‍♀️ The tradeoff is that you are susceptible to users monkey-patching said global primordials. 😜

Development

This project embraces TypeScript! At the scale of 700+ files, you really just can't with normal JavaScript. 😆 To get started, just run:

npm run build
npm test

To regenerate the latest primordials.json list, just make sure you're on the latest Node.js version and run:

node --expose-internals \
  -r internal/test/binding \
  -p "JSON.stringify(Object.getOwnPropertyNames(primordials).sort())" \
  > test/primordials.json