Skip to content

node:v8: implement promiseHooks lifecycle callbacks #3139

Description

@andrewtdiz

Summary

v8.promiseHooks should expose promise lifecycle callbacks through onInit, onBefore, onAfter, onSettled, and createHook. Perry currently has no public node:v8 namespace implementation for this promise lifecycle surface.

Node Behavior

A minimal Node probe shows the observable hook contract:

const v8 = require("node:v8");
const events = [];
const stops = [
  v8.promiseHooks.onInit((promise, parent) => events.push(["init", promise instanceof Promise, parent instanceof Promise])),
  v8.promiseHooks.onBefore((promise) => events.push(["before", promise instanceof Promise])),
  v8.promiseHooks.onAfter((promise) => events.push(["after", promise instanceof Promise])),
  v8.promiseHooks.onSettled((promise) => events.push(["settled", promise instanceof Promise])),
];
Promise.resolve(21).then(v => v + 1).then(v => events.push(["result", v]));
setTimeout(() => { console.log(events); stops.forEach(stop => stop()); }, 20);

Observed on Node v25.9.0: each on* method returns a function-valued stop handle; callbacks receive Promise objects during promise creation/execution/settlement; after calling the stop handles, later promises no longer trigger those callbacks. promiseHooks.createHook({ init, before, after, settled }) returns a function-valued stop handle. Missing or non-callable hook callbacks throw TypeError ERR_INVALID_ARG_TYPE for covered cases.

Perry Behavior

docs/runtime-parity.md marks v8.promiseHooks.onInit, onSettled, onBefore, onAfter, and createHook missing. docs/runtime-parity-gaps.md tracks node:v8 as a whole-module gap, source search found no public node:v8 promise-hook implementation, and there is no dedicated V8 parity fixture in this checkout.

Suggested PR Cut

Batch this with related issues in:
#3295 - node:v8: lifecycle callback namespaces parity cut

Good batch candidates:

Do not batch with:

Acceptance

  • A parity/regression test proves onInit, onBefore, onAfter, and onSettled invoke callbacks for a deterministic promise chain and return stop functions.
  • Calling stop functions prevents later callbacks for covered cases.
  • promiseHooks.createHook() installs the same callback set and returns a stop function.
  • Missing/non-callable callbacks throw Node-compatible errors for covered cases.
  • Related known-failure/docs/manifest entries are updated if touched.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions