@types/node 24.2.1 → 24.3.1

node/test.d.ts

@@ -1707,6 +1707,46 @@ declare module "node:test" {
              * @param options Optional configuration options for the mock module.
              */
             module(specifier: string, options?: MockModuleOptions): MockModuleContext;
+            /**
+             * Creates a mock for a property value on an object. This allows you to track and control access to a specific property,
+             * including how many times it is read (getter) or written (setter), and to restore the original value after mocking.
+             *
+             * ```js
+             * test('mocks a property value', (t) => {
+             *   const obj = { foo: 42 };
+             *   const prop = t.mock.property(obj, 'foo', 100);
+             *
+             *   assert.strictEqual(obj.foo, 100);
+             *   assert.strictEqual(prop.mock.accessCount(), 1);
+             *   assert.strictEqual(prop.mock.accesses[0].type, 'get');
+             *   assert.strictEqual(prop.mock.accesses[0].value, 100);
+             *
+             *   obj.foo = 200;
+             *   assert.strictEqual(prop.mock.accessCount(), 2);
+             *   assert.strictEqual(prop.mock.accesses[1].type, 'set');
+             *   assert.strictEqual(prop.mock.accesses[1].value, 200);
+             *
+             *   prop.mock.restore();
+             *   assert.strictEqual(obj.foo, 42);
+             * });
+             * ```
+             * @since v24.3.0
+             * @param object The object whose value is being mocked.
+             * @param propertyName The identifier of the property on `object` to mock.
+             * @param value An optional value used as the mock value
+             * for `object[propertyName]`. **Default:** The original property value.
+             * @returns A proxy to the mocked object. The mocked object contains a
+             * special `mock` property, which is an instance of [`MockPropertyContext`][], and
+             * can be used for inspecting and changing the behavior of the mocked property.
+             */
+            property<
+                MockedObject extends object,
+                PropertyName extends keyof MockedObject,
+            >(
+                object: MockedObject,
+                property: PropertyName,
+                value?: MockedObject[PropertyName],
+            ): MockedObject & { mock: MockPropertyContext<MockedObject[PropertyName]> };
             /**
              * This function restores the default behavior of all mocks that were previously
              * created by this `MockTracker` and disassociates the mocks from the `MockTracker` instance. Once disassociated, the mocks can still be used, but the `MockTracker` instance can no longer be
@@ -1876,6 +1916,70 @@ declare module "node:test" {
              */
             restore(): void;
         }
