primordials
object
Node.js π€© Great for authors who want safe intrinsics
π° 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
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";
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] }
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.
Development
This project embraces TypeScript! At the scale of 700+ files, you really just
can't with normal JavaScript.
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