/**

* @file Accessors for `node:module` that work across runtimes. Ambient

* `require` is bound in CommonJS but unbound in ESM and inside

* ahead-of-time-compiled package modules (e.g. Perry), where reading it

* throws. And Perry's `require('module')` value omits `isBuiltin`. So instead

* of the ambient `require('module')` lazy-loader, `isBuiltin`/`createRequire`

* are imported as named values from the bare `module` specifier — which

* resolves on Node and Perry, and which browser bundlers can stub via

* resolve.fallback (a `node:` prefix would throw UnhandledSchemeError

* there).

* `require` is DIRECTORY-SPECIFIC: `createRequire(base)` resolves relative

* specifiers (`./x`, `../y`) from `base`'s directory. For builtins and bare

* packages that's irrelevant since they resolve the same anywhere, so the

* cached `getRequire` / `requireBuiltin` bind to THIS file. A RELATIVE

* specifier must resolve from the CALLER's directory, so use `requireFrom`

* with the caller's `import.meta.url` — binding such a load to this file

* would resolve it against `src/node/` instead. Bundled, every module

* collapses to one base and either works; unbundled (e.g. AOT-compiled from

* source), each module sits at its own nested path and the base matters.

*/

// Bare `module` is browser-stubbable via resolve.fallback / the browser

// field; a `node:` prefix breaks browser bundles. Named exports resolve on

// Node and Perry.

// oxlint-disable-next-line unicorn/prefer-node-protocol -- browser stub

import { createRequire, isBuiltin as nodeIsBuiltin } from 'module'

import type * as NodeModule from 'node:module'

import { IS_NODE } from '../constants/runtime.mjs'

let cachedModule: typeof NodeModule | undefined

let cachedRequire: ((id: string) => unknown) | undefined

/**

* Bind a working `require`. Ambient `require` exists in CommonJS; in ESM and

* ahead-of-time-compiled package modules it is unbound (reading it throws or

* yields undefined), so fall back to `createRequire`. Returns undefined off

* Node and in browsers, where neither is available.

*

* `fromUrl` sets the resolution base — pass a caller's `import.meta.url` to

* resolve that caller's RELATIVE specifiers. When omitted, the base is this

* file, which is correct only for builtins / bare packages (dir-independent).

* With `fromUrl` the ambient `require` is skipped: it is bound to THIS file, so

* it would resolve a relative specifier from the wrong directory.

*/

export function bindRequire(

fromUrl?: string | undefined,

): ((id: string) => unknown) | undefined {

if (!IS_NODE) {

return undefined

}

if (!fromUrl && typeof require === 'function') {

return require

}

if (typeof createRequire === 'function') {

try {

return createRequire(fromUrl ?? import.meta.url) as (

id: string,

) => unknown

} catch {

return undefined

}

}

return undefined

}

/**

* Returns `node:module` loaded through the bound `require`, or undefined off

* Node. Cached across calls.

*/

export function getNodeModule(): typeof NodeModule {

return (cachedModule ??= requireBuiltin('module') as typeof NodeModule)

}

/**

* Returns a working `require` bound to THIS file, binding one on first call

* (see bindRequire). Cached across calls; undefined off Node / in browsers.

*

* For builtins and bare packages only — the resolution base is this file, so a

* relative specifier would resolve from `src/node/`. Use `requireFrom` for

* relative loads.

*/

export function getRequire(): ((id: string) => unknown) | undefined {

if (cachedRequire === undefined) {

cachedRequire = bindRequire()

}

return cachedRequire

}

/**

* Is `name` a Node built-in module? Resolved from the statically-imported

* `isBuiltin`, so it works on Node and on ahead-of-time-compiled binaries

* (Perry), where ambient `require('module')` would lack `isBuiltin`. Returns

* false in browsers, where the bare `module` import is stubbed away.

*

* Single source of truth for "is this a Node builtin?" probes across socket-lib

* (used by the smol-binding loaders to gate their `node:smol-*` loads).

*/

export function isNodeBuiltin(name: string): boolean {

if (!IS_NODE || typeof nodeIsBuiltin !== 'function') {

return false

}

return nodeIsBuiltin(name)

}

/**

* Load a built-in module by *computed* specifier through the bound `require`

* (see getRequire). The specifier is a parameter — never a literal at the call

* site — so browser bundlers neither walk nor bundle it. Returns undefined

* where no `require` can be bound.

*

* Builtins / bare packages only (dir-independent); for a relative specifier use

* `requireFrom`. Used by `getNodeModule` for `node:module`, and by the

* smol-binding loaders for the optional `node:smol-*` native bindings (gated

* behind `isNodeBuiltin`, true only on socket-btm's smol Node binary).

*/

export function requireBuiltin(specifier: string): unknown {

const req = getRequire()

if (req) {

return req(specifier)

}

return undefined

}

/**

* Load a module by specifier from a CALLER-supplied base (its

* `import.meta.url`). Use this for RELATIVE specifiers (`./x`, `../y`), whose

* resolution depends on the caller's directory — `requireBuiltin` binds to this

* file and would resolve them from `src/node/`. Not cached: the binding is

* per-caller. Returns undefined where no `require` can be bound.

*/

export function requireFrom(fromUrl: string, specifier: string): unknown {

const req = bindRequire(fromUrl)

if (req) {

return req(specifier)

}

return undefined

}