+        /**
+         * @since v24.3.0
+         */
+        class MockPropertyContext<PropertyType = any> {
+            /**
+             * A getter that returns a copy of the internal array used to track accesses (get/set) to
+             * the mocked property. Each entry in the array is an object with the following properties:
+             */
+            readonly accesses: Array<{
+                type: "get" | "set";
+                value: PropertyType;
+                stack: Error;
+            }>;
+            /**
+             * This function returns the number of times that the property was accessed.
+             * This function is more efficient than checking `ctx.accesses.length` because
+             * `ctx.accesses` is a getter that creates a copy of the internal access tracking array.
+             * @returns The number of times that the property was accessed (read or written).
+             */
+            accessCount(): number;
+            /**
+             * This function is used to change the value returned by the mocked property getter.
+             * @param value The new value to be set as the mocked property value.
+             */
+            mockImplementation(value: PropertyType): void;
+            /**
+             * This function is used to change the behavior of an existing mock for a single
+             * invocation. Once invocation `onAccess` has occurred, the mock will revert to
+             * whatever behavior it would have used had `mockImplementationOnce()` not been
+             * called.
+             *
+             * The following example creates a mock function using `t.mock.property()`, calls the
+             * mock property, changes the mock implementation to a different value for the
+             * next invocation, and then resumes its previous behavior.
+             *
+             * ```js
+             * test('changes a mock behavior once', (t) => {
+             *   const obj = { foo: 1 };
+             *
+             *   const prop = t.mock.property(obj, 'foo', 5);
+             *
+             *   assert.strictEqual(obj.foo, 5);
+             *   prop.mock.mockImplementationOnce(25);
+             *   assert.strictEqual(obj.foo, 25);
+             *   assert.strictEqual(obj.foo, 5);
+             * });
+             * ```
+             * @param value The value to be used as the mock's
+             * implementation for the invocation number specified by `onAccess`.
+             * @param onAccess The invocation number that will use `value`. If
+             * the specified invocation has already occurred then an exception is thrown.
+             * **Default:** The number of the next invocation.
+             */
+            mockImplementationOnce(value: PropertyType, onAccess?: number): void;
+            /**
+             * Resets the access history of the mocked property.
+             */
+            resetAccesses(): void;
+            /**
+             * Resets the implementation of the mock property to its original behavior. The
+             * mock can still be used after calling this function.
+             */
+            restore(): void;
+        }
         interface MockTimersOptions {
             apis: ReadonlyArray<"setInterval" | "setTimeout" | "setImmediate" | "Date">;
             now?: number | Date | undefined;

node/ts5.6/index.d.ts

@@ -40,6 +40,12 @@
 
 // Definitions for Node.js modules that are not specific to any version of TypeScript:
 /// <reference path="../globals.d.ts" />
+/// <reference path="../web-globals/abortcontroller.d.ts" />
+/// <reference path="../web-globals/domexception.d.ts" />
+/// <reference path="../web-globals/events.d.ts" />
+/// <reference path="../web-globals/fetch.d.ts" />
+/// <reference path="../web-globals/navigator.d.ts" />
+/// <reference path="../web-globals/storage.d.ts" />
 /// <reference path="../assert.d.ts" />
 /// <reference path="../assert/strict.d.ts" />
 /// <reference path="../async_hooks.d.ts" />
@@ -55,7 +61,6 @@
 /// <reference path="../dns/promises.d.ts" />
 /// <reference path="../dns/promises.d.ts" />
 /// <reference path="../domain.d.ts" />
-/// <reference path="../dom-events.d.ts" />
 /// <reference path="../events.d.ts" />
 /// <reference path="../fs.d.ts" />
 /// <reference path="../fs/promises.d.ts" />

node/ts5.7/index.d.ts

@@ -40,6 +40,12 @@
 
 // Definitions for Node.js modules that are not specific to any version of TypeScript:
 /// <reference path="../globals.d.ts" />
+/// <reference path="../web-globals/abortcontroller.d.ts" />
+/// <reference path="../web-globals/domexception.d.ts" />
+/// <reference path="../web-globals/events.d.ts" />
+/// <reference path="../web-globals/fetch.d.ts" />
+/// <reference path="../web-globals/navigator.d.ts" />
+/// <reference path="../web-globals/storage.d.ts" />
 /// <reference path="../assert.d.ts" />
 /// <reference path="../assert/strict.d.ts" />
 /// <reference path="../async_hooks.d.ts" />
@@ -55,7 +61,6 @@
 /// <reference path="../dns/promises.d.ts" />
 /// <reference path="../dns/promises.d.ts" />
 /// <reference path="../domain.d.ts" />
-/// <reference path="../dom-events.d.ts" />
 /// <reference path="../events.d.ts" />
 /// <reference path="../fs.d.ts" />
 /// <reference path="../fs/promises.d.ts" />

node/url.d.ts

@@ -315,6 +315,17 @@ declare module "url" {
      * @return The fully-resolved platform-specific Node.js file path.
      */
     function fileURLToPath(url: string | URL, options?: FileUrlToPathOptions): string;
+    /**
+     * Like `url.fileURLToPath(...)` except that instead of returning a string
+     * representation of the path, a `Buffer` is returned. This conversion is
+     * helpful when the input URL contains percent-encoded segments that are
+     * not valid UTF-8 / Unicode sequences.
+     * @since v24.3.0
+     * @param url The file URL string or URL object to convert to a path.
+     * @returns The fully-resolved platform-specific Node.js file path
+     * as a `Buffer`.
+     */
+    function fileURLToPathBuffer(url: string | URL, options?: FileUrlToPathOptions): Buffer;
     /**
      * This function ensures that `path` is resolved absolutely, and that the URL
      * control characters are correctly encoded when converting into a File URL.

node/web-globals/abortcontroller.d.ts

@@ -0,0 +1,34 @@
+export {};
+
+type _AbortController = typeof globalThis extends { onmessage: any } ? {} : AbortController;
+interface AbortController {
+    readonly signal: AbortSignal;
+    abort(reason?: any): void;
+}
+
+type _AbortSignal = typeof globalThis extends { onmessage: any } ? {} : AbortSignal;
+interface AbortSignal extends EventTarget {
+    readonly aborted: boolean;
+    onabort: ((this: AbortSignal, ev: Event) => any) | null;
+    readonly reason: any;
+    throwIfAborted(): void;
+}
+
+declare global {
+    interface AbortController extends _AbortController {}
+    var AbortController: typeof globalThis extends { onmessage: any; AbortController: infer T } ? T
+        : {
+            prototype: AbortController;
+            new(): AbortController;
+        };
+
+    interface AbortSignal extends _AbortSignal {}
+    var AbortSignal: typeof globalThis extends { onmessage: any; AbortSignal: infer T } ? T
+        : {
+            prototype: AbortSignal;
+            new(): AbortSignal;
+            abort(reason?: any): AbortSignal;
+            any(signals: AbortSignal[]): AbortSignal;
+            timeout(milliseconds: number): AbortSignal;
+        };
+}

node/web-globals/domexception.d.ts

@@ -0,0 +1,68 @@
+export {};
+
+type _DOMException = typeof globalThis extends { onmessage: any } ? {} : DOMException;
+interface DOMException extends Error {
+    readonly code: number;
+    readonly message: string;
+    readonly name: string;
+    readonly INDEX_SIZE_ERR: 1;
+    readonly DOMSTRING_SIZE_ERR: 2;
+    readonly HIERARCHY_REQUEST_ERR: 3;
+    readonly WRONG_DOCUMENT_ERR: 4;
+    readonly INVALID_CHARACTER_ERR: 5;
+    readonly NO_DATA_ALLOWED_ERR: 6;
+    readonly NO_MODIFICATION_ALLOWED_ERR: 7;
+    readonly NOT_FOUND_ERR: 8;
+    readonly NOT_SUPPORTED_ERR: 9;
+    readonly INUSE_ATTRIBUTE_ERR: 10;
+    readonly INVALID_STATE_ERR: 11;
+    readonly SYNTAX_ERR: 12;
+    readonly INVALID_MODIFICATION_ERR: 13;
+    readonly NAMESPACE_ERR: 14;
+    readonly INVALID_ACCESS_ERR: 15;
+    readonly VALIDATION_ERR: 16;
+    readonly TYPE_MISMATCH_ERR: 17;
+    readonly SECURITY_ERR: 18;
+    readonly NETWORK_ERR: 19;
+    readonly ABORT_ERR: 20;
+    readonly URL_MISMATCH_ERR: 21;
+    readonly QUOTA_EXCEEDED_ERR: 22;
+    readonly TIMEOUT_ERR: 23;
+    readonly INVALID_NODE_TYPE_ERR: 24;
+    readonly DATA_CLONE_ERR: 25;
+}
+
+declare global {
+    interface DOMException extends _DOMException {}
+    var DOMException: typeof globalThis extends { onmessage: any; DOMException: infer T } ? T
+        : {
+            prototype: DOMException;
+            new(message?: string, name?: string): DOMException;
+            new(message?: string, options?: { name?: string; cause?: unknown }): DOMException;
+            readonly INDEX_SIZE_ERR: 1;
+            readonly DOMSTRING_SIZE_ERR: 2;
+            readonly HIERARCHY_REQUEST_ERR: 3;
+            readonly WRONG_DOCUMENT_ERR: 4;
+            readonly INVALID_CHARACTER_ERR: 5;
+            readonly NO_DATA_ALLOWED_ERR: 6;
+            readonly NO_MODIFICATION_ALLOWED_ERR: 7;
+            readonly NOT_FOUND_ERR: 8;
+            readonly NOT_SUPPORTED_ERR: 9;
+            readonly INUSE_ATTRIBUTE_ERR: 10;
+            readonly INVALID_STATE_ERR: 11;
+            readonly SYNTAX_ERR: 12;
+            readonly INVALID_MODIFICATION_ERR: 13;
+            readonly NAMESPACE_ERR: 14;
+            readonly INVALID_ACCESS_ERR: 15;
+            readonly VALIDATION_ERR: 16;
+            readonly TYPE_MISMATCH_ERR: 17;
+            readonly SECURITY_ERR: 18;
+            readonly NETWORK_ERR: 19;
+            readonly ABORT_ERR: 20;
+            readonly URL_MISMATCH_ERR: 21;
+            readonly QUOTA_EXCEEDED_ERR: 22;
+            readonly TIMEOUT_ERR: 23;
+            readonly INVALID_NODE_TYPE_ERR: 24;
+            readonly DATA_CLONE_ERR: 25;
+        };
+}

node/{dom-events.d.ts → web-globals/events.d.ts}

@@ -1,37 +1,61 @@
-// Make this a module
 export {};
 
-// Conditional type aliases, which are later merged into the global scope.
-// Will either be empty if the relevant web library is already present, or the @types/node definition otherwise.
+interface AddEventListenerOptions extends EventListenerOptions {
+    once?: boolean;
+    passive?: boolean;
+    signal?: AbortSignal;
+}
 
-type __Event = typeof globalThis extends { onmessage: any } ? {} : Event;
+type _CustomEvent<T = any> = typeof globalThis extends { onmessage: any } ? {} : CustomEvent<T>;
+interface CustomEvent<T = any> extends Event {
+    readonly detail: T;
+}
+
+interface CustomEventInit<T = any> extends EventInit {
+    detail?: T;
+}
+
+type _Event = typeof globalThis extends { onmessage: any } ? {} : Event;
 interface Event {
     readonly bubbles: boolean;
     cancelBubble: boolean;
     readonly cancelable: boolean;
     readonly composed: boolean;
-    composedPath(): [EventTarget?];
     readonly currentTarget: EventTarget | null;
     readonly defaultPrevented: boolean;
     readonly eventPhase: 0 | 2;
-    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
     readonly isTrusted: boolean;
-    preventDefault(): void;
-    readonly returnValue: boolean;
+    returnValue: boolean;
     readonly srcElement: EventTarget | null;
-    stopImmediatePropagation(): void;
-    stopPropagation(): void;
     readonly target: EventTarget | null;
     readonly timeStamp: number;
     readonly type: string;
+    composedPath(): [EventTarget?];
+    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+    preventDefault(): void;
+    stopImmediatePropagation(): void;
+    stopPropagation(): void;
 }
 
-type __CustomEvent<T = any> = typeof globalThis extends { onmessage: any } ? {} : CustomEvent<T>;
-interface CustomEvent<T = any> extends Event {
-    readonly detail: T;
+interface EventInit {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+}
+
+interface EventListener {
+    (evt: Event): void;
+}
+
+interface EventListenerObject {
+    handleEvent(object: Event): void;
+}
+
+interface EventListenerOptions {
+    capture?: boolean;
 }
 
-type __EventTarget = typeof globalThis extends { onmessage: any } ? {} : EventTarget;
+type _EventTarget = typeof globalThis extends { onmessage: any } ? {} : EventTarget;
 interface EventTarget {
     addEventListener(
         type: string,
@@ -46,51 +70,22 @@ interface EventTarget {
     ): void;
 }
 
-interface EventInit {
-    bubbles?: boolean;
-    cancelable?: boolean;
-    composed?: boolean;
-}
-
-interface CustomEventInit<T = any> extends EventInit {
-    detail?: T;
-}
-
-interface EventListenerOptions {
-    capture?: boolean;
-}
-
-interface AddEventListenerOptions extends EventListenerOptions {
-    once?: boolean;
-    passive?: boolean;
-    signal?: AbortSignal;
-}
-
-interface EventListener {
-    (evt: Event): void;
-}
-
-interface EventListenerObject {
-    handleEvent(object: Event): void;
-}
-
-// Merge conditional interfaces into global scope, and conditionally declare global constructors.
 declare global {
-    interface Event extends __Event {}
-    var Event: typeof globalThis extends { onmessage: any; Event: infer T } ? T
-        : {
-            prototype: Event;
-            new(type: string, eventInitDict?: EventInit): Event;
-        };
-
-    interface CustomEvent<T = any> extends __CustomEvent<T> {}
+    interface CustomEvent<T = any> extends _CustomEvent<T> {}
     var CustomEvent: typeof globalThis extends { onmessage: any; CustomEvent: infer T } ? T
         : {
             prototype: CustomEvent;
             new<T>(type: string, eventInitDict?: CustomEventInit<T>): CustomEvent<T>;
         };
 
-    interface EventTarget extends __EventTarget {}
+    interface Event extends _Event {}
+    var Event: typeof globalThis extends { onmessage: any; Event: infer T } ? T
+        : {
+            prototype: Event;
+            new(type: string, eventInitDict?: EventInit): Event;
+        };
+
+    interface EventTarget extends _EventTarget {}
     var EventTarget: typeof globalThis extends { onmessage: any; EventTarget: infer T } ? T
         : {
             prototype: EventTarget;

node/web-globals/fetch.d.ts

@@ -0,0 +1,50 @@
+export {};
+
+import * as undici from "undici-types";
+
+type _CloseEvent = typeof globalThis extends { onmessage: any } ? {} : undici.CloseEvent;
+type _EventSource = typeof globalThis extends { onmessage: any } ? {} : undici.EventSource;
+type _FormData = typeof globalThis extends { onmessage: any } ? {} : undici.FormData;
+type _Headers = typeof globalThis extends { onmessage: any } ? {} : undici.Headers;
+type _MessageEvent = typeof globalThis extends { onmessage: any } ? {} : undici.MessageEvent;
+type _Request = typeof globalThis extends { onmessage: any } ? {} : undici.Request;
+type _RequestInit = typeof globalThis extends { onmessage: any } ? {} : undici.RequestInit;
+type _Response = typeof globalThis extends { onmessage: any } ? {} : undici.Response;
+type _ResponseInit = typeof globalThis extends { onmessage: any } ? {} : undici.ResponseInit;
+type _WebSocket = typeof globalThis extends { onmessage: any } ? {} : undici.WebSocket;
+
+declare global {
+    function fetch(
+        input: string | URL | Request,
+        init?: RequestInit,
+    ): Promise<Response>;
+
+    interface CloseEvent extends _CloseEvent {}
+    var CloseEvent: typeof globalThis extends { onmessage: any; CloseEvent: infer T } ? T : typeof undici.CloseEvent;
+
+    interface EventSource extends _EventSource {}
+    var EventSource: typeof globalThis extends { onmessage: any; EventSource: infer T } ? T : typeof undici.EventSource;
+
+    interface FormData extends _FormData {}
+    var FormData: typeof globalThis extends { onmessage: any; FormData: infer T } ? T : typeof undici.FormData;
+
+    interface Headers extends _Headers {}
+    var Headers: typeof globalThis extends { onmessage: any; Headers: infer T } ? T : typeof undici.Headers;
+
+    interface MessageEvent extends _MessageEvent {}
+    var MessageEvent: typeof globalThis extends { onmessage: any; MessageEvent: infer T } ? T
+        : typeof undici.MessageEvent;
+
+    interface Request extends _Request {}
+    var Request: typeof globalThis extends { onmessage: any; Request: infer T } ? T : typeof undici.Request;
+
+    interface RequestInit extends _RequestInit {}
+
+    interface Response extends _Response {}
+    var Response: typeof globalThis extends { onmessage: any; Response: infer T } ? T : typeof undici.Response;
+
+    interface ResponseInit extends _ResponseInit {}
+
+    interface WebSocket extends _WebSocket {}
+    var WebSocket: typeof globalThis extends { onmessage: any; WebSocket: infer T } ? T : typeof undici.WebSocket;
+}

node/web-globals/navigator.d.ts

@@ -0,0 +1,22 @@
+export {};
+
+// lib.webworker has `WorkerNavigator` rather than `Navigator`, so conditionals use `onabort` instead of `onmessage`
+type _Navigator = typeof globalThis extends { onabort: any } ? {} : Navigator;
+interface Navigator {
+    readonly hardwareConcurrency: number;
+    readonly language: string;
+    readonly languages: readonly string[];
+    readonly platform: string;
+    readonly userAgent: string;
+}
+
+declare global {
+    interface Navigator extends _Navigator {}
+    var Navigator: typeof globalThis extends { onabort: any; Navigator: infer T } ? T : {
+        prototype: Navigator;
+        new(): Navigator;
+    };
+
+    // Needs conditional inference for lib.dom and lib.webworker compatibility
+    var navigator: typeof globalThis extends { onmessage: any; navigator: infer T } ? T : Navigator;
+}

node/web-globals/storage.d.ts

@@ -0,0 +1,24 @@
+export {};
+
+// These interfaces are absent from lib.webworker, so the conditionals use `onabort` rather than `onmessage`
+type _Storage = typeof globalThis extends { onabort: any } ? {} : Storage;
+interface Storage {
+    readonly length: number;
+    clear(): void;
+    getItem(key: string): string | null;
+    key(index: number): string | null;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+    [key: string]: any;
+}
+
+declare global {
+    interface Storage extends _Storage {}
+    var Storage: typeof globalThis extends { onabort: any; Storage: infer T } ? T : {
+        prototype: Storage;
+        new(): Storage;
+    };
+
+    var localStorage: Storage;
+    var sessionStorage: Storage;
+}