global-builtin-modules 0.0.0

package/README.md

@@ -0,0 +1,65 @@
+# global-builtin-modules
+
+Installs a global with **lazy-loaded Node.js builtin modules**.
+
+## Install
+
+```bash
+npm i global-builtin-modules
+```
+
+## Usage (recommended)
+
+Side-effect import at the top of your entrypoint:
+
+```js
+import 'global-builtin-modules'
+
+const fileContent = await N.fs.promises.readFile('example.txt', 'utf8')
+const fileContent2 = await N.fs.promises.readFile('example2.txt', 'utf8')
+```
+
+`N.fs` is loaded on first access; subsequent reads hit a normal property (no Proxy trap overhead).
+
+## Manual install/uninstall (advanced)
+
+```js
+import { installGlobalBuiltinModules } from 'global-builtin-modules/install'
+import { uninstallGlobalBuiltinModules } from 'global-builtin-modules/uninstall'
+
+installGlobalBuiltinModules() // installs globalThis.N
+
+// Optional: customize the global name
+installGlobalBuiltinModules({ name: 'NB' })
+await NB.path.join('a', 'b')
+
+// Uninstall
+uninstallGlobalBuiltinModules() // removes globalThis.N
+uninstallGlobalBuiltinModules('NB') // removes globalThis.NB
+```
+
+## Options
+
+`installGlobalBuiltinModules(options)` supports:
+
+- `name` (default `"N"`): the global name to define
+- `allowlist` (default: all Node builtins, minus internal `_...`): which builtins to expose on `N`
+- `overwrite` (default `false`): overwrite an existing global with the same name
+- `preventExtensions` (default `true`): disallow adding new properties onto `N`
+- `require`: custom loader (useful in tests)
+
+Example allowlist:
+
+```js
+import { installGlobalBuiltinModules } from 'global-builtin-modules/install'
+
+installGlobalBuiltinModules({
+  allowlist: ['fs', 'path', 'crypto'],
+})
+```
+
+## Notes
+
+- Node-only. Requires Node >= 18.
+- Default allowlist is derived from Node’s `builtinModules`.
+- Implementation uses self-rewriting getters (fast after first access).

package/generated/builtins-map.cjs

@@ -0,0 +1,79 @@
+// Auto-generated by scripts/generate-builtins.js - DO NOT EDIT
+// Generated from Node.js builtinModules
+
+/**
+ * Maps N property names to Node.js module specifiers.
+ * Includes both original names (child_process) and camelCase variants (childProcess).
+ * @type {Record<string, string>}
+ */
+const builtinsMap = {
+  "assert": "node:assert",
+  "assertStrict": "node:assert/strict",
+  "async_hooks": "node:async_hooks",
+  "asyncHooks": "node:async_hooks",
+  "buffer": "node:buffer",
+  "child_process": "node:child_process",
+  "childProcess": "node:child_process",
+  "cluster": "node:cluster",
+  "console": "node:console",
+  "constants": "node:constants",
+  "crypto": "node:crypto",
+  "dgram": "node:dgram",
+  "diagnostics_channel": "node:diagnostics_channel",
+  "diagnosticsChannel": "node:diagnostics_channel",
+  "dns": "node:dns",
+  "dnsPromises": "node:dns/promises",
+  "domain": "node:domain",
+  "events": "node:events",
+  "fs": "node:fs",
+  "fsPromises": "node:fs/promises",
+  "http": "node:http",
+  "http2": "node:http2",
+  "https": "node:https",
+  "inspector": "node:inspector",
+  "inspectorPromises": "node:inspector/promises",
+  "module": "node:module",
+  "net": "node:net",
+  "os": "node:os",
+  "path": "node:path",
+  "pathPosix": "node:path/posix",
+  "pathWin32": "node:path/win32",
+  "perf_hooks": "node:perf_hooks",
+  "perfHooks": "node:perf_hooks",
+  "process": "node:process",
+  "punycode": "node:punycode",
+  "querystring": "node:querystring",
+  "readline": "node:readline",
+  "readlinePromises": "node:readline/promises",
+  "repl": "node:repl",
+  "stream": "node:stream",
+  "streamConsumers": "node:stream/consumers",
+  "streamPromises": "node:stream/promises",
+  "streamWeb": "node:stream/web",
+  "string_decoder": "node:string_decoder",
+  "stringDecoder": "node:string_decoder",
+  "sys": "node:sys",
+  "timers": "node:timers",
+  "timersPromises": "node:timers/promises",
+  "tls": "node:tls",
+  "trace_events": "node:trace_events",
+  "traceEvents": "node:trace_events",
+  "tty": "node:tty",
+  "url": "node:url",
+  "util": "node:util",
+  "utilTypes": "node:util/types",
+  "v8": "node:v8",
+  "vm": "node:vm",
+  "wasi": "node:wasi",
+  "worker_threads": "node:worker_threads",
+  "workerThreads": "node:worker_threads",
+  "zlib": "node:zlib"
+}
+
+/**
+ * List of all available property names on N.
+ * @type {readonly string[]}
+ */
+const builtinNames = Object.freeze(Object.keys(builtinsMap))
+
+module.exports = { builtinsMap, builtinNames }

