@nodefill/primordials v4.1.0
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
- Has
processCwd()
and friends. See alsoimport { cwd } from "node:process"
. - Doesn't have a
polyfill.js
export to shim the globalprimordials
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.
- Different from Node.js core
primordials
object, but similar goal. - Uses
getIntrinsic("%Math.pow%")
instead ofimport 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 globalprimordials
object.
- 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 globalprimordials
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