feat(promises): add withResolvers helper bound to native when available

Exposes the TC39 Promise.withResolvers API
(https://tc39.es/ecma262/#sec-promise.withResolvers) as a first-class
export so fleet code bases can retire the manual
`let resolve; const p = new Promise(r => { resolve = r })` dance.

- Bound to native `Promise.withResolvers` when `typeof === 'function'`
  (stable in Node 20.12+ / 21+ / 22+; V8 ≥ 12.0). Binds to `Promise`
  so destructured imports don't lose `this`.
- Fallback implementation captures resolvers via closure and returns
  a spec-equivalent `{ promise, resolve, reject }` whose own data
  properties are enumerable on `Object.prototype` — matches §27.2.4.9
  steps 3-6 (`OrdinaryObjectCreate` + `CreateDataPropertyOrThrow`).
- Public `PromiseWithResolvers<T>` interface documents the return
  shape for external consumers.

12 new unit tests cover: function identity, return shape, resolve /
reject roundtrip, thenable adoption (resolved + rejected), settle-
once semantics, deferred resolution, independence across calls, and
spec-shape assertions (`Object.prototype` prototype + enumerable
own properties). Fallback verified by deleting the native method on
the built dist and re-running: identical behavior on every assertion.

Author: jdalton

src/promises.ts

@@ -759,3 +759,69 @@ export function resolveRetryOptions(
 
   return options ? { ...defaults, ...options } : defaults
 }
+
+/**
+ * Shape returned by {@link withResolvers}: a fresh pending promise plus
+ * the `resolve` / `reject` handles that settle it.
+ *
+ * Matches the spec return-shape exactly
+ * ([ECMA-262 §27.2.4.9](https://tc39.es/ecma262/#sec-promise.withResolvers)).
+ */
+export interface PromiseWithResolvers<T> {
+  /** The pending promise. */
+  promise: Promise<T>
+  /** Resolves {@link promise} with the given value (or thenable). */
+  resolve: (value: T | PromiseLike<T>) => void
+  /** Rejects {@link promise} with the given reason. */
+  reject: (reason?: unknown) => void
+}
+
+const maybeNativeWithResolvers = (
+  Promise as unknown as {
+    withResolvers?: unknown
+  }
+).withResolvers
+
+/**
+ * Create a pending promise together with its `resolve` and `reject`
+ * handles as first-class values, per
+ * [ECMA-262 §27.2.4.9](https://tc39.es/ecma262/#sec-promise.withResolvers).
+ *
+ * Bound to native `Promise.withResolvers` when available (Node 20.12+ /
+ * 21+ / 22+; V8 ≥ 12.0); otherwise falls back to a spec-equivalent
+ * `new Promise(executor)` implementation that captures the handles via
+ * closure. The returned object always has own data properties `promise`,
+ * `resolve`, `reject` on `Object.prototype` — writable, enumerable, and
+ * configurable — matching the spec's `CreateDataPropertyOrThrow` steps.
+ *
+ * Use this instead of the manual
+ * `let resolve; const p = new Promise(r => { resolve = r })` dance for
+ * deferred-resolution patterns (event-driven bridges, adapter layers,
+ * handshake signaling) where the settle path lives outside the executor.
+ *
+ * @example
+ * ```typescript
+ * const { promise, resolve, reject } = withResolvers<string>()
+ * emitter.once('ready', () => resolve('ok'))
+ * emitter.once('error', err => reject(err))
+ * const result = await promise
+ * ```
+ */
+export const withResolvers: <T>() => PromiseWithResolvers<T> =
+  typeof maybeNativeWithResolvers === 'function'
+    ? // Bind so callers who destructure the export don't lose `this`.
+      ((maybeNativeWithResolvers as () => PromiseWithResolvers<unknown>).bind(
+        Promise,
+      ) as <T>() => PromiseWithResolvers<T>)
+    : <T>(): PromiseWithResolvers<T> => {
+        // Fallback: capture resolvers via closure. The `!` asserts hold
+        // because Promise's executor runs synchronously, so both handles
+        // are assigned before the constructor returns.
+        let resolve!: (value: T | PromiseLike<T>) => void
+        let reject!: (reason?: unknown) => void
+        const promise = new Promise<T>((res, rej) => {
+          resolve = res
+          reject = rej
+        })
+        return { promise, resolve, reject }
+      }

test/unit/promises.test.mts

@@ -19,6 +19,7 @@ import {
   pFilterChunk,
   pRetry,
   resolveRetryOptions,
+  withResolvers,
 } from '@socketsecurity/lib/promises'
 import { describe, expect, it, vi } from 'vitest'
 
@@ -1048,4 +1049,98 @@ describe('promises', () => {
       expect(options.retries).toBe(0)
     })
   })