package/generated/builtins-map.js

@@ -0,0 +1,77 @@
+// Auto-generated by scripts/generate-builtins.js - DO NOT EDIT
+// Generated from Node.js builtinModules
+
+/**
+ * Maps N property names to Node.js module specifiers.
+ * Includes both original names (child_process) and camelCase variants (childProcess).
+ * @type {Record<string, string>}
+ */
+export const builtinsMap = {
+  "assert": "node:assert",
+  "assertStrict": "node:assert/strict",
+  "async_hooks": "node:async_hooks",
+  "asyncHooks": "node:async_hooks",
+  "buffer": "node:buffer",
+  "child_process": "node:child_process",
+  "childProcess": "node:child_process",
+  "cluster": "node:cluster",
+  "console": "node:console",
+  "constants": "node:constants",
+  "crypto": "node:crypto",
+  "dgram": "node:dgram",
+  "diagnostics_channel": "node:diagnostics_channel",
+  "diagnosticsChannel": "node:diagnostics_channel",
+  "dns": "node:dns",
+  "dnsPromises": "node:dns/promises",
+  "domain": "node:domain",
+  "events": "node:events",
+  "fs": "node:fs",
+  "fsPromises": "node:fs/promises",
+  "http": "node:http",
+  "http2": "node:http2",
+  "https": "node:https",
+  "inspector": "node:inspector",
+  "inspectorPromises": "node:inspector/promises",
+  "module": "node:module",
+  "net": "node:net",
+  "os": "node:os",
+  "path": "node:path",
+  "pathPosix": "node:path/posix",
+  "pathWin32": "node:path/win32",
+  "perf_hooks": "node:perf_hooks",
+  "perfHooks": "node:perf_hooks",
+  "process": "node:process",
+  "punycode": "node:punycode",
+  "querystring": "node:querystring",
+  "readline": "node:readline",
+  "readlinePromises": "node:readline/promises",
+  "repl": "node:repl",
+  "stream": "node:stream",
+  "streamConsumers": "node:stream/consumers",
+  "streamPromises": "node:stream/promises",
+  "streamWeb": "node:stream/web",
+  "string_decoder": "node:string_decoder",
+  "stringDecoder": "node:string_decoder",
+  "sys": "node:sys",
+  "timers": "node:timers",
+  "timersPromises": "node:timers/promises",
+  "tls": "node:tls",
+  "trace_events": "node:trace_events",
+  "traceEvents": "node:trace_events",
+  "tty": "node:tty",
+  "url": "node:url",
+  "util": "node:util",
+  "utilTypes": "node:util/types",
+  "v8": "node:v8",
+  "vm": "node:vm",
+  "wasi": "node:wasi",
+  "worker_threads": "node:worker_threads",
+  "workerThreads": "node:worker_threads",
+  "zlib": "node:zlib"
+}
+
+/**
+ * List of all available property names on N.
+ * @type {readonly string[]}
+ */
+export const builtinNames = Object.freeze(Object.keys(builtinsMap))

package/generated/types.d.ts

@@ -0,0 +1,189 @@
+// Auto-generated by scripts/generate-builtins.js - DO NOT EDIT
+// Generated from Node.js builtinModules
+
+/**
+ * Union of all available property names on the global builtin modules object.
+ * Includes both original names (child_process) and camelCase variants (childProcess).
+ */
+export type BuiltinModuleName =
+  | 'assert'
+  | 'assertStrict'
+  | 'asyncHooks'
+  | 'async_hooks'
+  | 'buffer'
+  | 'childProcess'
+  | 'child_process'
+  | 'cluster'
+  | 'console'
+  | 'constants'
+  | 'crypto'
+  | 'dgram'
+  | 'diagnosticsChannel'
+  | 'diagnostics_channel'
+  | 'dns'
+  | 'dnsPromises'
+  | 'domain'
+  | 'events'
+  | 'fs'
+  | 'fsPromises'
+  | 'http'
+  | 'http2'
+  | 'https'
+  | 'inspector'
+  | 'inspectorPromises'
+  | 'module'
+  | 'net'
+  | 'os'
+  | 'path'
+  | 'pathPosix'
+  | 'pathWin32'
+  | 'perfHooks'
+  | 'perf_hooks'
+  | 'process'
+  | 'punycode'
+  | 'querystring'
+  | 'readline'
+  | 'readlinePromises'
+  | 'repl'
+  | 'stream'
+  | 'streamConsumers'
+  | 'streamPromises'
+  | 'streamWeb'
+  | 'stringDecoder'
+  | 'string_decoder'
+  | 'sys'
+  | 'timers'
+  | 'timersPromises'
+  | 'tls'
+  | 'traceEvents'
+  | 'trace_events'
+  | 'tty'
+  | 'url'
+  | 'util'
+  | 'utilTypes'
+  | 'v8'
+  | 'vm'
+  | 'wasi'
+  | 'workerThreads'
+  | 'worker_threads'
+  | 'zlib'
+
+/**
+ * The global builtin modules object providing lazy-loaded access to Node.js builtin modules.
+ * Properties are loaded on first access and cached thereafter.
+ */
+export interface GlobalBuiltinModules {
+  readonly assert: typeof import('node:assert')
+  readonly assertStrict: typeof import('node:assert/strict')
+  readonly async_hooks: typeof import('node:async_hooks')
+  readonly asyncHooks: typeof import('node:async_hooks')
+  readonly buffer: typeof import('node:buffer')
+  readonly child_process: typeof import('node:child_process')
+  readonly childProcess: typeof import('node:child_process')
+  readonly cluster: typeof import('node:cluster')
+  readonly console: typeof import('node:console')
+  readonly constants: typeof import('node:constants')
+  readonly crypto: typeof import('node:crypto')
+  readonly dgram: typeof import('node:dgram')
+  readonly diagnostics_channel: typeof import('node:diagnostics_channel')
+  readonly diagnosticsChannel: typeof import('node:diagnostics_channel')
+  readonly dns: typeof import('node:dns')
+  readonly dnsPromises: typeof import('node:dns/promises')
+  readonly domain: typeof import('node:domain')
+  readonly events: typeof import('node:events')
+  readonly fs: typeof import('node:fs')
+  readonly fsPromises: typeof import('node:fs/promises')
+  readonly http: typeof import('node:http')
+  readonly http2: typeof import('node:http2')
+  readonly https: typeof import('node:https')
+  readonly inspector: typeof import('node:inspector')
+  readonly inspectorPromises: typeof import('node:inspector/promises')
+  readonly module: typeof import('node:module')
+  readonly net: typeof import('node:net')
+  readonly os: typeof import('node:os')
+  readonly path: typeof import('node:path')
+  readonly pathPosix: typeof import('node:path/posix')
+  readonly pathWin32: typeof import('node:path/win32')
+  readonly perf_hooks: typeof import('node:perf_hooks')
+  readonly perfHooks: typeof import('node:perf_hooks')
+  readonly process: typeof import('node:process')
+  readonly punycode: typeof import('node:punycode')
+  readonly querystring: typeof import('node:querystring')
+  readonly readline: typeof import('node:readline')
+  readonly readlinePromises: typeof import('node:readline/promises')
+  readonly repl: typeof import('node:repl')
+  readonly stream: typeof import('node:stream')
+  readonly streamConsumers: typeof import('node:stream/consumers')
+  readonly streamPromises: typeof import('node:stream/promises')
+  readonly streamWeb: typeof import('node:stream/web')
+  readonly string_decoder: typeof import('node:string_decoder')
+  readonly stringDecoder: typeof import('node:string_decoder')
+  readonly sys: typeof import('node:sys')
+  readonly timers: typeof import('node:timers')
+  readonly timersPromises: typeof import('node:timers/promises')
+  readonly tls: typeof import('node:tls')
+  readonly trace_events: typeof import('node:trace_events')
+  readonly traceEvents: typeof import('node:trace_events')
+  readonly tty: typeof import('node:tty')
+  readonly url: typeof import('node:url')
+  readonly util: typeof import('node:util')
+  readonly utilTypes: typeof import('node:util/types')
+  readonly v8: typeof import('node:v8')
+  readonly vm: typeof import('node:vm')
+  readonly wasi: typeof import('node:wasi')
+  readonly worker_threads: typeof import('node:worker_threads')
+  readonly workerThreads: typeof import('node:worker_threads')
+  readonly zlib: typeof import('node:zlib')
+
+  /** Non-enumerable allowlist snapshot */
+  readonly __allowlist: readonly string[]
+}
+
+export interface InstallGlobalBuiltinModulesOptions {
+  /**
+   * Name of the global variable to define.
+   * @default "N"
+   */
+  name?: string
+
+  /**
+   * Builtin module names to expose. Supports both original (child_process)
+   * and camelCase (childProcess) names.
+   * @default All public Node.js builtins
+   */
+  allowlist?: BuiltinModuleName[]
+
+  /**
+   * Custom require-like loader (advanced/testing).
+   */
+  require?: (id: string) => unknown
+
+  /**
+   * If true, overwrite an existing global with the same name.
+   * @default false
+   */
+  overwrite?: boolean
+
+  /**
+   * If true, prevents adding new properties to the global builtin modules object.
+   * @default true
+   */
+  preventExtensions?: boolean
+}
+
+/**
+ * Installs a global "N" (configurable name) whose properties lazily load Node.js builtins.
+ */
+export function installGlobalBuiltinModules(options?: InstallGlobalBuiltinModulesOptions): GlobalBuiltinModules
+
+/**
+ * Removes the global builtin modules object (or custom name) from globalThis.
+ * @returns true if the global was removed, false if it didn't exist
+ */
+export function uninstallGlobalBuiltinModules(name?: string): boolean
+
+declare global {
+  var N: GlobalBuiltinModules
+}
+
+export {}

package/index.cjs

@@ -0,0 +1,4 @@
+const { installGlobalBuiltinModules } = require('./install.cjs')
+
+// Default behavior: install globalThis.N on require.
+installGlobalBuiltinModules()

package/index.d.ts

@@ -0,0 +1,18 @@
+// Re-export all types from the generated definitions
+export {
+  BuiltinModuleName,
+  GlobalBuiltinModules,
+  InstallGlobalBuiltinModulesOptions,
+  installGlobalBuiltinModules,
+  uninstallGlobalBuiltinModules,
+} from './generated/types.js'
+
+// Re-export the global declaration
+export {}
+
+// Augment global scope
+import type { GlobalBuiltinModules } from './generated/types.js'
+
+declare global {
+  var N: GlobalBuiltinModules
+}

package/index.js

@@ -0,0 +1,4 @@
+import { installGlobalBuiltinModules } from './install.js'
+
+// Default behavior: install globalThis.N on import.
+installGlobalBuiltinModules()

package/install.cjs

@@ -0,0 +1,75 @@
+const { builtinsMap, builtinNames } = require('./generated/builtins-map.cjs')
+
+function defineLazy(obj, prop, load) {
+  Object.defineProperty(obj, prop, {
+    enumerable: true,
+    configurable: true,
+    get() {
+      const value = load()
+      Object.defineProperty(obj, prop, {
+        enumerable: true,
+        configurable: false,
+        writable: false,
+        value,
+      })
+      return value
+    },
+  })
+}
+
+/**
+ * Installs a global "N" (configurable name) whose properties lazily load Node.js builtins.
+ * Supports both original names (child_process) and camelCase variants (childProcess).
+ *
+ * @param {object} [options]
+ * @param {string} [options.name="N"]
+ * @param {string[]} [options.allowlist]
+ * @param {(id: string) => any} [options.require]
+ * @param {boolean} [options.overwrite=false]
+ * @param {boolean} [options.preventExtensions=true]
+ */
+function installGlobalBuiltinModules(options = {}) {
+  const {
+    name = 'N',
+    allowlist = builtinNames,
+    require: requireOpt,
+    overwrite = false,
+    preventExtensions = true,
+  } = options
+
+  const existing = globalThis[name]
+  if (existing && !overwrite) return existing
+
+  const requireFn = requireOpt ?? require
+
+  const N = Object.create(null)
+
+  for (const propName of allowlist) {
+    const moduleSpecifier = builtinsMap[propName]
+    if (!moduleSpecifier) {
+      // Unknown name - skip silently
+      continue
+    }
+    defineLazy(N, propName, () => requireFn(moduleSpecifier))
+  }
+
+  Object.defineProperty(N, '__allowlist', {
+    enumerable: false,
+    configurable: false,
+    writable: false,
+    value: Object.freeze([...allowlist]),
+  })
+
+  if (preventExtensions) Object.preventExtensions(N)
+
+  Object.defineProperty(globalThis, name, {
+    value: N,
+    writable: false,
+    configurable: true,
+    enumerable: false,
+  })
+
+  return N
+}
+
+module.exports = { installGlobalBuiltinModules }