+
+  describe('withResolvers', () => {
+    // Spec: https://tc39.es/ecma262/#sec-promise.withResolvers
+    // These tests exercise the feature-detect binding. On Node 20.12+ /
+    // 22+ the export is bound to native Promise.withResolvers; on older
+    // engines it's our fallback. Both paths must satisfy the spec.
+
+    it('is a function', () => {
+      expect(typeof withResolvers).toBe('function')
+    })
+
+    it('returns an object with promise, resolve, reject', () => {
+      const d = withResolvers<number>()
+      expect(d.promise).toBeInstanceOf(Promise)
+      expect(typeof d.resolve).toBe('function')
+      expect(typeof d.reject).toBe('function')
+    })
+
+    it('resolves the promise with the provided value', async () => {
+      const { promise, resolve } = withResolvers<string>()
+      resolve('hello')
+      await expect(promise).resolves.toBe('hello')
+    })
+
+    it('rejects the promise with the provided reason', async () => {
+      const { promise, reject } = withResolvers<number>()
+      const err = new Error('boom')
+      reject(err)
+      await expect(promise).rejects.toBe(err)
+    })
+
+    it('adopts a thenable passed to resolve', async () => {
+      const { promise, resolve } = withResolvers<number>()
+      resolve(Promise.resolve(42))
+      await expect(promise).resolves.toBe(42)
+    })
+
+    it('rejects when a rejected thenable is passed to resolve', async () => {
+      const { promise, resolve } = withResolvers<number>()
+      const err = new Error('inner')
+      resolve(Promise.reject(err))
+      await expect(promise).rejects.toBe(err)
+    })
+
+    it('settles exactly once — later resolve() calls are ignored', async () => {
+      const { promise, resolve } = withResolvers<string>()
+      resolve('first')
+      resolve('second')
+      await expect(promise).resolves.toBe('first')
+    })
+
+    it('settles exactly once — reject after resolve is ignored', async () => {
+      const { promise, resolve, reject } = withResolvers<string>()
+      resolve('ok')
+      reject(new Error('late'))
+      await expect(promise).resolves.toBe('ok')
+    })
+
+    it('supports deferred resolution from outside the executor', async () => {
+      // The point of withResolvers: settle from code that doesn't own the
+      // executor. Here an event-style callback closes over `resolve`.
+      const { promise, resolve } = withResolvers<string>()
+      setTimeout(() => resolve('fired'), 0)
+      await expect(promise).resolves.toBe('fired')
+    })
+
+    it('each call returns a fresh, independent capability', async () => {
+      const a = withResolvers<number>()
+      const b = withResolvers<number>()
+      expect(a.promise).not.toBe(b.promise)
+      expect(a.resolve).not.toBe(b.resolve)
+      a.resolve(1)
+      b.resolve(2)
+      await expect(a.promise).resolves.toBe(1)
+      await expect(b.promise).resolves.toBe(2)
+    })
+
+    // Spec §27.2.4.9 step 3: `OrdinaryObjectCreate(%Object.prototype%)`.
+    // The returned object is a plain object, not a Promise / subclass.
+    it('returned object has Object.prototype as its prototype', () => {
+      const d = withResolvers<number>()
+      expect(Object.getPrototypeOf(d)).toBe(Object.prototype)
+    })
+
+    // Spec §27.2.4.9 steps 4-6: properties created via
+    // `CreateDataPropertyOrThrow` — writable, enumerable, configurable.
+    it('promise/resolve/reject are own enumerable properties', () => {
+      const d = withResolvers<number>()
+      const keys = Object.keys(d)
+      expect(keys).toContain('promise')
+      expect(keys).toContain('resolve')
+      expect(keys).toContain('reject')
+    })
+  })
 })