package/install.js

@@ -0,0 +1,73 @@
+import { createRequire } from 'node:module'
+import { builtinsMap, builtinNames } from './generated/builtins-map.js'
+
+function defineLazy(obj, prop, load) {
+  Object.defineProperty(obj, prop, {
+    enumerable: true,
+    configurable: true,
+    get() {
+      const value = load()
+      // Replace getter with a plain, non-configurable value property.
+      Object.defineProperty(obj, prop, {
+        enumerable: true,
+        configurable: false,
+        writable: false,
+        value,
+      })
+      return value
+    },
+  })
+}
+
+/**
+ * Installs a global "N" (configurable name) whose properties lazily load Node.js builtins.
+ * Supports both original names (child_process) and camelCase variants (childProcess).
+ *
+ * @param {import('./generated/types.js').InstallGlobalBuiltinModulesOptions} [options]
+ * @returns {import('./generated/types.js').GlobalBuiltinModules}
+ */
+export function installGlobalBuiltinModules(options = {}) {
+  const {
+    name = 'N',
+    allowlist = builtinNames,
+    require: requireOpt,
+    overwrite = false,
+    preventExtensions = true,
+  } = options
+
+  const existing = globalThis[name]
+  if (existing && !overwrite) return existing
+
+  // createRequire works in ESM; user can also supply a custom loader.
+  const requireFn = requireOpt ?? createRequire(import.meta.url)
+
+  const N = Object.create(null)
+
+  for (const propName of allowlist) {
+    const moduleSpecifier = builtinsMap[propName]
+    if (!moduleSpecifier) {
+      // Unknown name - skip silently (user may have passed invalid allowlist entry)
+      continue
+    }
+    defineLazy(N, propName, () => requireFn(moduleSpecifier))
+  }
+
+  // Expose the allowlist for debugging/introspection
+  Object.defineProperty(N, '__allowlist', {
+    enumerable: false,
+    configurable: false,
+    writable: false,
+    value: Object.freeze([...allowlist]),
+  })
+
+  if (preventExtensions) Object.preventExtensions(N)
+
+  Object.defineProperty(globalThis, name, {
+    value: N,
+    writable: false,
+    configurable: true, // allow uninstall/replace in tests or alternate installers
+    enumerable: false,
+  })
+
+  return N
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "global-builtin-modules",
+  "version": "0.0.0",
+  "description": "Installs a global with lazy-loaded Node.js builtin modules",
+  "author": "Aaron Casanova <aaronccasanova@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    },
+    "./install": {
+      "types": "./index.d.ts",
+      "import": "./install.js",
+      "require": "./install.cjs"
+    },
+    "./uninstall": {
+      "types": "./index.d.ts",
+      "import": "./uninstall.js",
+      "require": "./uninstall.cjs"
+    }
+  },
+  "files": [
+    "generated",
+    "index.js",
+    "index.cjs",
+    "install.js",
+    "install.cjs",
+    "uninstall.js",
+    "uninstall.cjs",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "generate": "node scripts/generate-builtins.js",
+    "prepublishOnly": "npm run generate"
+  },
+  "sideEffects": true,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "node",
+    "builtins",
+    "builtin",
+    "lazy",
+    "global",
+    "loader"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.0.9"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aaronccasanova/global-builtin-modules.git"
+  },
+  "homepage": "https://github.com/aaronccasanova/global-builtin-modules#readme",
+  "bugs": {
+    "url": "https://github.com/aaronccasanova/global-builtin-modules/issues"
+  }
+}

package/uninstall.cjs

@@ -0,0 +1,5 @@
+function uninstallGlobalBuiltinModules(name = 'N') {
+  return delete globalThis[name]
+}
+
+module.exports = { uninstallGlobalBuiltinModules }

package/uninstall.js

@@ -0,0 +1,8 @@
+/**
+ * Removes the global created by installGlobalBuiltinModules (default "N").
+ * @param {string} [name="N"]
+ * @returns {boolean} true if removed, false otherwise
+ */
+export function uninstallGlobalBuiltinModules(name = 'N') {
+  return delete globalThis[name]
+}